114 lines
2.5 KiB
Markdown
114 lines
2.5 KiB
Markdown
# claude-stats - Agent Interface Guide
|
|
|
|
CLI for Claude Code usage statistics. Designed for both human and AI agent use.
|
|
|
|
## Quick Start (Agents)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"data": { ... },
|
|
"meta": {
|
|
"sessions_parsed": 2478,
|
|
"files_scanned": 2478,
|
|
"period_days": 30
|
|
}
|
|
}
|
|
```
|
|
|
|
## Error Format
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```bash
|
|
claude-stats --json | jq '.data.tokens.total_billed'
|
|
```
|
|
|
|
### Check cache efficiency
|
|
```bash
|
|
claude-stats efficiency --json | jq '.data.cache_hit_rate'
|
|
```
|
|
|
|
### Daily usage trend
|
|
```bash
|
|
claude-stats daily -n 7 --json | jq '.data[] | {date, tokens}'
|
|
```
|
|
|
|
### Find highest usage project
|
|
```bash
|
|
claude-stats projects --json | jq '.data[0]'
|
|
```
|