npm package: @niebaopeng/ocusage
Description: Usage analysis tool for OpenCode / Kimi CLI sessions
Latest version: 1.0.6

# ocusage

Usage analysis tool for **Kimi CLI** and **OpenCode** sessions. Inspired by [ccusage](https://github.com/ryoppippi/ccusage).

`ocusage` reads your local session data, aggregates token usage, and estimates costs — all locally, with zero data leaving your machine.

## Supported Data Sources

- **Kimi CLI**: `~/.kimi/sessions/<md5(cwd)>/<uuid>/wire.jsonl`
- **OpenCode**: `~/.local/share/opencode/opencode.db` (SQLite)

## Features

- 📊 **Multiple Reports** — daily, monthly, session, and project-level breakdowns (day × CLI × model)
- 💰 **Cost Estimation** — built-in pricing for Kimi, DeepSeek, MiniMax, GLM, etc.
- 🌐 **External Pricing** — fetch live prices from **OpenRouter API** or **LiteLLM** local cache
- 📍 **Project Mapping** — automatically resolves session directory hashes to actual project paths
- 🖥️ **Statusline Integration** — compact one-line output for shell prompts
- 🔒 **100% Local** — no network calls, no data upload
- 📦 **Zero Runtime Dependencies** — single-file executable (~17 KB)

## Installation

```bash
# Run directly without installing
npx ocusage

# Or install globally
npm install -g ocusage
```

## Usage

```bash
# Daily report (default)
ocusage daily

# Monthly report
ocusage monthly

# Per-session breakdown
ocusage session

# Per-project breakdown
ocusage project

# Compact one-line summary (great for shell prompts)
ocusage statusline
```

### Options

| Option | Description |
|--------|-------------|
| `--json` | Output raw JSON |
| `--since <YYYY-MM-DD>` | Filter start date |
| `--until <YYYY-MM-DD>` | Filter end date |
| `--project <name>` | Filter by project path substring |
| `--compact` | Use compact table mode |

### Examples

```bash
ocusage daily --since 2026-01-01 --json
ocusage session --project myapp --compact
ocusage monthly --project ocusage
```

## Configuration

Create `~/.ocusage.json` to customize pricing source or override specific model prices:

```json
{
  "pricingProvider": "openrouter",
  "litellmPath": "~/.venv/lib/python3.12/site-packages/litellm/model_prices_and_context_window_backup.json"
}
```

### Pricing Providers

| Provider | Description |
|----------|-------------|
| `"openrouter"` | Fetch live prices from `openrouter.ai/api/v1/models` (default) |
| `"litellm"` | Read from local LiteLLM pricing JSON (auto-detected) |
| `"default"` | Use built-in hardcoded prices (zero network) |

### Pricing Priority
1. `~/.ocusage.json` `pricing` field (user manual override)
2. External provider (`openrouter` or `litellm`)
3. Built-in `DEFAULT_PRICING`
4. Special rules (e.g., MiniMax highspeed = 3× standard)

### Custom Model Prices

```json
{
  "pricing": {
    "kimi-k2.5": {
      "input": 0.50,
      "output": 2.00,
      "cacheRead": 0.10,
      "cacheCreation": 0.50
    }
  }
}
```

## How It Works

### Kimi CLI
1. Scans `~/.kimi/sessions/<md5(cwd)>/<conversation>/wire.jsonl`
2. Extracts `StatusUpdate` events containing `token_usage`
3. Default model is `k2.5` when not explicitly recorded

### OpenCode
1. Reads `~/.local/share/opencode/opencode.db` via built-in `node:sqlite`
2. Queries `message` table for assistant responses with token data
3. Maps sessions to projects via `session` and `project` tables

## License

MIT