GitHub
Docs Quickstart

Quickstart

Record Claude Code, Codex and other coding agents with no code changes, then list, inspect and search their sessions.

1. Install

shell 
curl -fsSL https://coding.sh/install | sh

The script installs the CLI and finds the agents on your machine. It asks once, adds a hook to each agent, then opens the viewer. Other ways to install are on Install. For an agent you built yourself, see Trace your own agent.

Codex: Codex runs a new hook only after you trust it. Open Codex and approve the coding.sh entries with /hooks. coding.sh never writes trust state for you; doctor tells you when hooks are still untrusted.

Add the hooks yourself

If you installed another way, or want to choose which agents get hooks, run init. Every file it edits is backed up to ~/.coding.sh/backups first, and its entries are marked so uninstall removes only them.

shell 
coding.sh init --dry-run              # print every file edit, write nothing
coding.sh init                        # install hooks into every detected agent
coding.sh init --agent claude-code    # or just one

--scope project writes to the repository's agent config (for example .claude/settings.json) instead of your user config.

2. Use your agent as usual

Start a new agent session. Agents read their hooks when a session starts, so a session that was already open when you ran init may not be recorded; restart it. Until the first session lands, the viewer says "Waiting for your first session".

Each hook appends one line to ~/.coding.sh/spool and exits 0, with no network calls and no output. If capture fails, the error goes to spool/errors.log and the agent carries on.

3. Look at what was captured

Read commands ingest the spool first, so a session shows up as soon as its events are written.

shell 
coding.sh sessions --since 7d         # newest first
coding.sh show latest                 # one session's timeline
coding.sh search 'flaky test'         # full text over prompts, replies, tool calls
coding.sh sessions --where 'tool:Bash ok:false cost>0.5'
coding.sh ui                          # local viewer on 127.0.0.1:4319
~/calc 
$ coding.sh show latest
add() returns the wrong result, fix it
  Session       22222222-2222-3333-4444-555555555555
  Agent         claude-code  claude-sonnet-4-5
  Repo          ~/calc
  Turns         1, 2 tool calls, 0 files changed
  Latency       tools 57ms (p95 29ms)

    +0ms  session.start
   +29ms  user        add() returns the wrong result, fix it
   +85ms  tool        Read ~/calc/add.js  ok 28ms
  +143ms  tool        Bash node test.js  ok 29ms
  +173ms  turn.end

Subagents are child sessions: sessions --subagents lists them, and show places them on the parent's timeline. Every command takes --json.

--where filters by any field (keys), and --facets counts sessions per value. The viewer's filter bar takes the same query.

Long sessions

A session over 200 events shows one line per phase: the start, each resume, compaction and long idle gap. Derails (looping, failure-streak, churn, no-progress, stalled, context-thrash) sit under the phase they started in.

show --all lists every event, show latest --follow prints new events as a session runs, and sessions --flag looping finds sessions by derail. Long sessions has the thresholds.

4. Ask your agent

init also registers the coding.sh MCP server with the agents that support MCP (Claude Code, Codex, Cursor, OpenCode and others), so the agent can read its own history. In a new session, ask it "what failed in my last session?" or "which tools are slowest this week?".

coding.sh mcp config prints how to register it by hand, and MCP lists every tool.

5. Import past sessions

Most agents keep local transcripts. --backfill imports them, so history from before init shows up too. Re-running it inserts nothing new: event ids are deterministic.

shell 
coding.sh ingest --backfill --since 30d

Agents without hooks

coding.sh run -- <cmd> works with anything. It snapshots the repository before and after the command, records each changed file, and exits with the command's exit code.

shell 
coding.sh run --agent my-agent -- ./my-agent --task 42

Model-call latency

Hooks see tool calls, not model calls. Most adapters recover one llm.call event per model call from the agent's transcript, with timing derived from message timestamps. For measured durations and time to first token from Claude Code, turn on its OpenTelemetry export and run coding.sh collector: see Claude Code over OTel.

Next