agentprof

agentprof

A profiler for AI coding agents: see where your agents spend time, tokens and money.

agentprof reads the session logs that Claude Code, OpenAI Codex CLI and VS Code Copilot Chat already write on your machine. It shows each session as a call tree of turns, subagents and tool calls, with an inline timeline, token counts, context growth, costs and hints about likely waste. Everything runs locally, so your sessions never leave your machine.

Features

• Call tree with timeline: every prompt, subagent and tool call becomes a row with its duration, cost, tokens and peak context, next to a timeline bar for when it ran. Nested subagents get their own colour-coded agent numbers, so you can follow a delegation chain at a glance.
• Cost and token accounting: costs and tokens are given both per node and rolled up per subtree, with input, output, cache read and cache write tokens counted separately. Estimated values are marked ≈, and values the logs do not contain are shown as – instead of being guessed.
• Context tracking: see how the context window grows call by call, where it peaks and where it was compacted.
• Agent summary: one row per agent with its model, cache TTL, resumes, duration, own cost, share of the session cost and token breakdown.
• Node details: open any turn or agent to see its timeline, cost per LLM call, context chart, subagents and a searchable list of LLM and tool calls, down to the raw prompt, result and tool arguments.
• Waste findings: hints, not verdicts, about where time and money may have gone (see Findings).
• Live updates: the session list fills in within seconds, and open sessions update while an agent is still working.
• JSON API for AI agents: everything in the UI is also available as compact JSON, so an AI agent can analyse sessions itself, including how the agents and subagents in them worked together.

Installation

agentprof is a command-line tool that starts a local web app. Install it in its own isolated environment with uv or pipx:

uv tool install agentprof
# or
pipx install agentprof

Or run it once without installing it:

uvx agentprof

agentprof requires Python 3.12 or newer.

Usage

agentprof

This starts a local server on 127.0.0.1:8765 and opens your browser. The session list appears immediately and fills in while sessions are summarised in the background; a session is analysed in full when you open it.

agentprof [SESSION] [--host 127.0.0.1] [--port 8765] [--no-browser]
          [--claude-root DIR] [--codex-root DIR] [--copilot-root DIR]
          [--pricing FILE]

Supported agents

Claude Code and Codex costs are API-equivalent estimates; on a subscription you do not pay per token. Costs keep their native unit and are never added across units.

Findings

agentprof flags likely waste as hints, not verdicts. Each finding is attached to the turn or agent it is about, and the session header counts them.

Local API for AI agents

agentprof is useful to people, and just as useful to AI agents. While it runs, everything it knows about a session is available as JSON on the same port, so you can point an agent at a session and ask it what went wrong, why a run was expensive or how its subagents worked together.

The API is built for this:

• Self-describing: /api lists every endpoint with its parameters, and each session page links to its JSON, so a URL from the browser is enough to start with. /sessions/{id}?format=json returns the same data as the API route.
• Agent by agent: /summary gives one row per agent with its parent agent, so the delegation tree can be rebuilt without the full call tree. Each row has the agent's topic, models, LLM calls, peak context, tokens, cache TTL, resumes, longest gap, its own cost and the cost of everything it delegated.
• Findings first: /findings puts the likely waste with the highest estimated cost first.
• Bounded downloads: depth and fields cut a large call tree down to what fits in a context window; prompts, results and tool arguments are only fetched for the node that needs them.
• Honest numbers: every value says whether it is exact, estimated or n/a, so an agent can tell measurements from guesses.

For example, ask your agent:

agentprof is running on http://127.0.0.1:8765. Start at /api, open session
claude-code:<id> and explain which subagents drove the cost, where they
waited for each other, and what we could do differently next time.

Development

./bootstrap.sh             # install uv, Node (nvm), pnpm and all dependencies
uv run agentprof           # run against your own sessions
pnpm --dir frontend dev    # frontend dev server, proxies /api to port 8765
uv run qa                  # lint, type check and tests for Python and the frontend
uv run build-dist          # build and smoke-test the distributions

See docs/architecture.md for how the code fits together, AGENTS.md for conventions and docs/releasing.md for releases.

License

MIT