Claude integration

What the setup button does

Settings (⌘,) → Claude → Set up Claude Integration performs two steps.

1. It copies three Node scripts into ~/.claude:

File	Destination	Role
hook.js	~/.claude/session-status/	Writes <id>.json session state
lib.js	~/.claude/session-status/	Shared state model and MCP glyphs
ctx_monitor.js	~/.claude/statusline/	Status line; writes <id>.meta.json

2. It merges the hooks and status line into ~/.claude/settings.json.

The merge is idempotent and your existing configuration is preserved. Fleet’s own entries are tagged by the session-status/hook.js substring, so re-running setup replaces them cleanly rather than duplicating them. The old settings file is backed up first.

It is safe to re-run at any time. Fleet also refreshes the copied scripts on every launch, so they stay in step with the app version.

How a session is matched to a row

This is the part that makes Fleet fast, and it is worth understanding.

Fleet spawns every PTY itself. When it does, it injects FLEET_SESSION=<uuid> into the shell environment and strips any inherited CLAUDE_CODE_* variables so the session starts as a clean top-level one.

The hooks then stamp that same FLEET_SESSION value into every state file they write. Fleet watches ~/.claude/session-status/state and ~/.claude/sessions with FSEvents and matches state to row on the fleetSession field directly.

There is no session_id → tty process-ancestry walk and no per-pid ps. The correlation key is a value Fleet put there itself.

State flows strictly one way: the hooks write the state files, Fleet reads them.

What ends up on a row

Three files per session feed the sidebar:

<stem>.json         { state, extra, mode, fleetSession }
<stem>.meta.json    { model, ctxPct, effort, fastMode, cwd, branch, … }
<stem>.agents.json  { count, names, ts }

Which produce the states you see:

State	Row shows	Colour
working	Working, with a spinner	Grey
idle	Your turn	Amber
wait	Waiting	Amber
perm	Needs permission	Red
ask	Question	Purple
mcp	The MCP server name	Blue
pr	PR opened	Green

A session that is idle but still has subagents running is treated as working, not as waiting on you.

Session names

Claude’s own /rename is honoured. Fleet reads the name from ~/.claude/sessions/<pid>.json, and a name you set by double-clicking the row title is honoured too. When both exist, the most recent one wins.

Undoing it

Remove Fleet’s entries from the hooks and statusLine sections of ~/.claude/settings.json — they are the ones referencing session-status/hook.js and statusline/ctx_monitor.js — and delete ~/.claude/session-status/ and ~/.claude/statusline/.

Fleet keeps working without them. Claude sessions simply appear as ordinary shell rows.