agent-roi-tracker 0.1.0

Track the cost, usage, and ROI of your AI coding agents across every tool.

Agent-ROI

Track the cost, usage, and ROI of your AI coding agents — across every tool.

English · 繁體中文

---

What is Agent-ROI?

When you use multiple AI coding tools — Claude Code, Codex CLI, GitHub Copilot, Cursor, and others — your token spend is scattered everywhere and impossible to evaluate. Agent-ROI unifies all of it.

It reads the local session logs each tool already writes, uses a model-free semantic classifier to discover what topic / task each session was about, and then shows you how many tokens each topic consumed — so you can measure the return on investment of your agents, not just raw token counts.

The core question Agent-ROI answers: "For this feature / bug / topic, how many tokens did my agents burn — and was it worth it?"

Features

• 🔌 Tool-agnostic collectors — parse local logs from Claude Code, Codex CLI, GitHub Copilot, and Gemini CLI (no proxy, no workflow change).
• 🧠 Topic classification — a model-free semantic classifier groups sessions by topic so you see cost per subject, not per request. Runs fully offline, costs nothing, requires no external service.
• 💰 Cost & ROI tracking — token usage mapped to per-model pricing, aggregated by topic, tool, or model, over a custom time window.
• 🔎 Drill-down & trust — click any topic to see which tools and models its tokens came from; every figure is backed by a viewable pricing table, and estimated numbers are clearly badged vs exact ones.
• 🖥️ CLI — report, per-topic drill-down, and a pricing command straight from the terminal.
• 🌐 Web UI — a modern React dashboard with dimension/time controls, breakdowns, and drill-downs.
• 🗄️ Local-first — everything stays on your machine (SQLite); fully offline; classification never sends data anywhere.

Architecture

┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  Collectors  │──▶│  Classifier  │──▶│   Storage    │
│ (parse logs) │   │  (semantic)  │   │  (SQLite)    │
└──────────────┘   └──────────────┘   └──────┬───────┘
                                             │
                          ┌──────────────────┼──────────────────┐
                          ▼                                      ▼
                   ┌────────────┐                        ┌────────────┐
                   │    CLI     │                        │  REST API  │──▶ Web UI (React)
                   └────────────┘                        └────────────┘

See docs/architecture.md for details.

Install

One line (macOS / Linux / WSL). Installs uv if needed, then the agent-roi command:

curl -LsSf https://raw.githubusercontent.com/Agent-ROI/agent-roi/main/scripts/install.sh | sh

Other ways to install

# With pipx
pipx install agent-roi

# With uv
uv tool install agent-roi

To install the latest from source before a release is published, set AGENT_ROI_FROM_GIT=1 before running the install script.

Quick Start

# Ingest logs from all detected tools
agent-roi ingest

# Discover topics from your sessions (model-free, fully local)
agent-roi classify

# Cost breakdown — group by topic, tool, or model, over a time window
agent-roi report --by tool --since 7d

# Drill into one topic: which tools/models did its tokens come from?
agent-roi topic "auth refactor"

# Inspect the pricing table behind every cost figure
agent-roi pricing

# Launch the web dashboard (API + React UI), then open http://127.0.0.1:8000
agent-roi serve

Developing Agent-ROI itself? See CONTRIBUTING.md — local dev uses uv and runs the frontend on a separate Vite dev server.

Configuration

Agent-ROI looks for config at ~/.config/agent-roi/config.toml. See docs/configuration.md.

[classifier]
similarity_threshold = 0.18   # higher = more, smaller topics
label_terms = 3               # words used to name each topic

[collectors]
enabled = ["claude_code", "codex", "copilot", "gemini"]

Documentation

Doc	English	繁體中文
Architecture	architecture.md	architecture.zh.md
Configuration	configuration.md	configuration.zh.md
Collectors	collectors.md	collectors.zh.md
Contributing	CONTRIBUTING.md	CONTRIBUTING.zh.md

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and our Code of Conduct.

License

MIT © Agent-ROI contributors