<!-- source: https://cli.dreamlake.ai/dev/claude-code-hooks @ 0.134.0 99837ab -->

# Claude Code hooks for live state

DreamLake learns what a session is doing from the session itself: Claude Code
runs the hooks below at each step and they call
[`dl sessions heartbeat` and `dl sessions event`](/sessions/control.md#live-state-and-subagent-events),
one bounded request each. Nothing is forked or wrapped; the stock CLI stays in
charge. This is the companion of the [`/dreamlake` skill](/dev/claude-code-skill.md):
the skill (or its SessionStart hook) registers the session and writes the env
file at `~/.dreamlake/sessions/<native-uuid>.env`, and the relay below finds
the saved session through that file, from `CLAUDE_CODE_SESSION_ID`, which
Claude Code sets in the environment of every hook command. The `session_id`
in the hook's stdin JSON is only checked against it: a payload naming another
session is refused and nothing is sent.

## settings.json

Copy into `~/.claude/settings.json` (every session of this user) or
`.claude/settings.json` (this project). Merge the `hooks` object with any
hooks already there; the SessionStart entry is the registration hook from the
skill page and is what makes the rest find their session.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "timeout": 20, "command": "sid=$(jq -r .session_id) && dl sessions register --provider claude --session \"$sid\" --cwd \"$PWD\" --visibility private --write-env \"$HOME/.dreamlake/sessions/$sid.env\" --json >/dev/null 2>&1; dl sessions heartbeat --state starting >/dev/null 2>&1 || true" }
        ]
      }
    ],
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command", "timeout": 5, "command": "dl sessions heartbeat --state running --hook-stdin >/dev/null 2>&1 || true" } ] }
    ],
    "PreToolUse": [
      { "hooks": [ { "type": "command", "timeout": 5, "command": "dl sessions heartbeat --state running --hook-stdin >/dev/null 2>&1 || true" } ] }
    ],
    "PostToolUse": [
      { "hooks": [ { "type": "command", "timeout": 5, "command": "dl sessions heartbeat --state running --hook-stdin >/dev/null 2>&1 || true" } ] }
    ],
    "Notification": [
      { "matcher": "permission_prompt", "hooks": [ { "type": "command", "timeout": 5, "command": "dl sessions heartbeat --state waiting-for-user --hook-stdin >/dev/null 2>&1 || true" } ] },
      { "matcher": "idle_prompt", "hooks": [ { "type": "command", "timeout": 5, "command": "dl sessions heartbeat --state idle --hook-stdin >/dev/null 2>&1 || true" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "timeout": 5, "command": "dl sessions heartbeat --state waiting-for-user --hook-stdin >/dev/null 2>&1 || true" } ] }
    ],
    "SubagentStart": [
      { "hooks": [ { "type": "command", "timeout": 5, "command": "dl sessions event --kind SubagentStart --hook-stdin >/dev/null 2>&1 || true" } ] }
    ],
    "SubagentStop": [
      { "hooks": [ { "type": "command", "timeout": 5, "command": "dl sessions event --kind SubagentStop --finished --hook-stdin >/dev/null 2>&1 || true" } ] }
    ],
    "SessionEnd": [
      { "hooks": [ { "type": "command", "timeout": 5, "command": "dl sessions heartbeat --state stopped --hook-stdin >/dev/null 2>&1 || true" } ] }
    ]
  }
}
```

The SessionStart line reads stdin once for the registration (`jq`), so its
`starting` beat takes no `--hook-stdin`: the relay finds the env file the
registration just wrote through `CLAUDE_CODE_SESSION_ID`. Every other line
reads the hook JSON itself.

## What each hook sends

| Claude Code event | Relay | `liveState` | From the hook JSON |
| --- | --- | --- | --- |
| `SessionStart` | register, then `heartbeat` | `starting` | `session_id` |
| `UserPromptSubmit` | `heartbeat` | `running` | `session_id`, `prompt` → `promptHead` (first 200 characters, one line) |
| `PreToolUse`, `PostToolUse` | `heartbeat` | `running` | `session_id`, `tool_name` → `current.tool` |
| `Notification` matcher `permission_prompt` | `heartbeat` | `waiting-for-user` | `session_id` |
| `Notification` matcher `idle_prompt` | `heartbeat` | `idle` | `session_id` |
| `Stop` | `heartbeat` | `waiting-for-user` | `session_id` |
| `SubagentStart` | `event --kind SubagentStart` | subagent `running` | `agent_id` → `subagentId`, `agent_type` → `name` |
| `SubagentStop` | `event --kind SubagentStop --finished` | subagent `stopped` | `agent_id`, `agent_type` |
| `SessionEnd` | `heartbeat` | `stopped` | `session_id` |

`--hook-stdin` reads **only** `session_id`, `tool_name`, `prompt`, `agent_id`
and `agent_type`. Tool input, tool responses, transcript paths and the working
directory are never read or forwarded, and the prompt head is never printed
by the relay. The payload is data, not identity: `session_id` must equal the
`CLAUDE_CODE_SESSION_ID` of the hook's own environment, else the relay exits 1
without posting. The server redacts the prompt head with the session redaction
patterns on ingest and shows it to the owner only.

## Why the lines look like this

- **`>/dev/null 2>&1 || true`.** Claude Code treats a hook's exit code 2 as
  a blocking error (for `PreToolUse`, `UserPromptSubmit`, `Stop` and
  `SubagentStop` it blocks the action) and any other non-zero code as a
  non-blocking error it shows the user. The relay itself never exits 2, but a
  logged-out CLI or an offline network should not nag every tool call either,
  so the line swallows the failure. Verify the installation once (below)
  instead.
- **`"timeout": 5`.** A hook holds the step it reports on until it returns.
  The relay makes one request with a 5 s timeout; the hook timeout (in
  seconds) caps the whole command the same way.
- **`PostToolUse` is optional.** It only refreshes `running` after a long
  tool; `PreToolUse` already set it. Drop it to halve the relay traffic.
- **No `Notification` matcher at all** sends `waiting-for-user` for every
  notification, including `auth_success`; keep the two matchers.
- **Why not infer the state from `hook_event_name`?** The state is on each
  line on purpose: the mapping above is a policy, and the CLI stays a relay
  that does not know Claude Code's event taxonomy.

## Codex

Codex CLI has no equivalent hook surface for tool calls. Codex sessions get
their live state from the runner (`dl sessions serve` reports
`running` every 10 s while it executes a headless turn) and from the Codex
`/dreamlake` skill, whose instruction block tells the model to run
`dl sessions heartbeat --state waiting-for-user --session <id> --namespace <ns>`
when it finishes a turn; without either, a Codex session shows the last state
anyone reported, or `uncertain` 60 s after a `running` beat.

## Verifying an installation

1. Start a Claude Code session and type `/dreamlake` (or rely on the
   SessionStart hook). `cat ~/.dreamlake/sessions/<native-uuid>.env` holds
   the saved id and namespace.
2. Ask Claude to run any tool. Within a few seconds
   `dl sessions status <saved-id> --namespace <ns>` shows
   `liveState: running` and `current.tool`; after the reply it shows
   `waiting-for-user`.
3. `dl sessions watch --session <saved-id> --namespace <ns>` prints
   each beat and each subagent start and stop as it arrives.
4. To see a relay's own output once, run the hook line by hand without the
   redirection, with the identity Claude Code would have set:
   `echo '{"session_id":"<native-uuid>","tool_name":"Bash"}' | CLAUDE_CODE_SESSION_ID=<native-uuid> dl sessions heartbeat --state running --hook-stdin`.
   A `register it first` error means the env file is missing for that native
   id: run the registration it prints.
