# vibestats

AI coding stats CLI for **Claude Code** and **OpenAI Codex**. Track your usage and generate annual "Spotify Wrapped" style summaries.

## Installation

```bash
npm install -g vibestats
# or run directly
npx vibestats
npx vibestats codex
```

## Usage

```bash
# Usage stats (default)
vibestats              # Daily usage table
vibestats claude       # Claude-compatible usage
vibestats codex        # Codex CLI usage
vibestats all          # Combined local sources
vibestats --monthly    # Monthly aggregation
vibestats --model      # Aggregate by model
vibestats --total      # Show only totals
vibestats --claude     # Claude family stats only
vibestats --kimi       # Kimi family stats only
vibestats --minimax    # MiniMax family stats only

# Wrapped summary
vibestats --wrapped    # Annual wrapped summary

# Claude local diagnostics
vibestats --claude-system
vibestats --claude-limits

# Codex local diagnostics
vibestats codex-resets
vibestats codex resets
```

## CLI Flags

### Usage Mode (default)

| Flag | Description |
|------|-------------|
| `--monthly` | Aggregate by month |
| `--model` | Aggregate by model |
| `--sessions` | Aggregate by session |
| `--total` | Show only totals |
| `--claude` | Show only Claude family stats |
| `--kimi` | Show only Kimi family stats |
| `--minimax` | Show only MiniMax family stats |
| `--since YYYY-MM-DD` | Filter from date |
| `--until YYYY-MM-DD` | Filter to date |
| `--last N` | Last N days (shorthand: `--last7`, `--last30`, etc.) |
| `--compact`, `-c` | Compact table (hide cache columns) |
| `--json` | Output raw JSON |
| `--quiet`, `-q` | Quiet output (totals line) |
| `--share`, `-s` | Generate a shareable usage URL |
| `--project`, `-p` | Current project only (Claude Code) |
| `--claude-system` | Inspect `~/.claude.json` account and app state |
| `--claude-limits` | Inspect `~/.claude/usage-data`, cache freshness, and local limit signals |

### Wrapped Mode

| Flag | Description |
|------|-------------|
| `--wrapped` | Generate wrapped summary |
| `--json` | Output raw JSON stats |
| `--quiet`, `-q` | Only output the shareable URL |
| `--no-short` | Disable shortlink generation |

### Data Source

| Command or flag | Description |
|-----------------|-------------|
| `vibestats claude` | Claude-compatible local usage |
| `vibestats codex` | OpenAI Codex only |
| `vibestats all` | All supported local sources combined |
| `--codex` | OpenAI Codex only |
| `--combined` | Claude + Codex combined |
| `vibestats usage codex --total` | Codex total usage table |
| `vibestats limits codex` | Codex local limit windows |
| `vibestats codex-resets` | Codex reset-credit status from the local Codex Desktop session |
| `vibestats codex resets` | Alias for `vibestats codex-resets` |

### Codex Reset-Credit Diagnostics

`vibestats codex-resets` reads `~/.codex/auth.json` from the locally authenticated Codex Desktop session and calls ChatGPT's reset-credit status endpoint with a short timeout. It prints available reset-credit count, status, local grant/expiry times, and title.

This endpoint is unofficial/internal and may change. The command is intended for personal local diagnostics only; it never prints auth tokens, account IDs, or raw authorization headers. Credit IDs are hidden unless `--debug` is explicitly passed.

### Config

| Flag | Description |
|------|-------------|
| `--init` | Create config file |
| `--config` | Show current config |
| `--url <url>` | Custom base URL for shareable links/pages |

## Config File

```bash
vibestats --init
```

Creates `~/.vibestats.json`:

```json
{
  "baseUrl": "https://vibestats.wolfai.dev",
  "outputFormat": "normal",
  "theme": { "enabled": true },
  "hideCost": false
}
```

## Data Sources

| Source | Location |
|--------|----------|
| Claude-compatible | Claude Code, OpenCode, and Factory Droid local usage |
| OpenAI Codex | `~/.codex/sessions/*.jsonl` |

Additional Claude diagnostic files:
- `~/.claude.json`
- `~/.claude/stats-cache.json`
- `~/.claude/usage-data/session-meta/*.json`
- `~/.claude/usage-data/facets/*.json`

## Session Semantics

- `sessions` means canonical top-level sessions
- subagents are counted separately and shown as a compact session mix notice
- token and cost totals still include subagent usage
- Claude subagents are inferred from sidechain/session metadata
- Codex subagents are inferred from spawned-thread metadata

## Requirements

- Node.js 18+
- Claude Code or OpenAI Codex CLI usage data

## View Online

Visit [vibestats.wolfai.dev](https://vibestats.wolfai.dev) to view shares in the browser.

- [vibestats.wolfai.dev/docs](https://vibestats.wolfai.dev/docs)
- [vibestats.wolfai.dev/wrapped](https://vibestats.wolfai.dev/wrapped)
- [vibestats.wolfai.dev/activity](https://vibestats.wolfai.dev/activity)
- [vibestats.wolfai.dev/changelog](https://vibestats.wolfai.dev/changelog)

The hosted web app runs from the VPS deployment defined by `docker-compose.vps.yml` and `packages/web/Dockerfile`, behind Traefik at `vibestats.wolfai.dev`.

## License

MIT