Building and Running

This guide walks you through setting up Cluely for development, running it locally, and building production releases.

Prerequisites

Install Node.js

Install Node.js (v16 or later recommended)

# Check your Node version
node --version

Download from nodejs.org if needed.

Install Git

# Check if Git is installed
git --version

Choose an AI Provider

You’ll need either:Option A: Google Gemini (Cloud AI)

Get API key from Google AI Studio
Fast, powerful, works immediately
Sends data to Google servers

Option B: Ollama (Local AI)

Install from ollama.ai
100% private, runs on your machine
Requires ~4GB+ RAM

Clone and Install

git clone https://github.com/ibttf/interview-coder-frontend.git
cd interview-coder-frontend

Sharp Build Issues: Sharp is an image processing library that sometimes fails to build. The --ignore-scripts approach uses prebuilt binaries instead of compiling from source.

Environment Configuration

Create a .env file in the project root:

GEMINI_API_KEY=your_api_key_here
GEMINI_FALLBACK_API_KEY=backup_key_here  # Optional

Setting Up Ollama (Optional)

If using Ollama for private, local AI:

Install Ollama

Download and install from ollama.ai

Pull a Model

# Recommended models:
ollama pull llama3.2        # General purpose
ollama pull codellama       # Code-focused
ollama pull mistral         # Lightweight, fast

Start Ollama Server

ollama serve

Keep this running in a terminal. Ollama runs on http://localhost:11434 by default.

Verify Connection

curl http://localhost:11434/api/tags

Should return a JSON list of installed models.

Development Workflow

Running in Development Mode

The recommended way to run Cluely during development:

npm start

This single command:

Starts Vite dev server on http://localhost:5180
Waits for the server to be ready
Compiles Electron TypeScript code
Launches the Electron app with hot reload

How it works: The npm start script is an alias for npm run app:dev, which uses concurrently to run multiple processes:

"app:dev": "concurrently \"npm run dev -- --port 5180\" \"wait-on http://localhost:5180 && npm run electron:dev\""

Manual Development Steps

If you prefer to run processes separately:

Step-by-Step Manual Development

Terminal 1: Start Vite Dev Server

npm run dev

Starts React dev server with hot module replacement on port 5180.

Terminal 2: Watch Electron TypeScript

npm run watch

Compiles electron/*.ts files to dist-electron/ on changes.

Terminal 3: Run Electron

npm run electron:dev

Launches Electron with NODE_ENV=development.

Development Features

Hot Reload

React components reload instantly without restarting Electron.

DevTools

Uncomment in electron/WindowHelper.ts:105:

this.mainWindow.webContents.openDevTools()

Live Logs

All console.log statements from main process appear in your terminal.

URL Loading

Dev mode loads from http://localhost:5180 instead of file system.

Build Scripts Reference

{
  "scripts": {
    // Development
    "dev": "vite --port 5180",
    "electron:dev": "tsc -p electron/tsconfig.json && cross-env NODE_ENV=development electron .",
    "app:dev": "concurrently \"npm run dev\" \"wait-on http://localhost:5180 && npm run electron:dev\"",
    "start": "npm run app:dev",
    
    // Build
    "clean": "rimraf dist dist-electron",
    "build": "npm run clean && tsc && vite build",
    "electron:build": "tsc -p electron/tsconfig.json && cross-env NODE_ENV=production electron .",
    "app:build": "npm run build && electron-builder",
    "dist": "npm run app:build",
    
    // Utilities
    "watch": "tsc -p electron/tsconfig.json --watch",
    "postinstall": "cross-env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm rebuild sharp"
  }
}

Script Breakdown

Script	Description	When to Use
`npm start`	Full dev environment	Primary development command
`npm run dev`	Vite server only	Testing React components
`npm run electron:dev`	Electron only	Testing main process changes
`npm run watch`	Compile Electron on save	Advanced development
`npm run build`	Build React app	Before packaging
`npm run dist`	Full production build	Creating distributable app
`npm run clean`	Remove build artifacts	Clean slate before rebuild

Building for Production

Clean Previous Builds

npm run clean

Removes dist/ and dist-electron/ directories.

Build the Application

npm run dist

This command:

Runs npm run clean
Compiles TypeScript (tsc)
Builds React with Vite (vite build)
Compiles Electron TypeScript
Packages with electron-builder

Find Built Application

Built apps are in the release/ directory:

release/
├── Meeting Notes Coder-1.0.0.dmg         # Installer
├── Meeting Notes Coder-1.0.0-arm64.dmg   # Apple Silicon
└── Meeting Notes Coder-1.0.0-x64.dmg     # Intel

electron-builder Configuration

The build configuration in package.json controls how the app is packaged:

"build": {
  "appId": "com.electron.meeting-notes",
  "productName": "Meeting Notes Coder",
  "files": [
    "dist/**/*",
    "dist-electron/**/*",
    "package.json",
    "node_modules/**/*"
  ],
  "directories": {
    "output": "release",
    "buildResources": "assets"
  },
  "extraResources": [
    {
      "from": "assets/",
      "to": "assets/"
    }
  ],
  "mac": {
    "category": "public.app-category.productivity",
    "target": [{"target": "dmg", "arch": ["x64", "arm64"]}],
    "icon": "assets/icons/mac/icon.icns"
  },
  "win": {
    "target": [{"target": "nsis"}, {"target": "portable"}],
    "icon": "assets/icons/win/icon.ico"
  },
  "linux": {
    "target": [{"target": "AppImage"}, {"target": "deb"}],
    "category": "Office"
  }
}

