agentcost-cli 0.2.0

Local CLI that profiles token spend for AI coding agent sessions (Claude, Cursor, Codex, Ollama).

AgentCost

Local open-source CLI that profiles what drives token spend in AI coding agent sessions — not just totals. Real logs from your machine. No cloud, no auth, no dashboard.

pip install agentcost-cli
agentcost doctor
agentcost smoke -v

Which AI tools can you connect?

AI tool	Provider ID	How AgentCost connects	Status
Claude Code	claude	Reads local transcripts in ~/.claude/projects/**/*.jsonl	Supported
Cursor Agent	cursor	Reads ~/.cursor/projects/**/agent-transcripts/**/*.jsonl	Supported
OpenAI Codex CLI	codex	Reads ~/.codex/sessions/**/rollout-*.jsonl	Supported
Ollama (local)	ollama	Records via agentcost smoke or ollama-proxy into ~/.agentcost/ollama/	Supported

List adapters anytime:

agentcost providers
agentcost list --provider claude
agentcost list --provider cursor
agentcost list --provider codex
agentcost report --provider ollama -v

Not connected yet (good first issues)

ChatGPT web/app, Gemini CLI, GitHub Copilot Chat, Aider, Continue, Windsurf, Cline, OpenCode, etc. These can be added as new provider adapters — see CONTRIBUTING.md.

Install

Requires Python 3.10+.

pip install agentcost-cli

The console command is still agentcost (PyPI name is agentcost-cli because agentcost is already taken by another project).

Or with pipx (isolated CLI install):

pipx install agentcost-cli

For contributors (editable install)

git clone https://github.com/kashifdevfe/AgentCost.git
cd AgentCost
pip install -e ".[dev]"

Community quick start (real local data)

agentcost doctor
ollama pull llama3.2:1b          # if needed
agentcost smoke -v               # real multi-turn local run + report
agentcost report --provider ollama -v

Default fallback model: llama3.2:1b (override with --model or AGENTCOST_OLLAMA_MODEL).

Example: what a good report looks like

FOUNDER SNAPSHOT (plain English)
  This was a LOCAL session (llama3.2:1b). API dollar cost is $0 ...
  Main driver: 84% of token volume came from `user_turn` ...
  No major waste flags - session looks relatively healthy.

TOTALS
  tokens  in=188  out=34  ...
  avg/turn in~62  out~11
  time    2.8 s wall generation

BY CALL TYPE (share by tokens)
  #############---  84.2%  user_turn       -> Later user messages
  ###-------------  15.8%  initial_prompt  -> First user message

ANOMALIES / INSIGHTS
  INFO [local_ollama] Ollama is local - API $ is $0 ...

WHAT TO DO NEXT
  - Local run: optimize for latency/tokens, not dollars.

Cloud agents (Claude / Codex) show estimated $ instead of $0.

What founders should look for

Signal	Why it matters
Estimated $ (cloud)	Rough session bill before finance sees the invoice
Main driver %	Is spend from one prompt, or endless agent loops?
HIGH / WARN anomalies	Waste patterns: tool loops, context re-sends
WASTE ALERTS	First-class cuttable loops (same file re-read, identical retries) — not buried ledger noise
Hottest tool	One tool (e.g. Read on the same file) eating the budget
Local $0 + time	For Ollama: money isn't the metric — tokens/latency are
agentcost outcome	Cost per merged PR (local git) — spend ÷ value shipped

Healthy: initial prompt owns a fair share; tool loops are short.
Unhealthy: tool_followup or one hot file is 60%+ of the session.

What developers should look for

