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 agentdiff

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

AgentDiff reads the session logs Claude Code already keeps 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 --path /other/.claude    # a different Claude Code config dir

Install

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

You have Run once Install
Node 18+ npx agentdiff npm i -g 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.
  • 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 Next
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.6.1

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.6.1
File Size Uploaded Provenance Actions
agent_trajectory_diff-0.6.1.tar.gz 81.2 kB With provenance Details for agent_trajectory_diff-0.6.1.tar.gz

Built distribution (wheel)

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

Total release size: 188.1 kB

Release files / agent_trajectory_diff-0.6.1.tar.gz

Download URL agent_trajectory_diff-0.6.1.tar.gz
Size 81.2 kB
Tags Source
SHA-256 checksum
How to use checksums
f35c90c6bd24dcda58f86bc04acb4b7e6f74e0e7719245b336c4874eaf761561
BLAKE2b-256 checksum
How to use checksums
72c43abef2d493b5a7798b2c4f471e701e08cb82190580452756bdc5b52a5b54
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.6.1-py3-none-any.whl

Download URL agent_trajectory_diff-0.6.1-py3-none-any.whl
Size 107.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dfb5e68e1ea37a00273154f4b1860ba03ce569499eee57f5471c8352a23487ce
BLAKE2b-256 checksum
How to use checksums
8bcf0250014692daaf6204e80bad138052d9385b179718d1aae55ad867b6ce14
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.6.1

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.6.1.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