DreamLake

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.

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 eventRelayliveStateFrom the hook JSON
SessionStartregister, then heartbeatstartingsession_id
UserPromptSubmitheartbeatrunningsession_id, prompt → promptHead (first 200 characters, one line)
PreToolUse, PostToolUseheartbeatrunningsession_id, tool_name → current.tool
Notification matcher permission_promptheartbeatwaiting-for-usersession_id
Notification matcher idle_promptheartbeatidlesession_id
Stopheartbeatwaiting-for-usersession_id
SubagentStartevent --kind SubagentStartsubagent runningagent_id → subagentId, agent_type → name
SubagentStopevent --kind SubagentStop --finishedsubagent stoppedagent_id, agent_type
SessionEndheartbeatstoppedsession_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.