devLap

cctrace: a local profiler for AI coding agents (Claude Code / Codex)

go dev.to

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 Read chewing through a pile of files, or was bash waiting 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
Enter fullscreen mode Exit fullscreen mode

After that one command, cctrace watches three sources at the same time:

  1. the agent process itself (process layer)
  2. writes to the transcript file (transcript layer)
  3. 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>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

macOS / Linux only.

Record a Claude Code session 

cctrace claude -- claude
Enter fullscreen mode Exit fullscreen mode

The CLI prints the local web UI URL; open it in your browser.

Record a Codex session 

cctrace codex -- codex
Enter fullscreen mode Exit fullscreen mode

Same recording pipeline — switching agents is just changing the first argument.

Replay a saved session 

cctrace view <session-id>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Source: dev.to

arrow_back Back to Tutorials