coding.sh records what your AI agents do: every prompt, model call, tool call, file change and what it cost.
You read each run in a local viewer and turn the ones that went wrong into evals.
Your sessions stay on your machine.

Docs · Quickstart · Supported agents · What you get · Changelog · Discussions · Report a bug

npx coding.sh                               # try it: finds your agents, asks once, imports past sessions
curl -fsSL https://coding.sh/install | sh   # or install it: same setup, then opens the viewer

_{A first run of npx coding.sh 0.1.6 in a fresh home.}

Run npx coding.sh again to open the viewer on your sessions.

What it costs: nothing. MIT licensed, runs on your machine, no account.

_{One Claude Code session in the local viewer (coding.sh ui), with the diff it made and the tests it ran.}

Each session goes into a SQLite index on your machine, with its latency and tokens. You browse it in a local viewer, query it from the CLI or from your agents over MCP, turn failures into evals, and compare changes with paired statistics. No session data leaves your machine unless you add a remote sink.

No runtime dependencies. Node 22.16 or newer.

Quickstart

1. Run npx coding.sh, or the install command above. It runs coding.sh init: it finds your agents, shows one plan and asks once.
2. Start a new agent session. Agents read their hooks when a session starts, so one that was already open may not be recorded.
3. Run coding.sh to open the viewer. New sessions show up on their own, with no ingest step, and your agents can read them over MCP.

init points each agent's hooks at coding.sh, registers the MCP server where the agent supports it, and backs up every config file it edits. It also imports the sessions your agents already keep on this machine, so the viewer opens on your own history.

Command	What it does
coding.sh init --dry-run	Prints the plan without writing anything. --diff adds the edits.
coding.sh init --no-import	Sets up capture and skips the past-session import.
coding.sh ingest --backfill	Imports past sessions again, for example after adding an agent.
coding.sh uninstall	Removes the hooks and MCP entries again.

npm install, the npx cache and other ways to install

You can also install with npm: npm install -g coding.sh. If you only ran npx coding.sh, the hooks keep recording, but the MCP server runs the copy in the npx cache, so install it before you clear that cache. Installing from source, updates and uninstall: docs/guides/install.md.

What you get

Area	What it does	Start with
Record	Captures each session, including subagents, from hooks and transcripts. Wraps any other agent. Takes OpenTelemetry from frameworks and apps.	coding.sh init, coding.sh run -- <cmd>, coding.sh collector
Measure	Turns, tool calls, model calls, tokens, latency and outcome for every session. Flags sessions that edited code and never ran a check.	coding.sh sessions, coding.sh usage, coding.sh improve
Evaluate	Turns a failed session into a replayable eval. Runs experiments with code graders or calibrated LLM judges. A/B tests prompts, harness files and models with paired statistics.	coding.sh eval new, coding.sh exp compare
Benchmark	Draws new cases every day, runs every contender on the same frozen set, and writes a static report.	coding.sh bench
Production	One server for ingest, the viewer and the API, backed by SQLite, Postgres or ClickHouse. SDKs for API apps.	coding.sh serve

Read your sessions

coding.sh sessions             # recent sessions
coding.sh show latest          # timeline with turns, tools, subagents and latency
coding.sh search "rate limit"  # full-text search over prompts, replies and tool calls
coding.sh usage --by model     # tokens, turns and cache hits
coding.sh stats --by agent     # sessions, failures, cost and latency per agent, with a daily trend
coding.sh diff-calls latest#-1 # what changed since the previous model call, and why the cache missed
coding.sh ui                   # the local viewer

Every command takes --json. coding.sh mcp gives your agents the same data as MCP tools. More in docs/guides/explore.md.

Record: wrappers, OpenTelemetry and the model API proxy

• coding.sh run -- <cmd> wraps any other agent and snapshots the repo before and after.
• coding.sh collector takes OpenTelemetry from agent frameworks and apps.
• coding.sh init --proxy routes Claude Code and Codex through a local API proxy that logs each model call's system prompt, tools, messages and cache use. More in docs/how-to/capture-with-proxy.md.

Evaluate: evals, experiments and paired statistics

Turn a failed session into a replayable eval with coding.sh eval new, and check that its verifier is fair with coding.sh eval validate. Run experiments over versioned datasets with code graders or calibrated LLM judges. coding.sh exp compare and coding.sh compare A/B prompts, harness files and models with paired statistics. coding.sh exp replay resends one logged model call with another model or system prompt. Tool evals and multi-agent workflow runs are covered too. More in docs/guides/evals.md.

Benchmark: daily cases and head-to-head reports

coding.sh bench draws new cases every day from a script, your failed sessions, GitHub issues or a sitemap. Every contender gets the same frozen set in random order, and bench report writes a static page with the trend, today's head to head and where each one fails. More in docs/guides/benchmarks.md.

Production: server, SDKs and LLM gateways

