opencode-dash

opencode-dash is a self-hosted hosted dashboard that visualizes your opencode CLI usage analytics. It Visualizes sessions, tokens, costs, models, and agents, from your local SQLite database.

Quick Start

npm install
npx opencode-dash

Opens a local dashboard at http://localhost:3000 showing your sessions, tokens, costs, models, and projects. The CLI auto-detects your OS (macOS, Linux, Windows) and finds your opencode database automatically.

Features

Feature	Description
Session Analytics	Agent type, model, cost, and token usage
Activity Heatmap	Calendar heatmap of daily session activity
Model Distribution	Pie/donut chart of model usage across sessions
Privacy-first	No backend, no account creation needed; everything runs locally

Example Dashboard:

Activity page: sessions over time, duration distribution, longest sessions, active projects

Cost page: input/output/reasoning token breakdown, daily cost trends, model and provider costing

How It Works

• Reads opencode's SQLite database (~/.local/share/opencode/opencode.db on all platforms, or $XDG_DATA_HOME/opencode/opencode.db when set)
• Built on Evidence.dev - lightweight SQL-driven, Svelte-based reporting
• Static site output: npm run build produces a deployable build/ directory
• No backend or account creation needed. So the data stays on your device.

Environment Variables

Variable	Purpose
OPENCODE_DB	Absolute path to the database file (bypasses all auto-detection)
OPENCODE_DATA_DIR	Custom opencode data directory
XDG_DATA_HOME	Override the XDG data home (default: ~/.local/share)

Contribution

Project Structure

opencode-telematics/
├── bin/
│   └── cli.js                 # CLI entry point — detects OS, launches dashboard
├── lib/
│   └── db-path.js             # DB path resolution (xdg-basedir, env overrides)
├── app/
│   ├── pages/                 # Dashboard pages (.md)
│   │   ├── index.md           # Overview
│   │   ├── cost.md            # Token economics
│   │   ├── activity.md        # Usage over time
│   │   ├── agents.md          # Agent distribution
│   │   ├── messages.md        # Message/part analysis
│   │   ├── models.md          # Model usage
│   │   ├── projects.md        # Projects list/costing
│   │   ├── events.md          # Event types
│   │   └── quality.md         # Finish reasons, todos
│   ├── components/            # Reusable Svelte components
│   ├── sources/opencode/      # SQL queries (.sql) + connection config
│   ├── build/                 # Static site output (generated)
│   └── evidence.config.yaml
├── test/
│   ├── db-path.test.js        # Unit tests — DB path resolution
│   └── e2e.test.js            # E2E smoke tests
└── package.json               # Root CLI package

Core Tables

These tables are created and populated automatically by opencode after each session. The CLI extracts from them to build the dashboard.

Table	Key Columns
session	id, project_id, parent_id, agent, model, cost, tokens_input, tokens_output, tokens_reasoning, tokens_cache_read/write, time_created
message	id, session_id, data (role, mode, finish reason), time_created
part	id, message_id, session_id, data (type, text), time_created
project	id, worktree, vcs, name

Other tables: todo, event, event_sequence.

Development Setup

git clone https://github.com/MuhammadOmarMuhdhar/opencode-dash.git
cd opencode-dash
npm install

# Prepare source connection, build, and preview
cp app/sources/opencode/connection.template.yaml app/sources/opencode/connection.yaml
ln -sf ~/.local/share/opencode/opencode.db app/sources/opencode/opencode.db
npm run sources
npm run build
npm run preview

# Or just use the CLI (handles all preparation automatically):
node bin/cli.js

Testing

Command	Scope
node --test test/db-path.test.js	Unit tests — validates DB path resolution across all OS/env scenarios
npm run build	CI — builds static dashboard, catches broken SQL and layout errors
npm run test:e2e	E2E — full npx simulation (pack → install → build → serve → page fetch)

CI runs npm run build on every push and PR. Unit tests can be run locally:

node --test test/db-path.test.js

Local tarball test

rm -rf app/.evidence/ app/build/ app/.sources-manifest.json

# Prepare source connection (normally done by bin/cli.js)
cp app/sources/opencode/connection.template.yaml app/sources/opencode/connection.yaml
ln -sf ~/.local/share/opencode/opencode.db app/sources/opencode/opencode.db

npm run sources
npm run build
rm -f app/.gitignore

# Clean up prepared files
rm -f app/sources/opencode/connection.yaml app/sources/opencode/opencode.db

npm pack
npm install -g ./opencode-dash-1.0.4.tgz
opencode-dash

License

ISC - see LICENSE.