For macOS · open source · runs on your Mac

Help that stays on your screen.

Klair is a quiet study companion. A small pixel flower sits in the corner of your screen, takes notes on what you read, and when you tap fn, answers right where you are, grounded in everything you've studied in that project.

Set it up on your Mac ↓ View the source

Free and open source · Bring your own OpenRouter key · Nothing runs until you ask

ChromeFileEditViewHistory

Sat 2:14 PM

encyclopedia.example/gradient-descent#learning-rate

Contents Overview Intuition Learning rate Convergence Momentum Stochastic variants

Gradient descent

From the free encyclopedia · Optimization

Learning rate

Each step moves the parameters against the gradient, scaled by a step size η called the learning rate: x ← x − η∇f(x). 1The whole method in one line: the gradient picks the direction, η picks how far to go.Choosing η is a trade-off between speed and stability.

2This is why the η = 1.1 example bounces: on f(x) = x², any η above 1 makes each step overshoot further.If the rate is too large, each update overshoots the minimum and the iterates can oscillate or diverge. If it is too small, progress is slow and training may stall on flat regions.

Figure 2. With a large step size, iterates jump from one side of the valley to the other before settling.

In practice the rate is often decayed over time, or adapted per parameter, as in AdaGrad and Adam.

Where you are

Gradient descent: Learning rate

You've stayed on the step-size section for a few minutes. Earlier in this project you read the Machine learning overview.

On screen · 2:14 PMFull page · Gradient descent

Building on this project

Ask for something else…

⌘K

⌘1–9pick⌘Sselect area⌘/all keysescclose

