Skip to main content
AgentDiff Logo

AgentDiff

See what your AI coding agent actually did, and what it cost.

CI Build PyPI version Python Versions License: MIT

npx @kerrshift/agentdiff

or uvx --from agent-trajectory-diff agentdiff · or /agentdiff:report in Claude Code

AgentDiff reads the session logs Claude Code and the OpenAI Codex CLI already keep on your machine and tells you where the money went and what was avoidable. No config, no API key, no account. Nothing leaves your machine.

AgentDiff  ·  Claude Code  ·  last 7d
12 sessions · 7 projects · $314.61

Where the money went
  Re-reading context (cache reads)           $162.64   52%  ████████████████
  Writing context to cache                    $93.33   30%  █████████
  Model output (incl. thinking)               $51.34   16%  █████
  Background calls not in the transcript       $7.28    2%  █

Avoidable ≈ $132.08 (42% of spend, conservative estimate)
  ▸ Long context re-sent every turn  $86.64
    Start a fresh session per task; /compact before the context gets huge.
  ▸ Cache rebuilt after breaks  $45.44
    After a break of an hour or more, start a new session instead of resuming a giant one.

Biggest items
     $37.59  Long context: 434 turns re-sent >200k tokens (peak 969k)
             Refactor billing service · api
     $23.89  Cache rebuilt 7x after breaks (worst: 818k tokens after 93 min)
             Refactor billing service · api

A real week from the author's own logs (session names changed).

Why

Your agent bill shows a total, not a reason. On real Claude Code usage, most of the spend isn't the model writing code. It's the model re-reading a growing conversation on every turn, and rebuilding the prompt cache when you come back to a long session after a break. Those habits are fixable once you can see them.

What it finds

Finding What it means What to do
Long context Turns that re-sent more than 200k tokens of conversation One session per task; /compact early
Cache rebuilt after breaks The prompt cache expired and the whole context was written again at cache-write prices After a long break, start fresh instead of resuming
Stuck retries The same command failing the same way, again and again Fix the setup once
Repeated failures One kind of command failing many times in a session Usually a missing step, wrong cwd or flaky test
Unchanged files re-read The same file read repeatedly with identical content Point the agent at the right section
Identical repeated calls Same tool, same input, same output Pure cost, no new information
Expensive subagents Subagents that cost more than a few dollars (informational) Narrower brief or cheaper model

Every finding names the session and the file or command involved, with a dollar estimate. Estimates are conservative: they count the requests that made the redundant calls, not the extra context those calls added later.

Usage

agentdiff                          # last 7 days (same as: agentdiff sessions)
agentdiff --since 30d              # 24h, 7d, 30d, 12w … or all
agentdiff --project api            # only projects whose name contains "api"
agentdiff --top 10                 # list more findings and sessions
agentdiff --json > spend.json      # machine-readable
agentdiff --agent codex            # only Codex (or: claude, all)
agentdiff --path /other/.claude    # a different Claude Code config dir
agentdiff --codex-home /other/.codex  # a different Codex home

Install

Pick whatever your machine already has. Every option runs the same CLI.

You have Run once Install
Node 18+ npx @kerrshift/agentdiff npm i -g @kerrshift/agentdiff
uv uvx --from agent-trajectory-diff agentdiff uv tool install agent-trajectory-diff
pipx pipx run --spec agent-trajectory-diff agentdiff pipx install agent-trajectory-diff
Python 3.10+ pip install agent-trajectory-diff
Claude Code /agentdiff:report see below

The installed command is always agentdiff. The npm package is a small launcher for the same Python CLI at the same version. It uses uv if present, else pipx, else builds a private virtualenv once with your Python 3.10+.

Inside Claude Code

Install the AgentDiff plugin from this repository's marketplace:

/plugin install agentdiff --marketplace kerrshift/agentdiff

On Claude Code versions before 2.1.275, add the marketplace first: /plugin marketplace add kerrshift/agentdiff, then /plugin install agentdiff@agentdiff.

Then run the report in any session. Claude shows it and explains the biggest avoidable items. The plugin finds AgentDiff the same way as the npm launcher: an installed agentdiff, else uv, pipx, or Python 3.10+.

/agentdiff:report
/agentdiff:report --since 30d

