# 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]'
```