Quick Start Guide

This guide will get you from installation to your first AI-powered screenshot analysis in under 5 minutes.

Make sure you’ve completed the installation before proceeding.

Launch Cluely

Start the application

Open your terminal in the Cluely directory and run:

npm start

The application will:

Start the Vite development server on port 5180
Wait for the server to be ready
Launch the Electron window

You should see a translucent window appear on your screen.

Understand the interface

Cluely’s window is designed to be invisible and non-intrusive:

Translucent background: See through to your work underneath
Always on top: Stays visible across all applications
Compact design: Takes minimal screen space

The window starts in “queue” view, ready to capture screenshots.

Master the keyboard shortcuts

Cluely is designed to be controlled entirely with keyboard shortcuts for maximum efficiency.

Essential shortcuts

Shortcut	Action	Description
`Cmd/Ctrl + H`	Take screenshot	Captures screen and auto-processes with AI
`Cmd/Ctrl + Enter`	Get solution	Processes queued screenshots
`Cmd/Ctrl + B`	Toggle visibility	Show/hide the window
`Cmd/Ctrl + Shift + Space`	Show & center	Brings window to center of screen
`Cmd/Ctrl + R`	Reset	Clears all queues and cancels requests
`Cmd + Q` / `Ctrl + Q`	Quit	Closes the application

Window positioning

Shortcut	Action
`Cmd/Ctrl + Left`	Move window left
`Cmd/Ctrl + Right`	Move window right
`Cmd/Ctrl + Up`	Move window up
`Cmd/Ctrl + Down`	Move window down

All shortcuts are registered globally in electron/shortcuts.ts:11-106 and work even when Cluely isn’t focused.

Your first screenshot analysis

Position the window

Move Cluely’s window to a corner of your screen where it won’t obstruct your work:

# Use arrow key shortcuts
Cmd/Ctrl + Right  # Move to right side
Cmd/Ctrl + Down   # Move to bottom

Or hide it completely with Cmd/Ctrl + B - it will reappear automatically when you take a screenshot.

Open content to analyze

Open something you want help with:

A coding problem
An error message
A technical diagram
Documentation you don’t understand
A math equation
Interview question

Make sure it’s visible on your screen.

Capture the screenshot

Press Cmd + H (macOS) or Ctrl + H (Windows/Linux)What happens:

Cluely window automatically hides
Screenshot is captured (entire screen)
Window reappears with preview
AI automatically processes the image

The screenshot is saved temporarily and will be auto-deleted after processing for privacy.

View the AI analysis

Within seconds, you’ll see:

AI’s analysis of the screenshot
Explanations and insights
Code suggestions (if applicable)
Step-by-step solutions

The response is formatted with:

Syntax highlighting for code
Math rendering (via KaTeX)
Markdown formatting

Ask follow-up questions (optional)

Use the chat interface to:

Ask for clarification
Request different approaches
Dive deeper into specific parts
Get additional examples

The AI maintains context from your screenshot.

Example workflows

Debugging code errors

Capture the error

Open your IDE with the error message visible
Press Cmd/Ctrl + H to capture
AI analyzes the error and code context

Get the solution

AI provides:

Explanation of what’s wrong
Why the error occurred
How to fix it
Prevention tips

Take additional screenshots if needed

Press Cmd/Ctrl + H again to capture:

Related code files
Stack traces
Configuration files

All screenshots are processed together for full context.

Interview preparation

Capture the question

During a coding interview or practice:

Question appears on screen
Press Cmd/Ctrl + H to capture
AI analyzes the problem

Review the approach

AI provides:

Problem understanding
Solution approach
Code implementation
Time/space complexity
Edge cases to consider

Toggle visibility

Press Cmd/Ctrl + B to hide Cluely while you implement the solution, then show it again if you need hints.

Learning from presentations

Capture slides

During a presentation or lecture:

Interesting slide appears
Press Cmd/Ctrl + H to capture
Continue listening

Review later

After the presentation:

Open Cluely
View captured slides
Ask AI for:
- Concept explanations
- Additional examples
- Related resources
- Practice problems

Understanding the processing flow

When you take a screenshot, here’s what happens under the hood:

Screenshot capture

// electron/shortcuts.ts:18-36
globalShortcut.register("CommandOrControl+H", async () => {
  const screenshotPath = await this.appState.takeScreenshot()
  const preview = await this.appState.getImagePreview(screenshotPath)
  mainWindow.webContents.send("screenshot-taken", {
    path: screenshotPath,
    preview
  })
  await this.appState.processingHelper.processScreenshots()
})

The screenshot is:

Captured using screenshot-desktop library
Compressed with Sharp
Stored temporarily
Preview generated for UI

AI processing

// electron/ProcessingHelper.ts:24-48
const useOllama = process.env.USE_OLLAMA === "true"
const useK2Think = process.env.USE_K2_THINK === "true"
const openRouterApiKey = process.env.OPENROUTER_API_KEY
const apiKey = process.env.GEMINI_API_KEY