Field	Meaning
in / out	Input vs output tokens per session or turn
cache_read / cache_write	Prompt-cache reuse (Claude etc.)
call type	initial_prompt, user_turn, tool_followup, text_response
quality=estimated/placeholder	Numbers may be incomplete — treat $ as directional
TOP CALLS (-v)	Heaviest turns + tool targets
Log summary lines	Grep-friendly one-liners in ~/.agentcost/ollama/*.jsonl

Ollama JSONL includes human fields, e.g.:

{
  "summary": "turn=2 model=llama3.2:1b in=58 out=17 ms=900.1",
  "request_preview": {"prompt": "...", "messages": 3},
  "response_preview": "A token represents..."
}

Live chat example (Ollama proxy)

# terminal A
agentcost ollama-proxy

# terminal B
set OLLAMA_HOST=127.0.0.1:11435
ollama run llama3.2:1b

# terminal C (optional live view)
agentcost watch --provider ollama

# after chatting
agentcost report --provider ollama -v

Analyze Claude / Cursor / Codex

agentcost list
agentcost list --provider cursor
agentcost report --provider claude -v
agentcost report --provider codex
agentcost watch --provider claude

Commands

Command	Purpose
doctor	First-run health check (missing paths are normal + explained)
pricing / pricing --check	Show local $/MTok table; exit 1 if stale
smoke	Real Ollama local test (llama3.2:1b fallback)
report	Founder + developer attribution report
report --fail-on-waste	Exit 1 when HIGH/WARN waste alerts fire (CI / hooks)
report --json	Machine-readable JSON for dashboards / scripts
outcome	Cost per merged PR / shipped commit (local git, last N days)
list	Discover sessions
providers	Show adapters
watch	Live-tail a growing transcript
ollama-proxy	Record usage for external Ollama clients
hook-session-end	Claude Code SessionEnd hook

Machine-readable output (--json)

agentcost report --provider ollama --json
agentcost smoke --json
agentcost pricing --json
agentcost outcome --days 7 --json

Report JSON includes data_quality, waste_alerts (cuttable loops with actions), and dollars_are_directional so dashboards can refuse to chart junk $ numbers.

Cost per outcome (not vanity session totals)

Raw token/$ totals are easy to glance at once and ignore. Divide spend by value shipped:

agentcost outcome --days 7

Uses local git only (merge / PR-merge commits; falls back to first-parent commits if needed). No cloud, no ticket APIs. $ stay DIRECTIONAL when session usage was estimated.

Waste alerts (ship the alert, not just the ledger)

When an agent re-reads the same file or retries the identical tool call, AgentCost prints a WASTE ALERTS block before the totals ledger — with a Monday action.

agentcost report --path path/to/session.jsonl -v
agentcost report --path path/to/session.jsonl --fail-on-waste   # exit 1 for CI/hooks

Healthy chat sessions (e.g. agentcost smoke) should show no waste alerts.

Pricing freshness (trust risk)

Cloud $ estimates use a hardcoded table in agentcost/pricing.py.

• As of: 2026-07-24 (PRICING_AS_OF)
• Stale after: 45 days (STALE_AFTER_DAYS) → warning starts 2026-09-08
• CI reminder: .github/workflows/pricing-stale.yml runs weekly (pricing --check), fails the workflow, and opens/comments a pricing-stale issue so this does not rely on memory

agentcost pricing
agentcost pricing --check    # exits 1 when stale + prints update steps

Where to get current per-token rates

Vendor	Official pricing page
Anthropic (Claude)	https://docs.anthropic.com/en/docs/about-claude/pricing
OpenAI (GPT / Codex)	https://openai.com/api/pricing/

Ollama / local models stay $0 by design (no cloud invoice).

When pricing --check says STALE

1. Open the vendor pages above and copy current $/MTok (input, output, cache if listed).
2. Edit MODEL_RATES in agentcost/pricing.py.
3. Set PRICING_AS_OF to today's UTC date in the same file.
4. Run python -m agentcost pricing --check (must exit 0).
5. Commit rates + date together (do not bump the date without verifying rates).

Reports and doctor also surface pricing age so screenshots do not hide staleness.

Data quality is loud on purpose

Cursor (and sometimes Claude streaming logs) may omit real usage. The terminal report prints a DATA QUALITY block before the founder snapshot:

DATA QUALITY
  turns: good=0  estimated=5  placeholder=0  partial=0  dominant=estimated
  !!! DO NOT TREAT $ AS INVOICE TRUTH !!!
  5/5 turns ESTIMATED from text length ...

If you screenshot numbers publicly, keep that block visible.

First-run experience

Fresh install with no Claude/Cursor/Codex history yet:

agentcost doctor

Expect MISS / EMPTY for unused agents - that is normal. Doctor explains each path and points you at:

agentcost smoke -v

Extending AgentCost

Want to add a provider or improve analysis? See CONTRIBUTING.md (project layout, adapter checklist, contract, and suggested first PRs).

Honest limits

• Claude JSONL usage can include streaming placeholders - cache fields are more reliable.
• Cursor transcripts often omit usage; AgentCost estimates from text and marks $ DIRECTIONAL.
• Ollama does not store per-call usage natively - use smoke or ollama-proxy.
• outcome uses local git merges (or first-parent commits as a weaker fallback) — not Jira/Linear yet.
• Pricing table is local (as of 2026-07-24; stale after ~45 days / 2026-09-08). Refresh from Anthropic / OpenAI and run agentcost pricing --check. Weekly GitHub Action reminds maintainers. Ollama API $ is always $0.

Dev / CI

fixtures/ is for unit tests (pytest), not end-user demos.

pip install -e ".[dev]"
python -m pytest -q

License

MIT — see LICENSE.