How Clair works
Clair plugs into Claude Code through hooks, the extension point every Claude Code user has. When Claude Code stops to ask for something, a hook hands the prompt to the Clair agent on your computer, which seals it for your phone. The phone opens it, shows it, and passes it to your watch. Your answer comes back the same way.
From the terminal to your wrist
- Claude Code calls the Clair agent on your own machine, at
127.0.0.1:7317, with what it wants to ask: a command to run, a question with its options, or a plan. - The agent seals the prompt so only your phone can open it, and posts it to Clair's relay over HTTPS.
- If your phone is asleep, the relay asks Google's push service to wake it. The push names the pairing that has something waiting and nothing more.
- The phone fetches the sealed prompt, opens it and shows it. If a watch running Clair is reachable, the phone passes the prompt on over Wear OS's own phone-to-watch connection.
- You answer on the watch, the phone or at the keyboard. An answer from the watch goes to the phone first. The phone seals it for the agent, and the agent hands it to Claude Code, which carries on.
Both ends connect out to the relay, so neither your computer nor your phone needs an open port, and they don't have to share a network.
First answer wins
Clair answers through Claude Code's PermissionRequest hook. For the main session, Claude Code runs the hook while it shows its own dialog in the terminal, so the prompt is in both places at once. Answer wherever you are: the first answer settles it and the others clear themselves.
Clair sets that hook to wait up to a day, so a prompt you walked away from is still waiting on your wrist when you look. The phone's "Prompt hook timeout" setting changes how long.
The hooks Clair adds
clair pair adds these to Claude Code's settings.json, next to any hooks of your own, and clair unpair takes them out again. Only PermissionRequest waits for an answer. The others report what the session is doing, so the phone and watch can show it.
| Hook | What Clair does with it |
|---|---|
PermissionRequest | Brings permission prompts, questions (AskUserQuestion) and plan reviews (ExitPlanMode) to your phone and watch, and returns your answer. |
PreToolUse, PostToolUse, PostToolUseFailure | The session's activity: each tool call as it starts, finishes or fails. |
UserPromptSubmit | The last thing you asked Claude, shown with the session. |
Stop | The end of a turn, with Claude's last message. A session with agents still working in the background stays Working. |
Notification | Only the idle_prompt kind, which marks the session Idle. |
PreCompact | Shows the session as Compacting. |
SessionEnd | Shows the session as Ended. |
SessionStart | Shows a new session as Starting before its first tool call. It runs clair hook-event, and a switch in the phone's settings leaves it out. |
Where the usage ring comes from
No hook reports your usage, so Clair reads it from Claude Code's status line. clair pair points the status line at clair statusline, which runs the status line you already had, prints its output unchanged, and passes your usage along at most every 30 seconds. That fills the ring on the watch complication: your token usage in the current five-hour window.
Prompts from background agents
Claude Code treats a background agent's permission prompt differently from the main session's: it shows the dialog in the terminal only if no hook answered first. The Clair agent checks whether you're at the computer first. If you are, it steps aside at once and the prompt appears in the terminal. If you're away, it waits for your phone or watch, and moves to the terminal if you come back before you've answered it.
At the computer means you typed in a terminal there within the last two minutes, a threshold you can change on the phone. On Windows any input counts.
What the relay can and can't see
The relay stores sealed messages and hands them over. It can't read a command, a plan or an answer, and it can't forge one: a message it altered or replayed fails to open at the other end. It deletes each message once the other end collects it, or after a day at most.
To deliver messages and hold off abuse, the relay does see when each pairing is active, how much it sends, the IP addresses your devices connect from, and the push token that wakes your phone. From your phone, prompts reach the watch over Wear OS's own phone-to-watch connection, which runs through Google's servers when the two aren't within Bluetooth range.