claude-stats/AGENTS.md

claude-stats - Agent Interface Guide

CLI for Claude Code usage statistics. Designed for both human and AI agent use.

Quick Start (Agents)

# JSON output (auto-enabled when piped)
claude-stats --json           # Summary with tokens, costs, efficiency
claude-stats daily --json     # Daily breakdown
claude-stats efficiency --json  # Cache hit rate, cost analysis

Commands

Command	Purpose	Example
(none)	Summary stats	claude-stats --json
daily	Daily breakdown	claude-stats daily -n 7 --json
weekly	Weekly breakdown	claude-stats weekly -n 4 --json
sessions	Recent sessions	claude-stats sessions -n 10 --json
projects	By project	claude-stats projects --json
hourly	By hour	claude-stats hourly --json
models	Model usage	claude-stats models --json
efficiency	Cache/cost metrics	claude-stats efficiency --json
all	Everything	claude-stats all --json

Flags

Flag	Purpose
--json	JSON output (auto when piped)
-n N	Limit/days count
-q	Quiet (no progress)
-d PATH	Custom data dir

JSON Response Format

{
  "ok": true,
  "data": { ... },
  "meta": {
    "sessions_parsed": 2478,
    "files_scanned": 2478,
    "period_days": 30
  }
}

Error Format

{
  "ok": false,
  "error": {
    "code": 2,
    "message": "Unknown command 'daytime'",
    "suggestions": [
      "claude-stats daily -n 7",
      "claude-stats --help"
    ]
  }
}

Exit Codes

Code	Meaning
0	Success
1	No data found
2	Invalid arguments
3	Data directory not found
4	Parse error

Error Tolerance

The CLI is forgiving of minor syntax issues:

What You Type	Interpreted As
daly, dayly	daily
session	sessions
mod, model	models
eff, efficency	efficiency
stats, summary	all
-json, -J	--json
-l, --limit	-n
-n7	-n 7
--days=7	--days 7

Example Workflows

Get token usage for analysis

claude-stats --json | jq '.data.tokens.total_billed'

Check cache efficiency

claude-stats efficiency --json | jq '.data.cache_hit_rate'

Daily usage trend

claude-stats daily -n 7 --json | jq '.data[] | {date, tokens}'

Find highest usage project

claude-stats projects --json | jq '.data[0]'