coding.sh serve runs ingest, the viewer and the API on one port, backed by SQLite, Postgres or ClickHouse. Your API apps send traces with the TypeScript SDK (@codingdotsh/sdk), the Python SDK (coding-sh) or plain OpenTelemetry. coding.sh gateway links calls made through LLM gateways (Vercel AI Gateway, OpenRouter, LiteLLM, Cloudflare, Portkey, Helicone) to their billed cost. The TypeScript SDK and the store plugins are on npm, and the Python SDK is on PyPI. Start with docs/production/README.md.

Supported agents

Agent	How it records	Status
Claude Code	hooks, transcript, subagents	Verified on real sessions
Codex CLI	hooks, rollout files, subagents	Verified on real sessions
Antigravity CLI (formerly Gemini CLI)	hooks, transcript	Verified on real sessions
OpenCode	plugin, session database	Verified on a real install
Cursor CLI	hooks, transcript	Not run live
GitHub Copilot CLI	hooks, session state	Verified on a real install
Factory Droid	hooks, transcript	Verified on a real install
Goose	plugin hooks, session database	Verified on a real install
Pi	extension, transcript	Verified on a real install
Amp	plugin	Not run live
T3 Code	its local store	Verified on a real install
Aider	coding.sh run -- aider …	Verified on a real install
Any other command	coding.sh run -- <cmd>	Tested
Your own agent or app (Vercel AI SDK, Claude Agent SDK, OpenAI Agents SDK, LangGraph and more)	OpenTelemetry into coding.sh collector, or the TypeScript and Python SDKs	Tested

What the statuses mean

• Verified on real sessions. Checked against sessions captured from a live install of the agent during development, in addition to the CI tests.
• Verified on a real install. The agent's current release was installed and run through a session against a local stub model, its hooks fired and the recorded session was checked, and the captured payloads are now CI fixtures. For OpenCode, Pi, Goose, Factory Droid, GitHub Copilot CLI and Aider, CI repeats that run on Linux and Windows on every change.
• Not run live. CI checks the adapter against the agent's documented formats, but nobody has run it against a live install yet. Cursor CLI and Amp are in that state because both need an account login.
• Tested. Covered by CI tests. There is no third-party agent to check against.

If you use an agent marked "Not run live", a short agent support report saying whether it works moves it to "Verified". Per-agent details, including which agents get the MCP server, are in docs/guides/agents.md. T3 Code and Pi each have a section on Record coding agents.

Privacy

With no sinks configured, no session data leaves your machine. The only default network request is a daily update check, which CODING_SH_NO_UPDATE_CHECK=1 turns off. Secrets are redacted at ingest, before anything is written to the index, blobs or sinks. Remote sinks send metadata only unless you opt in to full content.

What the hook writes to the spool

The hook first writes the agent's payload unredacted to ~/.coding.sh/spool (mode 600). Ingest redacts the payloads kept in spool/<agent>/raw/ in place. A payload written inside its spool line stays unredacted until coding.sh gc deletes the file after 7 days. Details in docs/guides/privacy.md.

Status

coding.sh is pre-1.0 (latest: 0.1.6), so expect rough edges. What isn't done yet:

• Windows. CI runs on Linux, macOS and Windows. On Windows, CI runs the test suite, the installer (from Git Bash) and real OpenCode, Pi, Goose, Factory Droid, GitHub Copilot CLI and Aider sessions against a stub model. Capture from Claude Code, Codex CLI, Antigravity CLI, Cursor CLI, Amp and T3 Code has not been checked on Windows yet.
• Not run live. Two adapters, Cursor CLI and Amp, have not been run on a live install yet. Both need an account login (see Supported agents).

Changes are listed in CHANGELOG.md and on the releases page.

Getting help

For	Go to
Questions and ideas	Discussions
Bugs	Open an issue. The bug form asks for the output of coding.sh doctor, which answers most first questions.
A new agent, or a report on one not run live yet	The agent support form
Security issues	Report them privately through SECURITY.md, not as an issue

Docs

• coding.sh/docs: quickstart, agents, CLI, MCP, evals, OpenTelemetry, storage and the trace format.
• docs/: the same guides in Markdown, plus production, design specs and research.
• docs/troubleshooting.md: what to check when sessions don't show up.

Repository layout

Path	What it holds
packages/coding.sh	The CLI, hook, adapters, OTLP receiver, viewer, MCP server and evals
packages/sdk, packages/sdk-python	The TypeScript and Python SDKs for API apps
packages/store-postgres, packages/store-clickhouse, packages/blob-s3	Store plugins
apps/site	The coding.sh website (Astro, static)
docs	Guides, production, reference and design docs
examples	An eve agent, production apps, a plugin A/B and a skill eval
deploy	Deploy recipes for Compose, Fly, Railway and ClickHouse (Render uses render.yaml)
evals	coding.sh's own CLI eval suite
scripts/dogfood	The scorecard coding.sh runs on itself

Contributing

See CONTRIBUTING.md for setup and the codebase map. Issues labeled good first issue are small and self-contained. Release steps are in docs/RELEASE.md.

Star history

License

MIT