agent-usage

A Go CLI tool to track AI coding agent usage (Codex, Claude Code). Monitor your agent usage statistics, sync sessions, and analyze productivity metrics.

Features

• Multi-agent Support: Track usage for Codex and Claude Code agents
• Session Tracking: Automatically parses and stores session data from agent log files
• Usage Statistics: View daily, weekly, and monthly usage stats
• Auto-sync: Automatically sync sessions before viewing stats
• Cost Tracking: Estimated costs based on token usage
• Project-level Insights: See which projects use the most agent time

Installation

# Clone and build
git clone https://github.com/ari/agent-usage.git
cd agent-usage
make build

# Or use Go directly
go build -o agent-usage .

# Install globally
make install
# or
go install .

Build Commands

make build        # Build to build/agent-usage
make build/osx    # Build for macOS
make build/linux  # Build for Linux
make build/windows # Build for Windows
make test         # Run tests
make clean        # Clean build artifacts

Quick Start

1. Create a config file at ~/.agent-usage/config.toml:

[agents]
codex = true
claude = true

2. View usage statistics (syncs automatically):

./agent-usage stats            # Combined stats for all agents
./agent-usage usage codex     # Codex-specific stats
./agent-usage usage claude    # Claude-specific stats

Commands

Command	Description
./agent-usage stats [period]	Show combined usage stats
./agent-usage usage <agent> [period]	Show per-agent stats
./agent-usage session <agent> [--limit N]	Show recent sessions for one agent
./agent-usage info	Show loaded configuration
./agent-usage --help	Show help

Period Options

For stats and usage commands, specify a time period:

• day - Last 24 hours (default)
• week - Last 7 days
• month - Last 30 days

Configuration

Config file location: ~/.agent-usage/config.toml

# Database path (optional, defaults to ~/.agent-usage/usage.db)
database = ""

[agents]
codex = true           # Enable Codex tracking
claude_code = true     # Enable Claude tracking

Custom Config Path

Use -c or --config flag to specify a custom config:

./agent-usage -c /path/to/config.toml stats

Output Examples

Stats Command (with sync loader)

Agent Sync NEON MODE
Scanning sessions and updating usage DB...

⠋ Claude   184/184   +3 new  ~1 upd  -180 skip  complete
⠋ Codex     42/42    +2 new  ~0 upd   -40 skip  complete

Sync complete
Elapsed 1.824s

Sync Summary
  OK Claude 184/184  +3  ~1  -180  1.192s
  OK Codex 42/42  +2  ~0  -40  632ms

==[ COMBINED / DAY ]==
------------------------------------------------------------------------

[ PER-AGENT BREAKDOWN ]
  Agent          Sessions         Time Tokens (in/out/crea/read)   Messages
  --------------------------------------------------------------------------
  Claude               31        12.2h 1.8M/246.4K/0/0       4434
  Codex                 4         8.3m 1.5M/23.1K/1.3M/0         21
  --------------------------------------------------------------------------
  Total                35        12.3h 3.3M/269.5K/1.3M/0       4455

[ SUMMARY ]
  Total Sessions:      35
  Total Session Time:  12.3h
  Total Tokens:        131.4M (in: 3.3M, out: 269.5K, cache: 1.3M/0)
  Total Messages:      4455
  Unique Projects:     6
  Last Sync:          2026-03-04 18:42:15

[ TOP MODELS | by session count ]
  1. claude-sonnet-4-5 - 24 sessions
  2. gpt-5.2-codex - 4 sessions
  3. claude-opus-4-2 - 3 sessions

[ LAST 5 SESSIONS ]
  1. Mar 04 18:40 Codex | gpt-5.2-codex | atlas-api | 5.8m | 1.4M (cache: 1.3M/0, msgs: 9)
  2. Mar 04 18:29 Codex | gpt-5.2-codex | atlas-api | 42s | 18.7K (cache: 0/0, msgs: 6)
  3. Mar 04 12:54 Claude | claude-sonnet-4-5 | orbit-mobile | 7.4m | 1.5M (cache: 0/0, msgs: 104)
  4. Mar 04 12:08 Claude | claude-sonnet-4-5 | helios-admin | 6.9m | 711.2K (cache: 0/0, msgs: 295)
  5. Mar 04 11:51 Claude | claude-sonnet-4-5 | orbit-mobile | 2.1m | 1.2M (cache: 0/0, msgs: 61)

------------------------------------------------------------------------

Usage Command

Agent Sync NEON MODE
Scanning sessions and updating usage DB...

⠸ Claude   184/184   +1 new  ~0 upd  -183 skip  complete

Sync complete
Elapsed 964ms

Sync Summary
  OK Claude 184/184  +1  ~0  -183  964ms

==[ CLAUDE / DAY ]==
------------------------------------------------------------------------

[ LAST SESSION ]
  ID:         e6f3417c-8a66-458a-9bd0-617f9de72f44
  Start:      2026-03-04 12:54:37
  Project:    /Users/dev/workspace/orbit-mobile
  Model:      claude-sonnet-4-5
  Provider:   anthropic
  End:        2026-03-04 13:02:18
  Duration:   7.7m
  Tokens:     1.5M (in: 31.8K, out: 6.1K, cache: 0/0)
  Messages:   104

[ SUMMARY ]
  Total Sessions:     31
  Total Session Time: 12.2h
  Total Tokens:       127.9M (in: 1.8M, out: 246.4K, cache: 0/0)
  Total Messages:     4434
  Last Sync:         2026-03-04 18:42:18

[ TOP MODELS | by session count ]
  1. claude-sonnet-4-5 - 24 sessions
  2. claude-opus-4-2 - 3 sessions
  3. claude-haiku-4-5 - 2 sessions

------------------------------------------------------------------------

Debug Mode

Use --debug or -d flag to see detailed debug output:

./agent-usage usage codex day --debug

Debug output shows:

• SQL queries being executed
• Raw session data
• Time filters being applied (start/end timestamps)

Database

The tool uses SQLite to store session data:

• Location: ~/.agent-usage/usage.db (or custom path)
• Tables:
  • sessions - Individual agent sessions
  • messages - Messages within sessions
  • tool_calls - Tool calls made during sessions
  • metadata - Key-value store for sync timestamps

How It Works

1. Session Discovery: The tool walks through agent session directories to find JSONL log files
2. Parsing: Each session file is parsed to extract:
   • Session ID, project path, model
   • Start/end timestamps
   • Token usage (input, output, cached)
   • Cost estimation
3. Storage: Parsed sessions are stored in SQLite database
4. Analysis: Stats queries aggregate data by time period

Session File Locations

• Codex: ~/.codex/sessions/*.jsonl
• Claude: ~/.claude/projects/**/*.jsonl

Development

# Run tests
go test ./...

# Build
go build -o agent-usage .

# Run with verbose output
go run . stats -d

License

MIT License