Metadata-Version: 2.4
Name: agentcost-cli
Version: 0.1.0
Summary: Local CLI that profiles token spend for AI coding agent sessions (Claude, Cursor, Codex, Ollama).
Author-email: kashifdevfe <kashif.devfe@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/kashifdevfe/AgentCost
Project-URL: Repository, https://github.com/kashifdevfe/AgentCost
Project-URL: Issues, https://github.com/kashifdevfe/AgentCost/issues
Project-URL: Changelog, https://github.com/kashifdevfe/AgentCost/blob/main/CHANGELOG.md
Keywords: ai,agents,claude-code,cursor,codex,ollama,tokens,cost,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

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

```bash
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:

```bash
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](CONTRIBUTING.md).

## Install

Requires Python 3.10+.

```bash
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](https://pipx.pypa.io/) (isolated CLI install):

```bash
pipx install agentcost-cli
```

### For contributors (editable install)

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

## Community quick start (real local data)

```bash
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

```text
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 |
| **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 |

**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.:

```json
{
  "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)

```bash
# 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

```bash
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 --json` | Machine-readable JSON for dashboards / scripts |
| `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`)

```bash
agentcost report --provider ollama --json
agentcost smoke --json
agentcost pricing --json
```

Report JSON includes `data_quality` (`dominant`, `counts`, `dollars_are_directional`,
`pricing_as_of`) so dashboards can refuse to chart junk `$` numbers.

## 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

```bash
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:

```text
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:

```bash
agentcost doctor
```

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

```bash
agentcost smoke -v
```

## Extending AgentCost

Want to add a provider or improve analysis? See **[CONTRIBUTING.md](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`.
- Pricing table is local (as of **2026-07-24**; stale after ~45 days / **2026-09-08**). Refresh from [Anthropic](https://docs.anthropic.com/en/docs/about-claude/pricing) / [OpenAI](https://openai.com/api/pricing/) 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.

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

## License

MIT — see [LICENSE](LICENSE).
