agent-roi-tracker 0.2.1

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 · 繁體中文

---

When you use multiple AI coding tools — Claude Code, Codex CLI, GitHub Copilot, Cursor, Gemini CLI — your token spend is scattered and impossible to evaluate. Agent-ROI reads the local logs each tool already writes, uses a model-free semantic classifier to discover what topic each session was about, and shows you how many tokens each topic consumed.

"For this feature / bug fix / topic — how many tokens did my agents burn, and was it worth it?"

Install

One line (macOS / Linux / WSL):

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

Installs uv if needed, then the agent-roi command. No Python version management needed.

Other install methods

pipx install agent-roi-tracker
# or
uv tool install agent-roi-tracker

Set AGENT_ROI_FROM_GIT=1 before running the install script to get the latest from source.

Quick start

agent-roi ingest                          # parse logs from all detected tools
agent-roi report --by topic --since 7d   # cost per topic this week
agent-roi serve                           # web dashboard on http://127.0.0.1:8000

Features

Tool-agnostic	Reads local logs from Claude Code, Codex CLI, GitHub Copilot, and Gemini CLI — no proxy, no workflow change
Topic classification	Model-free TF-IDF + cosine-similarity clustering; runs fully offline, no API keys
Cost & ROI	Token usage mapped to per-model pricing, aggregated by topic, tool, or model, over any time window
Drill-down	Click any topic to see which tools and models contributed; estimated vs exact counts clearly badged
Local-first	Everything in one SQLite file; data never leaves your machine

Supported tools

Tool	Status
Claude Code	✅
Codex CLI	✅
GitHub Copilot	✅
Gemini CLI	✅
Cursor	🔜

Architecture

Collectors ──▶ Storage ──▶ Classifier ──▶ Storage ──▶ CLI / API / Web
(parse logs)   (SQLite)    (semantic)     (topics)

Both the CLI (typer) and REST API (fastapi) are thin shells over a single Service class. See docs/architecture.md for details.

Configuration

~/.config/agent-roi/config.toml (all fields optional — works with zero config):

[classifier]
similarity_threshold = 0.18   # higher = more, smaller topics
label_terms = 3

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

See docs/configuration.md.

Documentation

	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

Read CONTRIBUTING.md. Local dev uses uv for the backend and Vite for the frontend.

License

MIT © Agent-ROI contributors