---
title: "Quickstart: record Claude Code and Codex sessions"
description: "Record Claude Code, Codex and other coding agents with no code changes, then list, inspect and search their sessions."
canonical: https://coding.sh/docs/quickstart
human_url: https://coding.sh/docs/quickstart
markdown_url: https://coding.sh/docs/quickstart.md
agents_url: https://coding.sh/agents.md
llms_url: https://coding.sh/llms.txt
updated: 2026-11-11
---

# 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](https://coding.sh/docs/install). For an agent you built yourself, see [Trace your own agent](https://coding.sh/docs/how-to/trace-your-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](https://github.com/jackulau/coding.sh/blob/main/docs/reference/query.md#filter-with---where)), 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](https://github.com/jackulau/coding.sh/blob/main/docs/guides/explore.md#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](https://coding.sh/docs/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](https://coding.sh/docs/otel#claude-code).

## Next

- [Coding agents](https://coding.sh/docs/agents): what each adapter captures.
- [Evals](https://coding.sh/docs/evals): datasets, graders and paired comparisons.
- [CLI reference](https://coding.sh/docs/cli): every command and flag.

To set coding.sh up for a user, follow the agent workflow at [/agents.md](https://coding.sh/agents.md).