initial commit

AGENTS.md

@@ -0,0 +1,113 @@
+# 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]'
+```