supertrace

Local-first observability for coding agent sessions. See what your agent actually did: every tool call, file edit, shell command, git delta, and token spent — in a local dashboard.

Zero runtime dependencies. Nothing leaves your machine. Events land in SQLite at ~/.supertrace/supertrace.db via Node's built-in node:sqlite. No account, no network calls — verify with tcpdump if you like.

Quick start

npx supertrace-cli init  # install Claude Code hooks in this project
# ... work normally in Claude Code; sessions are recorded locally ...
npx supertrace-cli       # local dashboard at http://localhost:4321

Optional cloud sync — see your sessions from any device at supertrace-alpha.vercel.app:

npx supertrace-cli login  # device-code flow, approve in the browser
npx supertrace-cli push   # backfill existing history (new sessions sync automatically)

Tip: npm install -g supertrace-cli is the most reliable install (it gives you a plain supertrace command) — npx caches can be cleared by npm, which silently stops the recording hooks until you re-run init.

Developing from source

npm install && npm --prefix web install && npm run build
node dist/cli.js --help

Commands

| Command | What it does | |---|---| | supertrace init | Install hooks into .claude/settings.local.json for the current project. --project targets settings.json, --global targets ~/.claude/settings.json. --durations also hooks PreToolUse for per-call durations (~100ms extra per tool call). --gate makes the Stop hook run the gate (see below). | | supertrace remove | Uninstall hooks (same scope flags). | | supertrace backfill | Import past sessions from Claude Code transcripts under ~/.claude/projects/ — history from before supertrace was installed. Sessions already recorded by hooks are skipped. | | supertrace status | DB path plus session/event/snapshot counts. | | supertrace sessions | List recorded sessions in the terminal. | | supertrace digest [--weekly\|--days N] [--json] [--slack [url]] | Rollup of agent activity for the window (default last 24h): sessions, active time, edits, commands with failures, tokens by model, per-project breakdown, top files, and a "needs a look" list (loops, unbacked file mentions, discarded work). --json for piping to other tools or agents; --slack posts it to a webhook (see Scheduled digests). | | supertrace check [session] [--json] [--strict] | The gate. Examines the latest (or given) session's trace and exits 1 when the evidence contradicts a clean finish: a command that failed repeatedly, or a session that ended right after a failing command. Softer signals (edit thrash, files named in the final message with no trace evidence) are warnings; --strict promotes them to failures. Exit 0 pass, 1 fail, 2 no data — built for loops and CI: claude -p "fix it" && supertrace check. | | supertrace serve [--port N] | Local dashboard (default 4321). Also the default command. | | supertrace hook | Internal: the hook receiver. Reads one JSON payload from stdin, appends to SQLite, always exits 0, never prints. |

What gets captured

• Hooks (live stream): SessionStart, UserPromptSubmit, PostToolUse (every tool call with inputs/results, truncated to 16KB), Stop, SubagentStop, SessionEnd.
• Git (ground truth): snapshot of branch/HEAD/status/diffstat at session start, every turn end, and session end; full diff (capped 512KB) at start/end. This is the raw material for claim-vs-reality analysis.
• Transcript (lazily): token usage per model, plus command failures, are parsed from the Claude Code session JSONL on demand — no hook-time cost. Failed commands matter: the PostToolUse hook only fires for successful tool calls, so a failing command leaves no hook event at all. Supertrace recovers them from the transcript's is_error tool results and merges them back into the timeline.

Insights per session

• Loop detection — the same file edited 3+ times within 10 minutes; the same command failing 3+ times.
• Claim vs reality — path mentions in the agent's end-of-turn messages compared against files actually edited and the git delta: files it said it changed but didn't, and files it changed but never mentioned.
• Turns — per-prompt breakdown: duration, edits, commands (with failures), output tokens (joined from the transcript by timestamp).
• Cost by file — approximate: each turn's output tokens split across the files it edited; shows which parts of the codebase are expensive to work in.
• Dead ends — files read repeatedly but never edited; files edited with no net change in the final git snapshot (reverted or committed mid-session).

Loop engineering: the gate

Loops are easy — the hard part is the check that decides when the work is actually done. Supertrace turns the session trace itself into that check.

In a shell loop or CI — supertrace check exits 1 when the trace contradicts a clean finish:

claude -p "fix the failing tests" && supertrace check || echo "not actually done"