Build Customization

Change App Name

Edit productName in the build section of package.json:

"productName": "Your App Name"

Add/Remove Build Targets

Modify the target arrays for each platform:

"mac": {
  "target": [
    {"target": "dmg", "arch": ["arm64"]},  // Apple Silicon only
    {"target": "zip", "arch": ["x64"]}     // Add zip format
  ]
}

Update App Icons

Place icons in assets/icons/:

macOS: assets/icons/mac/icon.icns (512x512 PNG converted to ICNS)
Windows: assets/icons/win/icon.ico (256x256 ICO format)
Linux: assets/icons/png/ (multiple PNG sizes)

Troubleshooting

Port Already in Use

Error: Port 5180 is already in use

Problem: Another instance of Vite is running.Solution:

# macOS/Linux: Find and kill the process
lsof -i :5180
kill -9 [PID]

# Windows: Find and kill the process
netstat -ano | findstr :5180
taskkill /PID [PID] /F

Or change the port in package.json:

"dev": "vite --port 5181"

Electron Won’t Start

White screen or blank window

Causes:

Vite server not running
Port mismatch between Vite and Electron
TypeScript compilation errors

Debug Steps:

# 1. Check if Vite is running
curl http://localhost:5180

# 2. Check Electron TypeScript compilation
npm run electron:dev
# Look for errors in output

# 3. Enable DevTools (uncomment in WindowHelper.ts)
this.mainWindow.webContents.openDevTools()

Build Failures

TypeScript errors during build

Problem: Type errors prevent compilation.Solution:

# Check for errors
npx tsc --noEmit

# For Electron code specifically
npx tsc -p electron/tsconfig.json --noEmit

electron-builder fails

Common issues:

Missing files: Ensure dist/ and dist-electron/ exist
```
npm run build
```
Permission errors: Run without sudo/admin
Disk space: electron-builder needs ~1GB+ free space
macOS code signing: Disable if not publishing
```
"mac": {
  "identity": null
}
```

Platform-Specific Issues

Windows: UI not loading

Problem: Renderer process can’t connect to main process.Solution: Ensure main field in package.json points to the correct file:

"main": "./dist-electron/main.js"

Linux: Window interaction problems

Problem: Can’t click or focus the window.Solution: Check window settings in electron/WindowHelper.ts:115-122:

if (process.platform === "linux") {
  this.mainWindow.setFocusable(true)
  if (this.mainWindow.setHasShadow) {
    this.mainWindow.setHasShadow(false)
  }
}

macOS: App won't quit

Problem: Pressing Cmd+Q doesn’t quit.Workaround:

Use Activity Monitor to force quit

Or add proper quit handler:

app.on('before-quit', () => {
  // Cleanup code
})

Ollama Issues

Ollama connection failed

Problem: Can’t connect to Ollama server.Debug Steps:

# 1. Check if Ollama is running
curl http://localhost:11434/api/tags

# 2. Start Ollama server
ollama serve

# 3. Verify model is pulled
ollama list

# 4. Pull model if needed
ollama pull llama3.2

Environment Variables Reference

Variable	Default	Description
`GEMINI_API_KEY`	-	Primary Google Gemini API key
`GEMINI_FALLBACK_API_KEY`	-	Backup API key for rate limits
`USE_OLLAMA`	`false`	Enable Ollama local AI
`OLLAMA_MODEL`	`llama3.2`	Ollama model to use
`OLLAMA_URL`	`http://localhost:11434`	Ollama server URL
`OPENROUTER_API_KEY`	-	OpenRouter API key
`OPENROUTER_MODEL`	`google/gemini-2.5-flash`	OpenRouter model
`K2_THINK_API_KEY`	-	K2 Think V2 API key
`USE_K2_THINK`	`false`	Enable K2 Think V2
`NODE_ENV`	`development`	Set to `production` for builds

Development Tips

Fast Iteration

Changes to React components reload instantly. For Electron changes, restart with npm run electron:dev.

Debug Main Process

Use console.log() in Electron code - output appears in the terminal where you ran npm start.

Debug Renderer

Enable DevTools in WindowHelper.ts or press Cmd+Option+I (may not work due to global shortcuts).

Test Multiple Platforms

Use VMs or dual-boot to test Windows/Linux builds if developing on macOS.

Next Steps

Contributing Guidelines

Ready to contribute? Read our contribution guidelines for code style, PR process, and more.

Contributing

​Prerequisites

​Clone and Install

​Environment Configuration

​Setting Up Ollama (Optional)

​Development Workflow

​Running in Development Mode

​Manual Development Steps

​Development Features

Hot Reload

DevTools

Live Logs

URL Loading

​Build Scripts Reference

​Script Breakdown

​Building for Production

​electron-builder Configuration

​Build Customization

​Troubleshooting

​Port Already in Use

​Electron Won’t Start

​Build Failures

​Platform-Specific Issues

​Ollama Issues

​Environment Variables Reference

​Development Tips

Fast Iteration

Debug Main Process

Debug Renderer

Test Multiple Platforms

​Next Steps

Contributing Guidelines

Build docs developers (and LLMs) love

Prerequisites

Clone and Install

Environment Configuration

Setting Up Ollama (Optional)

Development Workflow

Running in Development Mode

Manual Development Steps

Development Features

Build Scripts Reference

Script Breakdown

Building for Production

electron-builder Configuration

Build Customization

Troubleshooting

Port Already in Use

Electron Won’t Start

Build Failures

Platform-Specific Issues

Ollama Issues

Environment Variables Reference

Development Tips

Next Steps