Claude can also pick it up on its own when you ask things like "why is my Claude Code usage so high?". With no Python or uv at all, it tells you what to install. Without the plugin, prefix the command with ! to run it in a session: !uvx --from agent-trajectory-diff agentdiff.

How the numbers are computed

  • Source: ~/.claude/projects/**/*.jsonl (or $CLAUDE_CONFIG_DIR), including subagent transcripts, and Codex's ~/.codex/sessions/**/rollout-*.jsonl plus archived_sessions/ (or $CODEX_HOME), including subagent threads.
  • Codex: usage is read per API response (token_usage_record, or token_count in older logs) and priced at OpenAI list prices for the model active in each turn, including the long-context tier above 272K tokens and the Fast tier. Codex logs carry no cost of their own, so these are API-equivalent estimates (on a ChatGPT plan you aren't billed per token).
  • Counted once: Claude Code repeats usage on every content block of a request, and resumed or forked sessions copy their parent's history. AgentDiff counts each billed request exactly once.
  • Priced per model at Anthropic list prices: input, output, cache reads, and cache writes for both the 5-minute and 1-hour TTLs. Fast mode is included.
  • Cross-checked: when a session carries Claude Code's own cost counter, that counter is used as the total. The gap is shown as background calls not in the transcript, for example web-fetch summaries.
  • Subscriptions: on a Pro/Max plan these are API-equivalent costs. They still show which sessions and habits use the most.

Privacy

Session logs contain your source code. AgentDiff reads them locally, makes no network calls and has no telemetry.

Supported agents

Agent Status
Claude Code ✅
OpenAI Codex CLI ✅ (new in 0.7)
Gemini CLI, Cursor Planned

Also included: trajectory regression gate for agents you build

AgentDiff started as a CI gate that compares an agent's execution path against a committed baseline and fails the build on runaway loops or cost spikes. It is still included and maintained:

agentdiff diff baselines/support.envelope.json traces/candidate.json --fail-on-regression
from agentdiff import compare, load_trace
from agentdiff.testing import assert_no_regressions

report = compare(load_trace("baseline.json"), load_trace("candidate.json"))
assert_no_regressions(report, max_cost_increase_pct=5.0, allow_loops=False)

It ingests LangGraph, CrewAI, OpenAI Agents SDK, Langfuse, LangSmith, OpenInference/OpenTelemetry and a generic JSON schema, and ships a GitHub Action (kerrshift/agentdiff/.github/actions/agentdiff-check). See the cookbooks and agentdiff.app for details.

Development

git clone https://github.com/kerrshift/agentdiff.git
cd agentdiff
uv sync
make lint
make test

See CONTRIBUTING.md and the changelog.

License

MIT. See LICENSE.

Metadata

Release files for agent-trajectory-diff 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-trajectory-diff 0.7.0
File Size Uploaded Provenance Actions
agent_trajectory_diff-0.7.0.tar.gz 86.6 kB With provenance Details for agent_trajectory_diff-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-trajectory-diff 0.7.0
File Interpreter ABI Platform Actions
agent_trajectory_diff-0.7.0-py3-none-any.whl Python 3 none any Details for agent_trajectory_diff-0.7.0-py3-none-any.whl

Total release size: 200.8 kB

Release files / agent_trajectory_diff-0.7.0.tar.gz

Download URL agent_trajectory_diff-0.7.0.tar.gz
Size 86.6 kB
Tags Source
SHA-256 checksum
How to use checksums
5d24ba1c0102266490e2292539bbf637102e0274a9b3144fddff277bcc2d1821
BLAKE2b-256 checksum
How to use checksums
b7683a730a47f86c4ff55fcee279126c945a5aa15ae7a2b7097aa27225f5ca2b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.

Transparency log

Release files / agent_trajectory_diff-0.7.0-py3-none-any.whl

Download URL agent_trajectory_diff-0.7.0-py3-none-any.whl
Size 114.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c983ce2f56e77456e18b42a16eb106e7f383d42ea79dd58e3e8ab45a007d16b7
BLAKE2b-256 checksum
How to use checksums
ab3c7e22dc73c15001c04d44f9095f2ff2f2889684c5ec132e470f4b8bbe2109
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.

Transparency log

Security for agent-trajectory-diff 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agent_trajectory_diff-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page