[■]─[▪] sidecar
Get Started
Documentation

Claude Code Hooks

Beta

Sidecar can capture an ongoing Claude Code session into worklog and session records without any explicit sidecar worklog record calls. Once you wire Claude Code's hook system to sidecar hook <event>, every session start, file edit, and prompt submission flows into your project memory automatically.

Beta channel. Ambient capture via Claude Code hooks ships on the beta channel. Install sidecar-cli@beta to use it. See Release channels.

Generate the settings block

Print the ready-to-paste Claude Code settings block:

$ sidecar hooks print

Paste the hooks object into either:

  • .claude/settings.json — project-level, committed to the repo
  • ~/.claude/settings.json — user-level, across all projects

Claude Code merges hook arrays across scopes, so user-level and project-level hooks compose.

The four events

Claude Code event Sidecar hook Effect
SessionStart sidecar hook session-start Opens a Sidecar session (actor=agent, name claude-code:<sid>). Idempotent.
SessionEnd sidecar hook session-end Closes the active session. Safe to call when none is open.
PostToolUse (Edit, Write, MultiEdit, NotebookEdit) sidecar hook file-edit Records a worklog "Edited <path> via <tool>" and links the file as an artifact. Lazy-opens a session if none is active.
UserPromptSubmit sidecar hook user-prompt Records the first 200 chars of the prompt as a note.

Hook behavior

Every hook:

  • Reads its payload JSON from stdin (Claude Code supplies it automatically).
  • Always exits 0 — hooks never block the caller, even on internal errors.
  • Accepts --actor-name <name> to override the default actor name.
  • Accepts --json to emit a structured envelope (useful when testing).

Quick manual smoke test

You can verify hooks from the shell before wiring them up:

$ echo '{"session_id":"abc"}' | sidecar hook session-start
$ echo '{"tool_name":"Edit","tool_input":{"file_path":"'"$PWD"'/README.md"}}' | sidecar hook file-edit
$ sidecar hook session-end
$ sidecar recent --type worklog --limit 3

Codex and other runners

The hook commands are just a permissive JSON stdin → CLI bridge. Codex users can invoke the same CLI from any shell hook or wrapper script — a minimal {"tool_input":{"file_path":"..."}} is enough for sidecar hook file-edit to record a worklog entry.

Related