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,
one bounded request each. Nothing is forked or wrapped; the stock CLI stays in
charge. This is the companion of the /dreamlake skill:
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.
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 (forPreToolUse,UserPromptSubmit,StopandSubagentStopit 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.PostToolUseis optional. It only refreshesrunningafter a long tool;PreToolUsealready set it. Drop it to halve the relay traffic.- No
Notificationmatcher at all sendswaiting-for-userfor every notification, includingauth_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
- Start a Claude Code session and type
/dreamlake(or rely on the SessionStart hook).cat ~/.dreamlake/sessions/<native-uuid>.envholds the saved id and namespace. - Ask Claude to run any tool. Within a few seconds
dl sessions status <saved-id> --namespace <ns>showsliveState: runningandcurrent.tool; after the reply it showswaiting-for-user. dl sessions watch --session <saved-id> --namespace <ns>prints each beat and each subagent start and stop as it arrives.- 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. Aregister it firsterror means the env file is missing for that native id: run the registration it prints.