OpenCode Usage Tracker

Local-first usage analytics for OpenCode. It provides a terminal CLI and a polished local React dashboard backed by the same TypeScript core.

The project reads OpenCode's local SQLite database in read-only mode. Your usage data stays on your machine.

Features

• Explore sessions, projects, providers and models.
• Review daily, weekly and monthly usage, costs and token breakdowns.
• Filter by date, provider, model, project, cost and token count.
• Inspect session details, sort and search the full session list.
• Export any combination of sessions, summaries and breakdowns as CSV, JSON, Markdown or HTML.
• Use the dashboard in English or Spanish, with light and dark themes.

Privacy and limitations

By default, the app reads:

~/.local/share/opencode/opencode.db

It never modifies that database and does not send analytics or usage data to a remote service.

The local OpenCode database does not reliably expose remaining quota or historical API-key identity for each session. The tracker deliberately marks those values as unavailable instead of estimating them.

Requirements

• Node.js 20.19 or newer
• pnpm 10.32.1 (enabled through Corepack if needed)
• An OpenCode installation with its local SQLite database available

Getting started

corepack enable
pnpm install
pnpm build

CLI

pnpm cli -- usage daily
pnpm cli -- usage weekly --provider opencode-go
pnpm cli -- usage sessions --from 2026-06-01 --to 2026-06-30
pnpm cli -- usage inspect <session-id>
pnpm cli -- usage export --format csv
pnpm cli -- usage export --scope sessions,summary,models --format html > usage-report.html

Common filters:

--db <path>
--from <date> --to <date>
--provider <id> --model <id> --project <text> --session <id>
--min-cost <number> --max-cost <number>
--min-tokens <number> --max-tokens <number>
--locale en|es

Export sections are sessions, models, providers, projects, daily, weekly, monthly and summary. Pass a comma-separated list to --scope; the default is sessions. Supported formats are csv, json, md and html.

Override the database location with --db, OPENCODE_DB_PATH or OCT_DB_PATH.

Local dashboard

pnpm web

Open http://127.0.0.1:5173. The browser communicates only with the local Node API under /api/*; SQLite is never exposed to the frontend.

Use the export dialog to select one or several report sections, choose whether current filters apply, and select the output format. The server listens on loopback by default. If you override HOST, protect access yourself because reports can contain session titles and local project paths.

Development and verification

pnpm lint
pnpm format
pnpm typecheck
pnpm test
pnpm build

The full suite currently covers normalization, aggregation, filtering, exports, CLI parsing, SQLite compatibility, and session-list sorting/search.

Architecture

• packages/core: OpenCode source adapter, read-only SQLite access, normalization, filters, aggregations and export.
• packages/i18n: minimal English and Spanish text catalog.
• apps/cli: the oct command-line application.
• apps/web: local Node API and React dashboard.

The core exposes a UsageSource interface so future sources can be added without coupling OpenCode-specific details to the CLI or dashboard.

License

MIT