Try it: click the flower or press K (that's fn in the app), then 1–4 to pick and esc to close.

What it does

A study partner that reads along, then waits to be asked.

Klair runs in the background during a session. It notices what you're working on, keeps it organised by project, and stays out of the way until you want help.

Notices what you're reading

Every few seconds Klair checks the screen. Only real changes count. A chat that keeps scrolling or a small animation doesn't, and each new screen gets a short factual note.

Pause anytime fn P

Suggests what to do next

Stay on a page for a minute and ideas appear beside the flower: a summary, a worked example, a self-test, or how it connects to something you studied last week.

Quiet for 30 min fn Q

Answers in place

Pick an idea or ask your own question. The answer streams into a glass panel over the corner, says what it was built from, and can be reshaped: shorter, simpler, more detail.

fn open · ⌘1–9 pick · ⌘K ask

Focus on one part of the screen

Drag out a figure, an equation or a block of code. Klair captures it at full resolution and keeps it as the context until you switch back to the whole screen.

Select an area ⌘S

Reads whole pages and marks them up

With the Chrome extension, Klair gets the full text of the page, not just what's visible. After an answer, it highlights the passages it relied on, with a note beside each.

Optional Chrome extension

Adds the files you download

Grab a PDF, slides or a spreadsheet and Klair asks whether to add it. It reads the text into your project, so you can ask "summarize the paper I just downloaded".

Asks first, every time

Projects and sessions

Each subject keeps its own memory.

A project ("ML", "Operating Systems", "Spanish") holds everything Klair gathers for it, across every session, along with its own knowledge graph of the concepts you've covered. A session is just the time you spend. Switch projects mid-session with fn 1–9. Context never crosses projects, so your OS notes never leak into an ML answer.

How it works

Watch, note, wait, answer.

Klair does as little as possible until you ask. It sends only a small, relevant slice of your project to the model, never the whole history.

See what changed

The screen is checked every 4 seconds. A screenshot is kept only if at least 5% of it changed and a small judge model agrees it's new content.

Klair's own windows are never captured

Take a note

A vision model writes a short note of observed facts and proposes study moves. Screens unrelated to the project, like a glance at messages, are left out.

Gemini 3.5 Flash-Lite by default

Wait for you

Ideas show up only after you've paused on a screen. While the panel is open, ideas stay put, so nothing shifts while you read.

Pause time: 1 min (30 s / 2 min in the menu bar)

Answer from your project

When you pick, Klair pulls related notes from the project's knowledge graph and a keyword search, then streams a grounded answer into the panel.

GPT-5.4 mini by default

Install

Get Klair running on your Mac.

Klair is built from source for now. Plan on about 15 minutes. You'll need a Terminal and an OpenRouter API key, and everything else is optional.

NeededA MacmacOS with Apple silicon. pnpm app builds an arm64 app.

NeededNode 22+ and pnpmPlus Git and the Xcode Command Line Tools.

NeededOpenRouter keyPays for the AI models Klair uses, billed by OpenRouter.

OptionalGraphify, Chrome, TigerDataKnowledge graphs, whole pages, and a cloud copy of each project.

Already have Node 22+, pnpm and Git?Here's the short version.

Terminal

# Get the code and its packages

$ git clone https://github.com/evandong1976/Klair.git && cd Klair && pnpm install

# Make your settings file, paste in your OpenRouter key and save

$ cp -n .env.example .env.local; open -e .env.local

# Build Klair and open it

$ pnpm app

Then allow Screen recording in the Start window and reopen Klair (step 6). Graphify, the Chrome extension and the fn key are optional: steps 4, 7 and 8.

Install the developer tools

Xcode tools, Homebrew, Node, pnpm and Git. Skip this if you have them.

If you already have Homebrew, Node 22 or newer and pnpm, skip ahead. Otherwise, open Terminal and run these one at a time, letting each finish:

Terminal

# Apple's compilers (a dialog appears; click Install)

$ xcode-select --install

# Homebrew, the Mac package manager

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Put brew on your PATH (Homebrew prints these as its "Next steps")

$ echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
$ eval "$(/opt/homebrew/bin/brew shellenv)"

# Node, pnpm and Git

$ brew install node pnpm git

command not found: brew? The two PATH lines haven't run in this window yet. Run them and try again.

Check it worked

$ node -v
v22.16.0      # 22 or newer
$ pnpm -v
10.18.0
$ git --version
git version 2.50.1

Stuck on this step? Ask on GitHub.

Get the code

Clone the repository and install its packages.

Clone the repository and install its packages. pnpm install also fetches Electron, which takes a minute or two the first time.

Terminal

$ git clone https://github.com/evandong1976/Klair.git
$ cd Klair
$ pnpm install

Klair/

src/mainThe app: screen capture, notes, ideas, answers, storage
src/rendererThe flower, panel, Start and Sessions windows
extension/Klair for Chrome (step 7)
native/fn-keyOptional add-on for the fn key (step 8)
.env.exampleTemplate for your keys (step 3)

Stuck on this step? Ask on GitHub.

Add your OpenRouter key

Create a key and paste it into your settings file.

Klair reaches its AI models through OpenRouter. Create a key there and add a few dollars of credit. Then copy the settings template and paste your key into it:

Terminal

# -n keeps a key you already saved
$ cp -n .env.example .env.local
$ open -e .env.local      # opens it in TextEdit

Your key stays in .env.local on your Mac, and Git ignores that file. In OpenRouter's key dialog, set a credit limit so Klair can't spend past it.

Optional: keep a cloud copy with TigerData

Leave DATABASE_URL empty and projects stay on your Mac. To keep a cloud copy, fork a TigerData service with tiger service fork <id> --now, run tiger db uri <fork-id> --with-password, and paste the result with &uselibpqcompat=true on the end.

# .env.local (never committed) # https://openrouter.ai/keys OPENROUTER_API_KEY=sk-or-v1-… # Optional: your TigerData fork DATABASE_URL= # Models (must accept images) KLAIR_FAST_MODEL=google/gemini-3.5-flash-lite KLAIR_ANSWER_MODEL=openai/gpt-5.4-mini # How long before ideas appear (ms) KLAIR_DWELL_MS=60000

The defaults were picked for speed. Any OpenRouter model that accepts images works, and the Start window checks your key and models when Klair launches.

Stuck on this step? Ask on GitHub.

Install Graphify for knowledge graphs

So answers can draw on what you studied earlier. Recommended

Graphify builds a graph of each project's concepts, so answers can pull in what you studied earlier without sending your whole history. Klair finds it automatically.

Terminal

$ brew install pipx
$ pipx ensurepath          # then open a new Terminal window
$ pipx install "graphifyy[openai]"

Note the double y in graphifyy, and keep [openai]: it's how Graphify reaches OpenRouter. Installed it without? Run pipx inject graphifyy openai. Skipping Graphify is fine too, since answers still use the project's notes and the current screen.

Knowledge graph · ML

Stuck? See The knowledge graph stays empty, or ask on GitHub.

Start Klair

Build the app and open the Start window.

There are two ways to run it:

pnpm app builds a signed Klair.app, copies your .env.local next to it and opens it. This is the one to use day to day, because macOS remembers its permissions.
pnpm dev runs with hot reload, for working on Klair itself. macOS then grants permissions to the app you launched it from (Terminal, VS Code…).

Terminal

$ pnpm app      # run it again after pulling changes or editing .env.local

The flower appears in your menu bar and the Start window opens. Each row goes green as it's set up, and Check again re-tests them.

Only one Klair runs at a time. If pnpm dev exits right away, quit Klair.app from the menu bar first.

KlairStart a session

Screen recordingAllowed
The fn keyUse ⌃⌥K until Input Monitoring is onAllow
AI models via OpenRouterKey works · gemini-3.5-flash-lite
GraphifyFound in ~/.local/bin
TigerData databaseNot set: projects stay on this Mac

Not now escStart session ⌘↵

Stuck? See Klair.app shows the AI models in red, or ask on GitHub.

Allow screen recording

Klair needs to see your screen during a session.

It only captures while a session is running, and ⌃⌥P pauses it. Screenshots are kept on your Mac and deleted after 14 days by default. Each new screen also goes to your AI model through OpenRouter, which writes its note.

In the Start window:

Click Allow on the Screen recording row.
In System Settings › Privacy & Security › Screen & System Audio Recording, switch Klair on.
Quit Klair and open it again. macOS only applies the permission after a restart.

Settings says Klair is allowed but the app says it isn't? The entry is stale. Run tccutil reset ScreenCapture com.klair.app and allow it again.

Klair asks for the Downloads folder the first time a session starts, so it can offer new downloads. That one's optional.

Privacy & Security › Screen & System Audio Recording

Klair

Terminalfor pnpm dev

Klair's own windows are excluded from capture, so it never sees itself.

Stuck? See Screen recording says “not allowed”, or ask on GitHub.

Add the Chrome extension

So Klair can read whole pages and highlight passages. Optional

So Klair can read whole web pages and highlight the passages an answer is about:

Open chrome://extensions in Chrome.
Switch on Developer mode (top right).
Click Load unpacked and choose the extension folder inside your Klair folder.

The Start window's Chrome extension row turns green within a minute. Pages are only sent while a session is observing, never from incognito, and only to Klair on your own Mac (127.0.0.1).

After pulling new code, click reload ↻ on the extension's card. PDFs open in Chrome's viewer can't be read by extensions, so download them and add them instead.

chrome://extensions Developer mode

Load unpackedPack extension

Klair for ChromeSends the pages you open to Klair while a session is observing, and marks the passages its answers are about.

ID: jndibkpbjoldneahpgmofeoekkpeaepo

Stuck? See The extension says “Klair isn't running”, or ask on GitHub.

Use the fn key

Open Klair with plain fn instead of ⌃⌥K. Optional

Out of the box, Klair opens with ⌃⌥K. To use plain fn instead, build the small native add-on, then allow Input Monitoring from the Start window's fn row and click Check again.

The add-on is listen-only. It reports fn by itself, and fn held with P, Q or 1–9. Everything else you type is ignored, and it never blocks or changes a key.

Terminal

$ pnpm build:native
$ pnpm app       # bundles the add-on into Klair.app

If macOS uses fn for the emoji picker or dictation, go to System Settings › Keyboard › "Press 🌐 key to" and choose Do Nothing. Or just keep using ⌃⌥K.

fn or ⌃⌥K

The whole fn family has the same fallback: ⌃⌥P pause, ⌃⌥Q quiet, ⌃⌥H hide, ⌃⌥1–9 switch project.

Stuck on this step? Ask on GitHub.

Your first session

Two minutes to your first answer.

Once the Start window is green, try this with any article you're studying.

In the Start window, make a project (say "ML"), tick it and press ⌘↵. The flower appears in the top-right corner.
Open an article and stay on one section. After a minute, "N ideas for this section" appears beside the flower.
Tap fn (or ⌃⌥K). The panel opens over the corner with where you are and the ideas.
Press ⌘2. The answer streams in. Try ⌘⇧1 for a shorter version.
Press ⌘S and drag over a figure to ask about just that part.
Press esc to close. When you're done, choose End in the menu bar and the project's graph rebuilds.

Keyboard

Your hands never leave the keys.

Only the fn family works everywhere. The ⌘ shortcuts work only while Klair's panel is open, so ⌘1 still switches browser tabs the rest of the time. Press ⌘/ in the panel for the full list.

Anywhere (global)

fnor⌃⌥K: Open or close Klair
fn Hor⌃⌥H: Hide the panel and bring it back unchanged
fn Por⌃⌥P: Pause or resume observing
fn Qor⌃⌥Q: Quiet ideas for 30 minutes
fn 1–9or⌃⌥1–9: Switch the active project

In the panel

⌘1–9: Pick an idea
⌘↑⌘↓: Move between ideas
⌘K: Ask your own question
⌘S: Select an area of the screen
⌘/: Show all keys
esc: Close

On an answer

⌘⇧1–3: Shorter · Simpler · More detail
⌘[: Back to ideas
⌘R: Retry

Menu bar popover

⌘P ⌘E: Pause · End the session
⌘1–3: Pause time: 30 s · 1 min · 2 min
⌘L ⌘O: Last answer · All sessions
⌘G: Knowledge graph

Privacy

Your screen stays yours.

Klair is local-first. Here's exactly what goes where.

Kept on your Mac

Screenshots, selected areas and added files
Every project's notes, ideas, answers and pages, in SQLite
Each project's knowledge graph
Deleted automatically after 14 days (you can change this)

~/Library/Application Support/Klair/

Sent to AI models

Each new screen, to write its note
Up to 15k characters of the Chrome page you're on
For an answer: the screen note, the page, a recent file, and only the related earlier notes
All through OpenRouter, using your own key

Optional cloud copy

Only if you set DATABASE_URL
Text and metadata only. Images and files never leave your Mac.
Uploaded to your own TigerData database after each session
Deleting a project removes it there too

Pause anytime with fn P. Downloads are never read until you click Add, and the Chrome extension sends nothing from incognito windows.

Troubleshooting

If something's off

Screen recording says "not allowed" after I allowed it

macOS applies the permission only after the app restarts. Quit Klair from the menu bar and open it again. With pnpm dev, the permission belongs to the app you ran it from (the Start window names it). Allow that app, quit it with ⌘Q, and run pnpm dev again.

No ideas appear

Open the Start window and check that "Where your data lives" and the AI models row are green. The screen also has to stay put for the pause time (1 minute by default). Opening the panel asks for ideas immediately.

The ⌘ shortcuts do nothing

They only work while the panel is open and focused. Click the panel once if another app took focus.

Klair.app shows the AI models or TigerData in red, but pnpm dev works

The app reads its settings from ~/Library/Application Support/Klair. Run pnpm app again to copy your .env.local there.

The knowledge graph stays empty

Graphify needs its OpenAI backend to reach OpenRouter. Run pipx inject graphifyy openai, click Check again, then Rebuild graph in the Knowledge graph pane.

TigerData: "Connection terminated due to connection timeout"

Usually the network. Some campus and office Wi-Fi block the port. Sessions keep saving on your Mac and upload later, so try a hotspot or VPN, then Check again.

The Chrome extension says "Klair isn't running"

Make sure Klair is open and a session is observing. Reload the extension (↻ in chrome://extensions) after pulling new code, and reload tabs that were open before you installed it.

Let the flower take notes.

Klair is open source. Read the code, open an issue, or make it yours.

Star Klair on GitHub Install guide

git clone https://github.com/evandong1976/Klair.git