opencode-usage

CLI tool to view LLM usage statistics and costs for OpenCode sessions.

Requirements

• Node.js >= 18
• OpenCode reachable:
  • set OPENCODE_URL to an existing OpenCode server, or
  • let opencode-usage attempt to start a temporary local server automatically

Installation

From npm (if published)

npm install -g opencode-usage

From source (this repo)

bun install
bun run build
npm install -g .

Quick start

opencode-usage --help
opencode-usage --all
opencode-usage --today --byModel

Usage

View usage (default command)

# All-time aggregate (default when no filter flags are passed)
opencode-usage

# Aggregate across all tracked sessions
opencode-usage --all

# View a single session
opencode-usage --session <session-id>

# Date filters
opencode-usage --today
opencode-usage --week
opencode-usage --month
opencode-usage --from 2025-01-01
opencode-usage --from 2025-01-01 --to 2025-01-10

# Group aggregate by model
opencode-usage --all --byModel

Live updates

Refreshes the aggregate view periodically.

opencode-usage --all --live
opencode-usage --today --live
opencode-usage --today --live --interval 5

Sync historical data

opencode-usage automatically syncs before showing results.

If you want to run sync explicitly:

opencode-usage sync
opencode-usage sync --force

Notes:

• Without --force, already-tracked sessions are generally skipped (except very recent sessions).
• With --force, all sessions are re-analyzed and overwritten in local storage.

Clear data

# Prune sessions before a date
opencode-usage clear --before 2025-01-01

# Delete ALL usage data (requires explicit confirmation)
opencode-usage clear --confirm

CLI reference

opencode-usage [options]
opencode-usage sync [options]
opencode-usage clear [options]

Global options

• --help, -h: Show help

Options (view usage)

• --session <id>: View a specific session
• --all: Aggregate across all sessions
• --today: Filter to today
• --week: Filter to this week
• --month: Filter to this month
• --from <YYYY-MM-DD>: Start date
• --to <YYYY-MM-DD>: End date
• --byModel: Group results by model
• --live: Live refresh mode
• --interval <sec>: Refresh interval in seconds (default: 2)

Options (sync)

• --force: Re-sync all sessions, overwriting existing local data

Options (clear)

• --before <YYYY-MM-DD>: Only clear data before this date
• --confirm: Confirm full deletion (required when clearing everything)

Configuration

Environment variables

• OPENCODE_URL: OpenCode server URL. If set, the CLI will use it.
• NO_COLOR: Disable ANSI colors in output.

Data storage

• Usage data:

  • ~/.local/share/opencode-usage/usage-data.json
  • Auto-backup: ~/.local/share/opencode-usage/usage-data.backup.json

• Pricing cache (used for model cost calculations):

  • ~/.cache/opencode-usage/pricing-cache.json (fetched from https://models.dev/api.json, cached for ~7 days)

Troubleshooting

“Could not connect to OpenCode server” / “fetch failed”

• If you run OpenCode yourself, make sure it’s running and reachable.
• If you have a non-default server URL, set it:

export OPENCODE_URL="http://localhost:4096"

• If you rely on the auto-started server, ensure your OpenCode environment is installed correctly (or set OPENCODE_URL explicitly).

Development

bun install

# Run CLI directly
bun run dev -- --help
bun run dev -- --all

# Build (bundles to dist/)
bun run build
node dist/cli.js --help

# Typecheck
bunx tsc --noEmit

License

MIT