agent-profiler

agent-profiler times a Claude Code session and splits it into waiting for the model, running tools, blocking subagents and the engine’s own overhead. It shows the split live, explains it with /profile, and saves the session as OpenTelemetry (OTLP) traces you can open in Jaeger or Grafana Tempo.

What it does

• /profile reports the session, /profile turn the last turn: time per category, model requests with time to first token (average and p95), tokens with cache reads, tool execution against approval wait, the five slowest calls, Bash time by kind (test, build, install, git, search), files read more than once and each subagent’s model and tool time.
• Findings close the report when a share crosses a threshold: the model at 70% of the time, tests at a quarter, approval waits at a fifth (with a hint to add allow rules), one call at 30%, a blocking subagent at half. A file read again twice with no edit in between gets one too.
• A status line shows the model and tool shares and the call running longest. /profile-pane opens a pane with the category bars, what is running now, the slowest tools and the latest findings.
• Each figure is graded: measured by Claude Code (a tool’s execution time), observed by the mod between events, reported by the API (tokens) or inferred as the remainder. Idle time between turns is left out.

Install

Needs Claude Code 2.1.287 or later.

claude plugin marketplace add YeonwooSung/my-claude-code-mods
claude plugin install agent-profiler@my-claude-code-mods

Recording starts with the session; run /profile or /profile-pane. The marketplace holds five more mods by the same author (time-machine, loop-detective, pin-memo, model-effort-band and token-run), each installed on its own. Its sibling context-inspector does for the context window what this one does for time.

Traces in Jaeger or Tempo

After every turn the mod writes what finished in it as an OTLP JSON file under ~/.claude/agent-profiler/<sessionId>/, and /profile-export writes a full snapshot. Spans use the OpenTelemetry GenAI names (chat <model>, execute_tool <tool>, invoke_agent <type>), and the trace id is the session id, so sending a session twice yields the same spans.

To send them as they are written, set otlpEndpoint in the plugin’s settings (the /plugin menu or pluginConfigs); each file goes to <endpoint>/v1/traces. The repo ships a Docker Compose file for a local Jaeger. From a clone:

docker compose -f agent-profiler/examples/jaeger/docker-compose.yml up -d

Set otlpEndpoint to http://localhost:4318, open http://localhost:16686 and pick the service claude-code. Tempo and the OpenTelemetry Collector take the same endpoint. To import files written earlier, the README has a curl loop; send the numbered batches or the full snapshot, not both.

How it works

The module wraps each tool call and model request to time them, and reads Claude Code’s own tool durations and subagent start and stop events. From each tool call it keeps a summary of the input: the Bash command line, file paths and read ranges, Glob and Grep patterns, the subagent type. It also keeps the first 120 characters of each prompt. Memory holds up to 20,000 requests and tool calls; past that the oldest finished turns are dropped, after they were written to disk.

The trace files carry timings, model names, token counts, tool names, file paths, search patterns and a category for each Bash command. Prompts and command lines stay out unless you turn on exportCommandText, whose redaction catches only common secret shapes such as bearer tokens, --password and NAME=value where the name contains KEY, TOKEN, SECRET or PASSWORD. Nothing leaves the machine while otlpEndpoint is empty, the default. Once you set it, every batch goes to that collector, file paths and search patterns included. The mod makes no model calls, costs no tokens, and never deletes old trace folders.

Limitations

• Model time is how long the session waited for a response, not compute time inside the model. Time to first token bundles network, queueing and prefill, and engine retries show up as a longer wait.
• Files changed through Bash are invisible to the re-read check.
• A hot reload starts the report and the pane over; files already written stay.
• Subagents have no turn spans of their own, and a background subagent’s span outlives the Agent call that launched it.
• At session end the POST gets at most 1.5 seconds; the file is written first, so a dropped batch can be sent by hand.
• The author documents the pane and status line in the terminal and the Desktop Code tab. In the VS Code chat panel and claude -p the mod records and /profile answers, but nothing draws.
• The author’s test suite ran on 2.1.292 and the Jaeger import on 2.1.280; the repo notes that the live pane still needs an interactive check.
• The repository has no license file, so its code comes with no stated terms of reuse.