Agent Stats CLI

Terminal analytics for local AI coding sessions from Codex and Claude logs.

What It Does

• Scans local session logs from:
  • ~/.codex/sessions
  • ~/.codex/archived_sessions
  • ~/.claude/projects (excluding subagents)
• Shows:
  • Total sessions
  • Estimated spend
  • Tokens (input + output only, cached tokens excluded from displayed totals)
  • Today / last 7 days / last 30 days / all-time summaries
  • Model and provider breakdowns
  • Activity patterns
  • Recent sessions
  • Live auto-refresh monitor
• Includes interactive dashboard view with range switching (all, 30d, 7d)
• Checks npm for updates and shows an upgrade hint when available

Install

Run once (no install):

npx agent-stat@latest

Install globally:

npm i -g agent-stat

Quick Start

agent-stat

Running with no command opens the interactive menu (TTY).

Commands

agent-stat [menu|dashboard|summary|live|models|providers|activity|recent|update] [--json]

• menu - interactive menu (default in TTY)
• dashboard - unified overview + models with all/30d/7d range switch
• summary - today, 7d, 30d, all-time totals
• live - auto-refresh live monitor
• models - top models by spend/tokens
• providers - Codex vs Claude breakdown
• activity - hourly + weekday usage view
• recent - recent session table
• update - self-update via npm
• --json - output full analytics snapshot JSON
• -h, --help - help
• -v, --version - version

Keyboard Controls (Interactive)

• Global/menu:
  • j/k or ↑/↓ to move
  • Enter to select
  • q to quit
  • r to refresh data
• Dashboard:
  • 1 all-time
  • 2 last 30 days
  • 3 last 7 days
  • Tab or ←/→ to cycle ranges
  • b back to menu
• Live view:
  • Auto-refresh every ~2s
  • b back, q quit

No Data / Missing Folders

The CLI fails gracefully when one or both local folders are missing.

• If neither exists, you get a clear warning with expected paths.
• If one is missing, stats are still computed from the available source.

Pricing Notes

• Cost is estimated from model pricing constants in dist/cli.js.
• Displayed token totals intentionally exclude cached tokens.
• Unknown/unpriced models are surfaced in output where relevant.

Development

node --check dist/cli.js
node dist/cli.js --help
node dist/cli.js summary
node dist/cli.js dashboard

Publish to npm

npm login
npm whoami
npm publish --access public

If your account enforces 2FA, publish with a token or OTP per npm policy.

Package

• npm package: agent-stat
• binary: agent-stat