agentic-metric-x 0.2.3

Minimal personal-usage monitor for Codex + Claude Code

Agentic Metric X

中文文档

A local-only monitoring tool for AI coding agents — like top, but for your coding agents. Track token usage and costs across Claude Code and Codex — with a TUI dashboard and CLI.

Supported platforms: Linux, macOS, and Windows.

All data stays on your machine. No network requests, no telemetry, no data leaves your computer. The tool only reads local agent data files (~/.claude/, ~/.codex/) and process info.

Features

• Live monitoring — Detect running agent processes, incremental JSONL session parsing
• Cost estimation — Per-model pricing table with CLI management, calculates API-equivalent costs
• Unified report — One report command for today / week / month / custom date range, with agent × model breakdown, top projects, top sessions, and hourly/daily/weekly heatmaps
• TUI dashboard — Terminal UI with live refresh, stacked summary cells, heatmap strip, 30-day cost chart, and agent × model breakdown
• Multi-agent — Plugin architecture; supports Claude Code and Codex today, extensible

Agent Data Coverage

Field	Claude Code	Codex
Session ID	✓	✓
Project path	✓	✓
Git branch	✓	✓
Model	✓	✓
Input tokens	✓	✓
Output tokens	✓	✓
Cache tokens	✓	✓¹
User turns	✓	✓
Message count	✓	✓
First/last prompt	✓	✓
Cost estimation	✓	✓
Live active status	✓	✓

¹ Codex exposes cache-read tokens only; cache-write is not reported. Codex's input_tokens already includes cached tokens, so the collector stores input_tokens − cached_input_tokens to avoid double-charging at both input and cache-read pricing.

Installation

Requires Python 3.10+.

pip install agentic-metric-x

Or with uv:

uvx agentic-metric-x              # Run directly without installing
uv tool install agentic-metric-x   # Or install persistently
uv tool upgrade agentic-metric-x   # Upgrade to latest version

Usage

agentic-metric                       # Launch TUI dashboard (default when no command given)
agentic-metric tui                   # Launch TUI dashboard explicitly
agentic-metric sync                  # Force sync collectors to the local database
agentic-metric report --today        # Today's usage report
agentic-metric report --week         # This week (Mon → today)
agentic-metric report --month        # This month
agentic-metric report --range 2026-04-01:2026-04-23   # Custom date range
agentic-metric today                 # Shortcut for `report --today`
agentic-metric week                  # Shortcut for `report --week`
agentic-metric month                 # Shortcut for `report --month`
agentic-metric history -d 30         # Last N days (default 14)
agentic-metric pricing               # Manage model pricing

report shows a header with total cost / sessions / turns / tokens / cache-hit rate, a delta vs. the previous equivalent period, a heatmap strip (hours for --today, days for --week, weeks for --month), a 30-day cost chart, and breakdowns by agent × model, top projects, top sessions, and time buckets.

Pricing Management

Model pricing is used for cost estimation. Builtin pricing is included for common models. You can add new models or override existing prices via CLI — overrides are stored in $DATA/agentic_metric/pricing.json.

agentic-metric pricing list                                                # List all model pricing
agentic-metric pricing set deepseek-r2 -i 0.5 -o 2.0                       # Add a new model
agentic-metric pricing set claude-opus-4-7 -i 4.0 -o 20.0 -cr 0.4 -cw 5.0  # Override builtin
agentic-metric pricing reset deepseek-r2                                   # Reset a model to builtin default
agentic-metric pricing reset --all                                         # Reset all overrides

Unknown models are not priced by default. They are displayed as Unknown with cost ? until you add explicit pricing with agentic-metric pricing set.

TUI Keybindings

Key	Action
← / →	Switch view (Today / Week / Month)
↑ / ↓	Move time range earlier / later
.	Jump back to "now" (reset offset)
t / w / m	Focus Today / Week / Month directly
r	Refresh data
q	Quit

Data Sources

Paths differ by platform. $DATA refers to:

	Linux	macOS	Windows
$DATA	~/.local/share	~/Library/Application Support	%LOCALAPPDATA%

Agent	Path	Data
Claude Code	~/.claude/projects/	JSONL sessions, token usage, model, branch
Claude Code	~/.claude/stats-cache.json	Daily activity stats
Claude Code	Process detection	Running status, working directory
Codex	~/.codex/sessions/	JSONL sessions, token usage, model
Codex	Process detection	Running status, working directory

Claude Code honors CLAUDE_CONFIG_DIR and Codex honors CODEX_HOME — if you have relocated either agent's config directory, the collectors pick up the environment variable automatically.

All aggregated data is stored locally in $DATA/agentic_metric/data.db (SQLite).

Unsupported Agents

• Cursor — Cursor stopped writing token usage data (tokenCount) to its local state.vscdb database around January 2026 (approximately version 2.0.63+). All inputTokens/outputTokens values are now zero. Cursor has moved usage tracking to a server-side system. Since this tool is designed to be fully offline with no network requests, monitoring Cursor usage is not supported.
• OpenCode / Qwen Code / VS Code Copilot Chat — collectors for these agents existed up to v0.1.8 and were removed in v0.2.0 as this fork narrowed its focus to Claude Code and Codex. If you need them, stay on v0.1.8 from upstream.

Privacy

• Fully offline — no network requests, no data sent anywhere
• Read-only — never modifies agent config or data files
• All stats stored in a local SQLite database
• Delete the data directory at any time to remove all data (~/.local/share/agentic_metric/ on Linux, ~/Library/Application Support/agentic_metric/ on macOS, %LOCALAPPDATA%\agentic_metric\ on Windows)

Development

git clone https://github.com/xihuai18/agentic-metric
cd agentic-metric
pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.

Forked from MrQianjinsi/agentic-metric (v0.1.8 upstream). See CHANGELOG.md for what changed in this fork.