agent-usage-atlas

Agent Usage Atlas

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

一个从本地 AI 编程 Agent 日志生成可视化仪表盘的工具。支持 Codex CLI / Claude Code / Cursor 三大 Agent 栈，25+ 交互式图表，纯 Python 标准库实现。

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/, ~/.claude/, ~/.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

Pricing covers GPT-5.x, Claude 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
• Multi-agent unified view — Claude Code + Codex CLI + Cursor in one dashboard, with per-source drill-down
• Cost analytics — per-model, per-day, per-session cost estimation with 30-day burn rate forecasting
• Tool call intelligence — ranking, frequency density, bigram sequences, command success rates
• Cache efficiency tracking — hit rate, savings estimation, cache vs. uncached token split
• Working pattern heatmap — hour × weekday activity distribution to find your flow states
• Session deep-dive — duration histogram, complexity scatter, median session cost
• Live dashboard mode — SSE-powered auto-refresh server with date range tabs (All / 7 days / Today)
• Bilingual narratives — auto-generated story summaries in both Chinese and English
• Animated data updates — stock-style green/red flash on number changes in live mode
• Single self-contained HTML — one file, works offline, shareable, archivable
• Zero dependencies — pure Python standard library, no npm/Node/Rust/Docker required
• Fully local — all data stays on your machine, nothing sent anywhere

Screenshots

Installation

pip (recommended)

pip install agent-usage-atlas

Homebrew

brew install heggria/tap/agent-usage-atlas

From source

git clone https://github.com/heggria/agent-usage-atlas.git
cd agent-usage-atlas
pip install .

Usage

# Default: last 30 days, output to ./reports/dashboard.html
python -m agent_usage_atlas

# Last 7 days
python -m agent_usage_atlas --days 7

# Custom start date
python -m agent_usage_atlas --since 2026-03-01

# Custom output path and auto-open in browser
python -m agent_usage_atlas --output /tmp/dashboard.html --open

# Start live dashboard with auto-refresh (SSE)
agent-usage-atlas --serve --interval 5 --open

# Live dashboard on custom host/port
agent-usage-atlas --serve --port 8765 --host 127.0.0.1 --interval 5

CLI Options

Live Mode Endpoints

How It Works

~/.codex/**/*.jsonl  ─┐
~/.claude/**/*.jsonl ─┼─→  Parse  →  Aggregate  →  Render  →  dashboard.html
~/.cursor/**/*.jsonl ─┘     (parallel)   (rollup)    (ECharts)

1. Parse — Reads JSONL log files and SQLite databases from each agent's local directory. Codex uses cumulative-delta token counting; Claude deduplicates by message ID; Cursor tracks activity counts.
2. Aggregate — Computes source rollups, daily rollups, session rollups, tool bigrams, chord diagram data, Sankey flows, burn rate projections, heatmaps, and narrative text.
3. Render — Injects the aggregated data into a self-contained HTML template with ECharts visualizations. In live mode, an SSE server pushes updates when log files change.

All data stays local — nothing is sent to any server.

Comparison with Alternatives

Key Differentiators

1. Unified multi-agent dashboard — the only tool that tracks Claude Code + Codex CLI + Cursor simultaneously from local logs in a single view
2. Richest visualization suite — 25+ chart types including Sankey flows, chord diagrams, tool-call bigrams, heatmaps, burn rate projections, calendar views
3. True zero dependencies — Python stdlib only, no npm/Node/Rust/Docker/database required
4. Single self-contained HTML — one file, works offline, email it to yourself, archive it
5. Live SSE server — real-time auto-refresh with date range switching (All / 7 days / Today)
6. Cache efficiency analytics — unique among local tools, tracks savings and hit rates
7. Animated transitions — smooth number counter animations with stock-style green/red flash on live data refresh
8. Bilingual narrative — auto-generated story/summary in both Chinese and English

Architecture

src/agent_usage_atlas/
├── cli.py          # CLI entry point, build_dashboard_payload()
├── parsers.py      # Codex / Claude / Cursor log parsers
├── models.py       # UsageEvent, ToolCall, SessionMeta + pricing (GPT-5, Claude 3–4.6, MiniMax)
├── aggregation.py  # Full dashboard payload computation (CN + EN narratives)
├── template.py     # Self-contained HTML/CSS/JS template (number flash animations)
└── server.py       # Live SSE server (stdlib http.server)

License

MIT