The Clair agent

The Clair agent runs on the computer where you use Claude Code. Claude Code hands it each prompt through a hook. The agent seals the prompt for your phone, passes it to the relay, and returns your answer to Claude Code.

Install

On a Mac or Linux, run this in a terminal:

$ curl -fsSL https://claircode.app/install.sh | sh

On Windows, run this in PowerShell:

PS> irm https://claircode.app/install.ps1 | iex

The agent starts right away and again each time you sign in, so there's no terminal to keep open. The installer puts clair in ~/.local/bin (%USERPROFILE%\.local\bin on Windows) and runs clair service install to register it with your system's service manager. It downloads only from claircode.app and checks each download against the release's SHA-256 checksums before installing anything. Nothing runs as root or administrator.

System	How the agent runs
Linux	A systemd user unit, `clair.service`. Logs: `journalctl --user -u clair`.
macOS	A LaunchAgent, `app.claircode.clair`. Logs: `~/Library/Logs/clair`.
Windows	A Scheduled Task, `clair`, run at sign-in. Logs: `%LocalAppData%\clair`.

The agent keeps itself current. About every six hours it asks claircode.app for the newest release, and installs one only if it carries a signature from a key built into the agent. The new version takes over the next time the agent starts, such as when you sign in or run clair service restart. Run clair update to check right away, or set "autoUpdate": false in the agent's agent.json to stop the checks. Each check is an ordinary download, so claircode.app sees your IP address and the agent's version and platform.

clair service status shows whether the agent is running and where it logs, and clair service uninstall removes the service but keeps your pairing.

Set CLAIR_INSTALL_DIR to install somewhere else, or CLAIR_NO_SERVICE=1 to skip the service and run clair daemon yourself.

Pair a phone

$ clair pair

Scan the code it shows with Clair on your phone. A code works once and expires after ten minutes. Before pairing finishes, the terminal shows the name of the phone that scanned it and asks you to confirm, so a code someone photographed over your shoulder can't pair quietly.

Option	What it does
`-qr ascii`	Draws the code in plain characters, for terminals without Unicode blocks.
`-qr none`	Prints only the pairing link. Paste it into Enter link in the app instead of scanning.
`-invert`	Draws the code for a terminal with a light background.
`-replace`	Replaces this computer's current pairing with a new one.
`-yes`	Skips the confirmation.

Then restart Claude Code so it picks up the new hooks. Each computer pairs once; run clair pair on every computer you want to reach the phone.

Check on it

$ clair status

Shows what the running agent is doing: which phone it's paired with, whether that phone is connected, and the pairing's fingerprint. The phone shows the same fingerprint under the computer's name if you want to compare. clair status -json prints the same as JSON, and the command exits with status 3 when no agent is running, which suits scripts.

Unpair

$ clair unpair

Ends the pairing on both sides, deletes whatever was still waiting on the relay, takes Clair's hooks out of Claude Code's settings, restores your own status line, and deletes the keys. Revoking the computer from the phone does the same from the other end. The agent keeps running after a revoke and answers nothing until you pair again.

What it changes on your computer

Claude Code's settings.json (in ~/.claude, or wherever CLAUDE_CONFIG_DIR points) gets Clair's hooks. Your own hooks and settings stay as they were, and the previous file is kept beside it as a timestamped backup.
The status line setting points at clair statusline. It runs your original status line command and prints its output unchanged, and passes your usage along to the watch at most every 30 seconds.
The agent listens for Claude Code's hooks on 127.0.0.1:7317, on your own machine only.

It keeps its keys and settings in one folder. CLAIR_CONFIG_DIR moves it.

System	Folder
Linux	`~/.config/clair`
macOS	`~/Library/Application Support/clair`
Windows	`%AppData%\clair`

Commands

Command	What it does
`clair pair`	Shows a code for your phone to scan, then installs the hooks.
`clair status`	Shows what the running agent is doing.
`clair unpair`	Ends the pairing and removes the hooks and keys.
`clair daemon`	Runs the agent in the foreground, which helps when troubleshooting.
`clair service`	Installs, starts, stops or removes the agent's login service. `clair service status` shows its state and logs.
`clair update`	Installs the newest release now instead of waiting for the agent's next check. `clair update -check` only reports.
`clair version`	Prints the agent's version.
`clair help`	Lists the commands. `clair <command> -h` lists one command's flags.

Claude Code runs two more commands itself, clair statusline and clair hook-event. You won't need to call either.

If a prompt doesn't arrive or can't be answered

Restart Claude Code after pairing. It reads its hooks only when a session starts.
Run clair status. If no agent is running it says so, and clair daemon starts one in the foreground where you can watch it work.
This code has expired: codes last ten minutes. Run clair pair again.
This code was already used: another phone scanned it first. If that wasn't you, run clair unpair on that computer and pair again.
The phone lists the computer as offline: the agent can't reach the relay. Check the computer's connection, then clair status.
The watch's settings say Disconnected: it can't reach your phone. Away from the phone, the watch needs Wi-Fi or LTE, and the phone needs to be on and online.
The phone says Answer this one in the terminal: without a subscription, Clair is read-only, so the terminal answers the prompt. A prompt that arrived before you subscribed stays with the terminal too.

If none of that helps, email support@claircode.app with what clair status prints and your phone's model.