Skip to main content
Without hooks, Rakumux reads each agent’s screen and process to tell whether it’s working, waiting for you or finished. The optional hooks report it directly: tool phases, input and permission requests, finished turns and running subagent counts. They also let the session’s git branch follow the agent’s active worktree. Hooks are opt-in and never installed automatically. They need no API key and make no network request: they send metadata only (never prompts, tool arguments, output or transcripts) to the Rakumux server on your machine. Outside a Rakumux session they do nothing.
Your last message and the agent’s latest message don’t come from the hooks: the server reads them from the agent’s own conversation on your machine. See Agents’ messages.
Print the hook configuration:
Merge the printed hooks entries into ~/.claude/settings.json (or the directory set by CLAUDE_CONFIG_DIR). Append the handlers to existing event arrays; don’t replace your other hooks or settings. Then restart Claude Code inside a Rakumux session.
  • Submitting a prompt reports working, tool hooks running tool, approvals and questions needs input, and Stop done.
  • A Stop that leaves background subagents running stays working until they finish.
  • An Esc interrupt fires no hook: Rakumux ends that turn once Claude’s own screen has looked idle for 5 seconds.
  • The root hook’s cwd reports Claude’s active worktree, and CwdChanged updates it.
To turn the hooks off, remove only the Rakumux handlers.

​
How hook activity behaves

  • Busy markers animate locally; waiting-for-you, unread and ready marks stay still.
  • Hook state expires after 120 seconds without updates, or 10 minutes while hook-reported subagents run, and Rakumux falls back to screen detection. Command hooks have no heartbeat, so a long quiet operation may fall back before it finishes.
  • A compaction neither starts nor ends a turn.
  • Agent subagents are not Rakumux child sessions; they only show as a count (◈ 3).
  • Hooks can’t approve, deny or continue work.
The hooks need a Rakumux server that supports activity reports. If an older server is running, the UI offers to restart it in place.