0.2.0

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?

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

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

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

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

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.