agent-roi-tracker 0.4.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 · 繁體中文

---

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

macOS / Linux / WSL:

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/Agent-ROI/agent-roi/main/scripts/install.ps1 | iex

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 roi --since 7d                  # cost vs. active dev time, per topic
agent-roi serve                           # web dashboard on http://127.0.0.1:8000
agent-roi doctor                          # see which tools were detected and why
agent-roi mcp-cost                        # estimate each MCP server's per-turn overhead

Features

Tool-agnostic	Reads local logs from Claude Code, Codex CLI, GitHub Copilot, Gemini CLI, and Hermes Agent — 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
Time, not just cost	Estimates active development time per topic/session (gaps between turns, idle stretches excluded via a threshold derived from your own usage — no magic constant), so cost is weighed against time spent and a $/hour burn rate. agent-roi roi ranks topics and flags the steepest rates
Where tokens go	Splits every total into overhead (system prompt + tool + MCP schemas), cached re-sent context, and actual work — so you see what your tokens are really spent on
Activity analysis	Concrete actions behind the cost: which tools and MCP servers were called, how often, how many tokens each returned, and which files were touched most
MCP cost	agent-roi mcp-cost estimates each MCP server's per-turn schema overhead (opt-in; launches the servers to read their tool list)
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	✅
Hermes Agent	✅
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", "hermes"]

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