Oh My OpenCode Dashboard

If you are developing or running from a cloned repository, use the following commands:

Development Mode

Starts both the API and the UI development server:

bun run dev -- --project /absolute/path/to/your/project

Production Mode

Builds and starts a single server serving both the UI and the API:

bun run build
bun run start -- --project /absolute/path/to/your/project

Network Binding

By default, the server binds to 127.0.0.1. To expose the server to other machines (e.g., from a container), bind to 0.0.0.0. Use this only on trusted networks.

Using environment variables:

OMO_DASHBOARD_HOST=0.0.0.0 bun run start -- --project /absolute/path/to/your/project

Using CLI flags:

bun run start -- --project /absolute/path/to/your/project --host 0.0.0.0

You can run the dashboard without a permanent installation using bunx.

Important: If the dashboard appears empty after an OpenCode SQLite update, you must register your project as a source first using the add command.

1. Register your project

Run this from your project directory to register it as a source:

bunx oh-my-opencode-dashboard@latest add --name "My Project"

Alternatively, specify a custom name or an absolute path:

bunx oh-my-opencode-dashboard@latest add --name "My Project" --project /absolute/path/to/your/project

2. Start the dashboard

Once registered, start the dashboard using:

bunx oh-my-opencode-dashboard@latest

Global Installation

To install it globally via Bun:

bun add -g oh-my-opencode-dashboard
oh-my-opencode-dashboard

When running the dashboard, you can customize its behavior using the following flags:

• --project <path>: The project root used for plan lookup and session filtering. Defaults to the current working directory.
• --host <hostname>: The server bind host. Defaults to 127.0.0.1. Can also be set via the OMO_DASHBOARD_HOST environment variable.
• --port <number>: The server port. Defaults to 51234.

Example of specifying a project path explicitly:

bunx -p oh-my-opencode-dashboard oh-my-opencode-dashboard -- --project /absolute/path/to/your/project

The getPlanProgressFromMarkdown function extracts progress statistics from a Markdown string by counting task list items (e.g., - [ ] or - [x]).

Returns: An object containing:

• total: Total number of task items found.
• completed: Number of items marked as checked ([x] or [X]).
• isComplete: Boolean indicating if all tasks are completed (or if no tasks exist).

import { getPlanProgressFromMarkdown } from './src/ingest/boulder';

const markdown = `- [x] Task 1\n- [ ] Task 2`;
const progress = getPlanProgressFromMarkdown(markdown);
// Returns: { total: 2, completed: 1, isComplete: false }

Use buildDashboardPayload to construct a complete DashboardPayload object representing the current state of the OpenCode session. This function automatically detects whether to use the legacy file-based storage or the modern SQLite backend based on the provided storageBackend option.

If a storageBackend with kind: 'sqlite' is provided, the function attempts to derive data (tasks, time series, token usage, etc.) from the SQLite database. If the backend is missing or not SQLite, it falls back to reading from the file system using the provided storage roots.

import { buildDashboardPayload } from './src/server/dashboard';

const payload = buildDashboardPayload({
  projectRoot: '/path/to/project',
  storage: { /* OpenCodeStorageRoots */ },
  storageBackend: { kind: 'sqlite', sqlitePath: '/path/to/database.sqlite' }
});

The dashboard uses specific directory structures to find OpenCode data. You can determine the storage location using getDataDir or getOpenCodeStorageDir.

By default, the dashboard follows XDG standards:

1. It checks the XDG_DATA_HOME environment variable.
2. If XDG_DATA_HOME is not set, it defaults to ~/.local/share (or the platform equivalent).
3. The OpenCode storage directory is located at [dataDir]/opencode/storage.

You can override the default behavior by providing a custom Env object containing a different XDG_DATA_HOME value.

import { getOpenCodeStorageDir } from 'oh-my-opencode-dashboard/src/ingest/paths';

// Uses default XDG_DATA_HOME or ~/.local/share
const storageDir = getOpenCodeStorageDir();
console.log(`Storage directory: ${storageDir}`);

Use readBoulderState to retrieve the current session and plan metadata from the .sisyphus/boulder.json file located within a project root. If the file does not exist or is invalid, the function returns null.

import { readBoulderState } from './src/ingest/boulder';

const boulderState = readBoulderState('/path/to/project-root');
if (boulderState) {
  console.log(boulderState.plan_name);
  console.log(boulderState.session_ids);
}

OpenCode uses a specific directory structure to separate session metadata, messages, and tool parts. You can define these roots using getStorageRoots(storageRoot: string), which returns an OpenCodeStorageRoots object containing paths for session, message, and part subdirectories.

import { getStorageRoots } from './ingest/session';

const roots = getStorageRoots('/path/to/opencode/data');
// roots.session -> '/path/to/opencode/data/session'
// roots.message -> '/path/to/opencode/data/message'
// roots.part    -> '/path/to/opencode/data/part'