> ## Documentation Index
> Fetch the complete documentation index at: https://rakumux.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Activity hooks

> Optional hooks that tell Rakumux exactly what Claude Code, Codex and OpenCode are doing.

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.

> [!NOTE]
>
> 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](https://rakumux.com/docs/guides/session-descriptions.md).

**Claude Code**

Print the hook configuration:

```bash theme={null}
rakumux session hook-config --agent claude
```

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.

**Codex**

Use a Codex version with native hooks, then print the configuration:

```bash theme={null}
rakumux session hook-config --agent codex
```

Merge the printed `hooks` entries into `~/.codex/hooks.json` (or `$CODEX_HOME/hooks.json`),
appending to existing event arrays. Restart Codex inside Rakumux, open `/hooks`, and review and
trust the new handlers. Don't bypass hook trust or tool approval.

The hooks cover prompt submission, tool execution, permissions, completion, interruption and
subagents, and the root hook's `cwd` reports Codex's current worktree. Older Codex versions
without hooks keep screen detection.

**OpenCode**

Install the Rakumux plugin for OpenCode V2, then restart OpenCode inside Rakumux:

```bash theme={null}
rakumux-mcp opencode-plugin --install
```

It writes a self-contained `tui.js` to `~/.config/opencode/plugins/rakumux-session/`
(`XDG_CONFIG_HOME` is respected, and `--dir` picks another config directory). It doesn't change
your OpenCode config. `rakumux-mcp opencode-plugin` prints the module instead.

The plugin runs in OpenCode's TUI, inside the Rakumux session. It reports the displayed
conversation's phase, tools, permissions and forms and active subagents, binds that
conversation to the session for the [MCP server](https://rakumux.com/docs/agents/mcp.md), and reports the worktree it
shows. Rakumux recognises OpenCode V2 run as `opencode` or `opencode2`.

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.