As a Stop hook — supertrace init --gate swaps the Stop hook for the gate. When the agent tries to stop with a failing gate, the stop is blocked and the evidence is fed back ("last command exited 1: npm test"), so the agent fixes it instead of reporting success. stop_hook_active is honored: one self-correction round per stop, never an infinite loop. A broken gate always lets the stop through — it can never take down a session.

Project contracts — .supertrace/gates.json in a repo turns the generic heuristics into rules:

{
  "mustRun": [{ "match": "npm test", "label": "tests" }],
  "strict": false,
  "disable": ["edit-loops"]
}

mustRun requires the command to have run in the session with its last run passing (a pass followed by more edits is flagged as stale evidence). strict promotes warnings to failures; disable turns gates off by name (commands, final-command, claims, edit-loops).

Scheduled digests

digest --slack posts the rollup to any Slack-style incoming webhook ({"text": ...}). The URL comes from the flag, SUPERTRACE_SLACK_WEBHOOK, or "slackWebhook" in ~/.supertrace/config.json. A weekly digest every Friday at 5pm:

0 17 * * 5  /usr/local/bin/npx supertrace-cli digest --weekly --slack

Architecture

src/                     collector + server (zero runtime dependencies)
  cli.ts        command dispatch
  hook.ts       hook receiver (stdin JSON → SQLite; must stay silent and fast)
  normalize.ts  Claude Code payloads → vendor-neutral events (only vendor-aware file)
  db.ts         schema: sessions / events / git_snapshots
  git.ts        git snapshots at session boundaries
  transcript.ts lazy token accounting from session JSONL
  analyze.ts    claim-vs-reality, dead ends, turns, cost attribution
  backfill.ts   import past sessions from transcripts
  config.ts     Supabase URL/publishable-key resolution
  server.ts     node:http server: JSON API + built frontend static assets
web/                     dashboard frontend (React + Vite + Tailwind + shadcn/ui)
  src/lib/      api types, formatting, Supabase auth & sync (plain fetch, no SDK)
  src/components/  header, session list, session detail, consent dialog + shadcn ui/

The frontend is a build-time dependency only: vite build emits static assets into dist/public, which the zero-dependency CLI serves. The published npm package ships the built assets, so end users still need nothing but Node.

The event schema is vendor-neutral (tool_call_finished, file_modified, command_executed, …); everything Claude-Code-specific is confined to normalize.ts so other agents (Cursor, Codex, Gemini CLI) can be added as adapters.

Cloud sync (optional)

Everything works offline with no account. Optionally, sign in (Google/GitHub via Supabase Auth) to sync aggregate metrics — durations, counts, token totals, and insight results — to your own account for cross-machine and per-user views:

• Configure via .env (NEXT_PUBLIC_SUPABASE_URL + NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY) or ~/.supertrace/config.json (supabaseUrl / supabaseKey). Without config, the dashboard shows no cloud UI at all and runs unauthenticated.
• With cloud config present, the dashboard is auth-gated: an auth page is shown first, and the local API itself rejects requests without a valid Supabase token (validated server-side against GoTrue, cached 5 min).
• First sync shows a consent dialog spelling out exactly what is uploaded. File contents, diffs, prompts, and command output are never uploaded.
• Rows live in synced_sessions / consents (schema in supabase/001_cloud_schema.sql) with row-level security — each user can only ever read or write their own rows. The browser talks to Supabase with the publishable key + the user's JWT; no service credentials exist client-side.
• "Delete all synced data" in the account menu removes everything server-side; local data is untouched.
• Privacy: file paths are relativized to the project root before display and sync, and the home-directory prefix is stripped from project paths on upload (~/GitHub/foo, not /Users/name/GitHub/foo).

Cloud dashboard (Vercel)

The same web/ app doubles as the hosted dashboard: built with VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_KEY set, it skips the local API entirely and reads the signed-in user's synced_sessions from Supabase — stats, insights, tokens, and cost-by-file from any device. Per-event timelines, commands, and git diffs are local-only by design and never leave the machine that recorded them.

Deploy: point Vercel at the repo with root directory web/, framework Vite, and set the two VITE_* env vars. Add the deployed domain to Supabase Auth → URL Configuration → Redirect URLs.

Notes

• Requires Node ≥ 22.5 (for built-in node:sqlite).
• The installed hook command embeds absolute paths to your Node binary and this checkout — that's why the default install target is settings.local.json (not committed). Re-run init after moving the checkout or upgrading Node.
• Hooks take effect for new Claude Code sessions; restart running ones.
• Hook failures never surface into your session; they're logged to ~/.supertrace/hook.log.