Installing Cluely

This guide will walk you through installing Cluely on your machine. The process takes about 5-10 minutes depending on your AI provider choice.

Prerequisites

Before installing Cluely, ensure you have the following installed:

Node.js

Install Node.js version 16 or higher from nodejs.orgVerify installation:

node --version
npm --version

Git

Install Git from git-scm.comVerify installation:

git --version

AI Provider (Choose one)

Choose one of the following AI providers:

Gemini (Recommended for beginners)
Ollama (Recommended for privacy)
OpenRouter
K2 Think V2

Get a free API key from Google AI StudioPros:

Fastest setup (just need API key)
Best accuracy for complex tasks
Latest AI technology (Gemini 2.0 Flash)

Cons:

Requires internet connection
Data sent to Google servers
Usage costs apply (generous free tier)

Install Ollama from ollama.aiPull a model:

ollama pull llama3.2

Pros:

100% private - data never leaves your computer
No API costs
Works offline
Supports many models: llama3.2, codellama, mistral, etc.

Cons:

Requires more RAM (8GB+ recommended)
Slower than cloud providers
Requires Ollama service running

Installation steps

Clone the repository

git clone https://github.com/yourusername/free-cluely.git
cd free-cluely

Install dependencies

Standard installation
If you encounter Sharp/Python errors

npm install

If you see gyp ERR! find Python or Sharp build errors:

npx cross-env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install --ignore-scripts

This uses prebuilt Sharp binaries instead of building from source.

The installation automatically runs npm rebuild sharp via the postinstall script to ensure Sharp is properly configured.

Configure environment variables

Create a .env file in the root folder:

touch .env

Choose your AI provider configuration:

Gemini
Ollama
OpenRouter
K2 Think V2
Multiple providers

# Primary API key (required)
GEMINI_API_KEY=your_primary_api_key_here

# Fallback API key (optional but recommended)
GEMINI_FALLBACK_API_KEY=your_backup_api_key_here

The fallback API key is used automatically if the primary key hits rate limits or errors.

# Enable Ollama
USE_OLLAMA=true

# Model name (auto-detected if not set)
OLLAMA_MODEL=llama3.2

# Ollama server URL (optional, defaults to localhost)
OLLAMA_URL=http://localhost:11434

Make sure Ollama is running:

ollama serve

OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_MODEL=google/gemini-2.5-flash

Available models include:

google/gemini-2.5-flash
anthropic/claude-3-opus
openai/gpt-4-turbo
And many more at openrouter.ai/models

K2_THINK_API_KEY=your_k2_think_api_key_here
USE_K2_THINK=true

You can configure multiple providers and switch between them:

# Gemini (primary)
GEMINI_API_KEY=your_gemini_key_here

# Ollama (fallback/private mode)
USE_OLLAMA=false
OLLAMA_MODEL=llama3.2

# OpenRouter (alternative)
OPENROUTER_API_KEY=your_openrouter_key_here
OPENROUTER_MODEL=google/gemini-2.5-flash

The app uses the first available provider in this priority: K2 Think → OpenRouter → Gemini → Ollama

Start the application

Development mode (recommended for first run)
Production build

npm start

This command:

Starts the Vite dev server on port 5180
Waits for the server to be ready
Launches the Electron app

The dev server runs on port 5180. If this port is in use, you’ll need to free it first.

Build the application for your platform:

npm run dist

The built app will be in the release folder:

macOS: .dmg installer
Windows: .exe installer and portable .exe
Linux: .AppImage and .deb packages

Platform-specific notes

macOS
Windows
Linux

PermissionsOn first launch, macOS may ask for permissions:

Screen Recording: Required for screenshot functionality
Accessibility: Required for global shortcuts

Grant these in System Preferences → Security & Privacy → Privacy.Dock iconCluely hides from the dock by default (see electron/main.ts:320). Access it via:

Global shortcuts
Menu bar tray icon (shows as “IC”)

Closing the appUse Cmd + Q to quit properly. The close button (X) currently doesn’t work (known issue).

Windows 10/11 SupportCluely is fully tested on Windows 10 and 11 with:

Fixed UI loading issues
Improved error handling
Platform-specific window focus fixes

InstallationYou can choose between:

NSIS Installer: Traditional Windows installer with options
Portable: No installation required, run directly

Closing the appUse Ctrl + Q or Task Manager to quit. The close button (X) currently doesn’t work (known issue).

Tested distributions

Ubuntu 20.04+
Most major Linux distributions

Installation formats

AppImage: Universal Linux format, no installation needed
DEB: For Debian/Ubuntu-based systems

DependenciesMost dependencies are bundled, but ensure you have:

# Ubuntu/Debian
sudo apt-get install libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils

Window interactionFixed focusable settings ensure proper window interaction on Linux window managers.

Troubleshooting

Port 5180 already in use

If you see an error about port 5180:

# Find processes using port 5180
lsof -i :5180

# Kill the process (replace [PID] with the process ID)
kill [PID]

Sharp/Python build errors

If you see gyp ERR! find Python or Sharp-related errors during installation:

rm -rf node_modules package-lock.json
npx cross-env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install --ignore-scripts
npm rebuild sharp

Ollama not responding

If using Ollama and the app can’t connect:

Ensure Ollama is running:
```
ollama serve
```
Verify the model is pulled:
```
ollama list
```

Test Ollama directly:

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Hello"
}'

General installation issues

If you encounter other errors:

Clean installation

rm -rf node_modules package-lock.json
npm install

Verify environment variables

Check that your .env file is in the root directory and properly formatted.

Check logs

Run in development mode to see detailed logs:

npm start

App won’t quit

The close button (X) currently doesn’t work. This is a known issue.

Solutions:

Press Cmd + Q (macOS) or Ctrl + Q (Windows/Linux)
Use Activity Monitor (macOS) or Task Manager (Windows) to force quit “Interview Coder”
On Linux: pkill -f "interview-coder"

Next steps

Quick Start Guide

Learn how to take your first screenshot and get AI-powered insights

Get Started

Core Features

AI Providers

Guides

Installation

Installing Cluely

Prerequisites

Installation steps

Platform-specific notes

Troubleshooting

Port 5180 already in use

Sharp/Python build errors

Ollama not responding

General installation issues

App won’t quit

Next steps

Quick Start Guide

Build docs developers (and LLMs) love

Get Started

Core Features

AI Providers

Guides

​Installing Cluely

​Prerequisites

​Installation steps

​Platform-specific notes

​Troubleshooting

​Port 5180 already in use

​Sharp/Python build errors

​Ollama not responding

​General installation issues

​App won’t quit

​Next steps

Quick Start Guide

Build docs developers (and LLMs) love

Installing Cluely

Prerequisites

Installation steps

Platform-specific notes

Troubleshooting

Port 5180 already in use

Sharp/Python build errors

Ollama not responding

General installation issues

App won’t quit

Next steps