PACKAGE EXPLORERView in registry

agent-roi-tracker

PyPI

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

Versions collected1

Direct dependencies15From release 0.5.0

Last observed20 Oct, 23:13 UTC

README

Version 0.5.0 documentation

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?"

Agent-ROI overview dashboard — cost trends, token composition, and active development time

_{The overview: where your tokens and dollars go, plus how long you actually spent.}

Agent-ROI unit-cost page — average cost, time, and tokens to finish one piece of work per topic, with a consistency signal

_{Unit cost: what one piece of work of each kind typically costs — and how consistent it is.}

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

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Versions 1

Collected releases

Version	Published	Direct dependencies	Open version
0.5.0	22 Jun 2026	15

Package advisories

No matching advisories collected

This describes our collected data; it is not a security assessment.

Repository

PENDING

agent-roi/agent-roi

Shared repository data · GitHub

License detected in repository: Not collected

Metadata history

Meaningful changes

Current collected state Current

Observed since 20 Oct, 23:13 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package:c8ac0ecf020d79aaf55ae261968989190ab4787c16c2b10e85fbc3b22e401bd3