cctrace

# cctrace

> TLS-intercepting HTTP tracer for the Claude Code, OpenAI Codex, Grok, and
> Kimi Code CLIs. Spawns the client behind a local zero-config MITM proxy and captures
> its first-party traffic (/v1/messages, OAuth, usage/credits, MCP registry,
> telemetry) into a live categorized web UI with a reconstructed Sessions
> view — sessions > threads > turns on one rail, where a turn is the human
> unit (user request > agent work > final response) and tool rows name what
> they touched (Edit(src/ui.ts), workspace-relative); model epochs, subagent
> spawns attached at their dispatching turn, harness-injected messages
> (recaps, reminders) tagged SYS, compaction boundaries with the
> context collapse in turns and tokens, superseded exchanges kept at their
> timeline position — plus replay, cost, reasoning-effort, cache-verdict, and
> first-token-latency chips. External hosts (npm, github, apt) pass through
> as opaque byte-counted tunnels — logged, never decrypted. Built for two
> jobs: LLM tracing (see exactly what the agent sends and receives each
> turn, and what the harness rewrote — /model switches, /compact repacks,
> injected exchanges) and security/privacy auditing (see what actually
> leaves the machine). Local-only; credentials are redacted before anything
> hits disk.

Runs on Bun. `cctrace` wraps the client transparently: `cctrace -- --continue`
passes everything after `--` to the Claude CLI verbatim; a leading client
word picks who runs (`cctrace codex -- ...`, `cctrace grok -- ...`,
`cctrace kimi`, `cctrace opencode`). Codex/Grok speak OpenAI Responses;
Kimi Code speaks OpenAI Chat Completions; opencode is multi-provider (each
request's dialect is detected from its wire shape) — all reconstruct into
the same sessions view. Traces
land in the store — `~/.local/share/cctrace/traces/<project-key>/`, one dir
per project — as `trace-<timestamp>.jsonl` (one request/response pair per
line, archived to `.jsonl.zst` at exit) — the .jsonl IS the trace;
snapshots render on demand; `cctrace store` shows the store, `cctrace
adopt` moves legacy `./.cctrace/` dirs in. Capture
modes: `mitm` (default, full first-party picture via HTTPS_PROXY +
NODE_EXTRA_CA_CERTS; `--capture-external` decrypts everything with
external bodies capped at 64KB,
`--intercept-host` enrolls extra hosts), `base-url` (messages only, no CA).

Key commands:

- `cctrace` — trace claude, open the live UI
- `cctrace view [target|latest]` — reopen a saved trace in the web UI; no
  target lists traces and prompts (Enter = newest); `--html` writes a
  self-contained snapshot instead (reads .jsonl, .jsonl.zst, .jsonl.gz)
- `cctrace clean|merge|compress|purge|compact` — log-dir housekeeping; dry-run
  by default, `--yes` applies, never deletes data not fully held elsewhere
  (purge default drop: telemetry,tokens,external; compact folds superseded
  request bodies to stubs, -95%+ with an identical session view)
- `cctrace ps` — live cctrace instances: URL, pids, client, project, session
- `cctrace --print-ca` — path to the auto-generated MITM CA

## Docs

- [README](https://raw.githubusercontent.com/thevibeworks/cctrace/main/README.md): overview, quick start, comparison, security model
- [Install & options](https://raw.githubusercontent.com/thevibeworks/cctrace/main/docs/install.md): install methods, runtime, prerequisites, full options table, `--` pass-through
- [Capture modes](https://raw.githubusercontent.com/thevibeworks/cctrace/main/docs/capture-modes.md): mitm/base-url/node, tunnel scope model, proxy internals, output format
- [Web UI](https://raw.githubusercontent.com/thevibeworks/cctrace/main/docs/web-ui.md): row chips, sessions view, context view, replay, cost, continuity, multi-instance
- [Saved traces](https://raw.githubusercontent.com/thevibeworks/cctrace/main/docs/traces.md): view/clean/merge/compress/purge/compact + housekeeping guarantees
- [Clients](https://raw.githubusercontent.com/thevibeworks/cctrace/main/docs/clients.md): codex/grok/kimi/opencode wire notes, third-party Anthropic-compatible providers
- [CHANGELOG](https://raw.githubusercontent.com/thevibeworks/cctrace/main/CHANGELOG.md): released changes
- [CLAUDE.md](https://raw.githubusercontent.com/thevibeworks/cctrace/main/CLAUDE.md): architecture and design decisions (agent-oriented)
- [SECURITY](https://raw.githubusercontent.com/thevibeworks/cctrace/main/SECURITY.md): redaction guarantees, reporting
- [Agent skill](https://raw.githubusercontent.com/thevibeworks/cctrace/main/skills/cctrace/SKILL.md): how coding agents drive cctrace (commands, UI routes, jsonl anatomy)

## Notes

- The trace .jsonl is machine-readable: one JSON pair per line with request,
  response, timing, and the session id on the wire — Claude inside
  `request.body.metadata.user_id`, codex/grok in request headers, kimi in
  `request.body.prompt_cache_key`, opencode gateway calls in the
  `x-opencode-session` header.
- A trace records a real session — treat saved traces as sensitive; review
  before sharing.