Provider priority:

K2 Think (if USE_K2_THINK=true)
OpenRouter (if OPENROUTER_API_KEY set)
Gemini (if GEMINI_API_KEY set)
Ollama (if USE_OLLAMA=true)

Response rendering

The AI response is rendered with:

react-markdown: Markdown parsing
react-syntax-highlighter: Code syntax highlighting
rehype-katex: Math equation rendering
remark-gfm: GitHub Flavored Markdown support

Cleanup

Screenshots are automatically deleted after processing to protect your privacy.

Advanced tips

Multiple screenshots for context

You can take multiple screenshots before processing to give the AI more context.

Take first screenshot: Cmd/Ctrl + H (auto-processes)
For additional context, manually queue more screenshots
All screenshots are analyzed together

Reset and start fresh

If you want to start a new analysis:

Cmd/Ctrl + R  # Resets queues and cancels ongoing requests

This:

Cancels any ongoing API requests
Clears screenshot queues
Resets view to initial state
Deletes screenshot metadata

Cluely adds a menu bar icon (macOS shows “IC”):

Double-click: Show and center window
Right-click menu:
- Show Interview Coder
- Toggle Window
- Take Screenshot (Cmd+H)
- Quit

Optimize for your use case

Privacy-focused
Performance-focused
Cost-optimized

Use Ollama for 100% local processing:

USE_OLLAMA=true
OLLAMA_MODEL=llama3.2

No data sent to cloud
Works offline
Requires more RAM

Use Gemini for fastest responses:

GEMINI_API_KEY=your_key_here
GEMINI_FALLBACK_API_KEY=backup_key_here

Fastest processing
Best accuracy
Requires internet
Fallback key prevents rate limit issues

Use Ollama for routine tasks, Gemini for complex ones:

# Both configured
USE_OLLAMA=true
OLLAMA_MODEL=llama3.2
GEMINI_API_KEY=your_key_here

Toggle in .env based on task complexity.

Troubleshooting common issues

Screenshot not capturing

On macOS, you need to grant Screen Recording permissions.

Go to: System Preferences → Security & Privacy → Privacy → Screen Recording Add and enable Cluely/Electron.

AI not responding

Check your configuration

Verify your .env file:

cat .env

Ensure API keys are set correctly (no extra spaces).

Verify provider status

Gemini
Ollama

Test API key:

curl -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Hello"}]}]}' \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=YOUR_API_KEY"

Check if Ollama is running:

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

If not running:

ollama serve

Check console logs

Open DevTools in the Electron window to see error messages.

Window positioning issues

If the window is off-screen or positioned oddly:

Cmd/Ctrl + Shift + Space  # Centers and shows window

What’s next?

Now that you’re familiar with the basics:

Explore AI Providers

Learn about different AI provider options and how to switch between them

Keyboard Shortcuts

Master all shortcuts for maximum productivity

Privacy & Security

Understand how Cluely protects your data

Advanced Configuration

Customize Cluely’s behavior and appearance

Remember: Press Cmd/Ctrl + Q to quit the application properly. The close button (X) doesn’t work yet.

Get Started

Core Features

AI Providers

Guides

Quick Start

Quick Start Guide

Launch Cluely

Master the keyboard shortcuts

Essential shortcuts

Window positioning

Your first screenshot analysis

Example workflows

Debugging code errors

Interview preparation

Learning from presentations

Understanding the processing flow

Advanced tips

Multiple screenshots for context

Reset and start fresh

Using the tray menu

Optimize for your use case

Troubleshooting common issues

Screenshot not capturing

AI not responding

Window positioning issues

What’s next?

Explore AI Providers

Keyboard Shortcuts

Privacy & Security

Advanced Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

AI Providers

Guides

​Quick Start Guide

​Launch Cluely

​Master the keyboard shortcuts

​Essential shortcuts

​Window positioning

​Your first screenshot analysis

​Example workflows

​Debugging code errors

​Interview preparation

​Learning from presentations

​Understanding the processing flow

​Advanced tips

​Multiple screenshots for context

​Reset and start fresh

​Using the tray menu

​Optimize for your use case

​Troubleshooting common issues

​Screenshot not capturing

​AI not responding

​Window positioning issues

​What’s next?

Explore AI Providers

Keyboard Shortcuts

Privacy & Security

Advanced Configuration

Build docs developers (and LLMs) love

Quick Start Guide

Launch Cluely

Master the keyboard shortcuts

Essential shortcuts

Window positioning

Your first screenshot analysis

Example workflows

Debugging code errors

Interview preparation

Learning from presentations

Understanding the processing flow

Advanced tips

Multiple screenshots for context

Reset and start fresh

Using the tray menu

Optimize for your use case

Troubleshooting common issues

Screenshot not capturing

AI not responding

Window positioning issues

What’s next?