I once asked Claude Code to do a moderately complex refactor. Seven or eight minutes in, the terminal was still scrolling.
I couldn't tell where it was stuck. No Bash error, the model was still producing output — it was just slow. Was it re-reading the same file dozens of times? Waiting on IO in some command? Stuck in a loop? Terminal output is all past tense: it scrolls by and it's gone. When the task finally finished, I still couldn't say where the time went.
Then I tried cctrace. Same task, but afterwards I opened the waterfall timeline. One glance: a single Bash tool call had hung for almost two minutes, with batches of fast Read calls before and after it, and a dozen tool results in between. The problem went from "no idea" to "oh, it's right there."
cctrace does one simple thing: it turns a whole agent session into a waterfall timeline you can actually read.
1. The stuff you can't see
When you run a non-trivial task with Claude Code or Codex, the terminal keeps scrolling. It looks busy, but you can't really tell:
- Which tool call took the longest — was
Readchewing through a pile of files, or wasbashwaiting on a command? - When was the model thinking, and when was it actually stuck?
- When did it fan out a subagent, and how many levels deep?
- A conversation turn ran for five minutes — where did the wall-clock time actually go?
The terminal can't answer any of this. Claude Code has no built-in profiler. The transcript files have the data, but it's line-by-line JSON you have to correlate by hand. ccglass records are a different format again. Process-level events are yet another thing. Three sources, scattered.
2. How cctrace solves it
The approach: wrap a layer around the agent before you launch it.
cctrace claude -- claude
After that one command, cctrace watches three sources at the same time:
- the agent process itself (process layer)
- writes to the transcript file (transcript layer)
- ccglass trace records (ccglass layer)
All three feed into a single Event / Session model. A heuristic pass correlates related events across sources, tagging each link with one of four confidence levels (exact / likely / possible / unknown).
Then it starts a local web server (default 127.0.0.1:43179), prints the URL, and you open the waterfall timeline in your browser.
No background daemon, no telemetry — data is only written to JSONL files on local disk.
3. What you actually see
The waterfall timeline
Events are grouped by request turn on the left; every event (user input, model reply, tool call, tool result) sits on one shared time axis. There's a density overview across the whole session up top, so you can jump to the busiest stretch. Drag horizontally to zoom, scroll vertically for the rest.
Single-event detail
Click any tool operation to see:
- arguments and output
- duration (start / end timestamp)
- correlation IDs (which events it's linked to, with the four-level confidence tag)
- the raw event JSON
"Why was this tool call so slow?" or "which later event consumed this call's result?" — click in and look.
Replay
Every session is a JSONL file on disk. After a run, any time:
cctrace view <session-id>
reopens it — no need to re-run the agent. Since it's JSONL, you can also just grep, jq, or pipe it into something else.
4. Using it
Install
With Go 1.22+:
go install github.com/androidZzT/cctrace/cmd/cctrace@latest
macOS / Linux only.
Record a Claude Code session
cctrace claude -- claude
The CLI prints the local web UI URL; open it in your browser.
Record a Codex session
cctrace codex -- codex
Same recording pipeline — switching agents is just changing the first argument.
Replay a saved session
cctrace view <session-id>
5. A few design trade-offs
The code is split by responsibility:
cmd/cctrace CLI entry point
└── internal/
├── app wires up CLI parsing, collection, persistence, server
├── trace shared Event / Session model
├── store writes sessions and events to JSONL in a session dir
├── collectors process / transcript / ccglass → trace events
├── correlate heuristic event correlation + four-level confidence
└── server local web UI + event JSON API
Why Go?
A single binary to ship — no Python environment, no Node. go install and you're done, no package-manager conflicts. For a CLI tool whose whole job is wrapping other processes, that constraint is very practical.
Why JSONL instead of SQLite?
JSONL is grep/jq-able directly, diffing two sessions is straightforward, and it pipes nicely into other tools. You don't need a dedicated viewer to read your own data.
How is correlation confidence computed?
It's heuristic — time-proximity plus event-type. For API request/response events, it looks for the nearest candidate parent within a time window (candidate types are limited to ToolCall / AgentTurn / Skill / Subagent), marks it likely if found, unknown if not. Confidence is a four-level enum (exact / likely / possible / unknown), not a numeric score. Edge cases can slip through, but a miss shows up as unknown rather than a false likely.
Does collection slow the agent down?
cctrace is a thin wrapper; collection is asynchronous and doesn't do blocking work on the agent's critical path.
6. Wrapping up
cctrace isn't trying to be a big all-in-one debugging platform. It does one thing: make the Claude Code / Codex session you're already running observable. One Go binary, MIT licensed.
It's early days — the correlation, the UI, and the set of supported event types all have room to grow. If you use Claude Code or Codex, I'd love an issue telling me what you most want to see clearly, or a PR to build it together. A star helps too if you find it useful.
GitHub: https://github.com/androidZzT/cctrace
Acknowledgement: cctrace reads traces exported by ccglass (by @jianshuo, MIT) as one of its event sources, and the cctrace <agent> -- <cmd> ergonomics are inspired by its wrap-and-inspect approach. If you want to see exactly what your agent sends to the model, ccglass is well worth a look.