agent-usage-atlas

# Agent Usage Atlas

**English** | [中文](README_CN.md)

[![PyPI version](https://img.shields.io/pypi/v/agent-usage-atlas)](https://pypi.org/project/agent-usage-atlas/)
[![PyPI downloads](https://img.shields.io/pypi/dm/agent-usage-atlas)](https://pypi.org/project/agent-usage-atlas/)
[![Python](https://img.shields.io/pypi/pyversions/agent-usage-atlas)](https://pypi.org/project/agent-usage-atlas/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> Turn your local AI coding agent logs into a rich, interactive analytics dashboard — zero dependencies, fully offline, one command.

<p align="center">
  <a href="https://heggria.github.io/agent-usage-atlas/demo/"><strong>Live Demo →</strong></a>
</p>

<!-- TODO: replace with GIF once recorded with vhs -->
![Hero Overview](docs/screenshots/en/hero-overview.png)

## Why Agent Usage Atlas?

You're burning tokens across multiple AI coding agents every day — but **how much** are you actually spending? Which model is the most cost-effective? When are you most productive? Are your caches saving you money?

Agent Usage Atlas reads your local log files (`~/.codex/`, `~/.cursor/`, `~/.cursor/`), crunches the numbers, and generates a single self-contained HTML dashboard with 25+ interactive charts. No API keys, no cloud uploads, no dependencies beyond Python itself.

## Supported Agents

| Agent | Token Tracking | Cost Estimation | Tool Call Tracking | Session Meta |
|-------|:-:|:-:|:-:|:-:|
| [Codex CLI](https://github.com/openai/codex) (GPT-5 family) | ✅ | ✅ | ✅ | ✅ |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Cursor 3–4.6) | ✅ | ✅ | ✅ | ✅ |
| [Cursor](https://www.cursor.com/) | Activity only | — | — | — |

> Pricing covers GPT-5.x, Cursor 3/3.5/4.x (Haiku/Sonnet/Opus), and MiniMax-M2 out of the box.

## Features

- **25+ interactive ECharts visualizations** — cost trends, token breakdowns, Sankey flows, chord diagrams, heatmaps, radar charts, calendar views, burn rate projections