Metadata-Version: 2.4
Name: agent-roi-tracker
Version: 0.2.1
Summary: Track the cost, usage, and ROI of your AI coding agents across every tool.
Project-URL: Homepage, https://github.com/Agent-ROI/agent-roi
Project-URL: Repository, https://github.com/Agent-ROI/agent-roi
Project-URL: Issues, https://github.com/Agent-ROI/agent-roi/issues
Author: Agent-ROI contributors
License: MIT
License-File: LICENSE
Keywords: ai,claude,codex,cost,llm,observability,roi,tokens
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.111
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.2
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.30
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/Agent-ROI/agent-roi/main/docs/assets/logo.svg" alt="Agent-ROI" width="72" height="72" />

# Agent-ROI

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

[![CI](https://github.com/Agent-ROI/agent-roi/actions/workflows/ci.yml/badge.svg)](https://github.com/Agent-ROI/agent-roi/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/agent-roi-tracker?label=PyPI)](https://pypi.org/project/agent-roi-tracker/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[English](./README.md) · [繁體中文](./README.zh.md)

</div>

---

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):

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

<details>
<summary>Other install methods</summary>

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

</details>

## Quick start

```bash
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](./docs/architecture.md) for details.

## Configuration

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

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

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

See [docs/configuration.md](./docs/configuration.md).

## Documentation

| | English | 繁體中文 |
|--|---------|----------|
| Architecture | [architecture.md](./docs/architecture.md) | [architecture.zh.md](./docs/architecture.zh.md) |
| Configuration | [configuration.md](./docs/configuration.md) | [configuration.zh.md](./docs/configuration.zh.md) |
| Collectors | [collectors.md](./docs/collectors.md) | [collectors.zh.md](./docs/collectors.zh.md) |
| Contributing | [CONTRIBUTING.md](./CONTRIBUTING.md) | [CONTRIBUTING.zh.md](./CONTRIBUTING.zh.md) |

## Contributing

Read [CONTRIBUTING.md](./CONTRIBUTING.md). Local dev uses `uv` for the backend and Vite for the frontend.

## License

[MIT](./LICENSE) © Agent-ROI contributors
