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:

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.