Oh My OpenCode Dashboard

https://github.com/williamjudge94/oh-my-opencode-dashboard
Admin
A local-only, read-only dashboard for monitoring OpenCode and OhMyOpenCode agent progress, plan...
Tokens:55,783
Snippets:425
Trust Score:7.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Basic CLI usage examples

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-start.md

Demonstrates starting the dashboard server and registering a project as a named source.

```bash
# from a project directory
oh-my-opencode-dashboard --project /path/to/project --port 51234

# register the project as a named source first (SQLite mode)
oh-my-opencode-dashboard add --name "My Project" --project /path/to/project
```

--------------------------------

### Start globally installed dashboard

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Starts the dashboard after a global installation.

```bash
oh-my-opencode-dashboard
```

--------------------------------

### Complete registry flow example

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-sources-registry.md

Demonstrates the full flow: adding a source with a label, adding one without, retrieving by id, getting the default (newest) source, and listing all sources. Comments indicate expected outputs.

```typescript
import { addOrUpdateSource, listSources, getSourceById, getDefaultSourceId } from "./sources-registry"

addOrUpdateSource(storageRoot, { projectRoot: "/a", label: "A" })
const id = addOrUpdateSource(storageRoot, { projectRoot: "/b" }) // label optional
const entry = getSourceById(storageRoot, id) // { id, projectRoot: "/b", createdAt, updatedAt }
const def = getDefaultSourceId(storageRoot) // "/b" entry (newest)
const list = listSources(storageRoot) // [{ id, label?, updatedAt }]
```

--------------------------------

### Start dashboard with bunx

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Starts the dashboard using the latest version via bunx.

```bash
bunx oh-my-opencode-dashboard@latest
```

--------------------------------

### Install dashboard globally with bun add -g

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Installs the dashboard globally using Bun.

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

--------------------------------

### getPublicHost example

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-host.md

Example calls showing that '0.0.0.0' and '::' map to 'localhost', while other hosts are returned unchanged.

```typescript
import { getPublicHost } from "./host"

getPublicHost("0.0.0.0") // "localhost"
getPublicHost("::") // "localhost"
getPublicHost("127.0.0.1") // "127.0.0.1"
getPublicHost("localhost") // "localhost"
```

--------------------------------

### Install dependencies with bun install

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Installs project dependencies from source using the Bun package manager.

```bash
bun install
```

--------------------------------

### Start dashboard with explicit project path

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Specifies a project path explicitly when starting the dashboard.

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

--------------------------------

### Basic Usage Example

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-static-file.md

A simple demonstration of resolving a request path to an absolute file path.

```ts
import { resolveStaticFilePath } from "./static-file"

const file = resolveStaticFilePath("/app/dist", "/assets/index-abc.js")
// "/app/dist/assets/index-abc.js" (or null if missing/non-existent at realpath level)
```

--------------------------------

### Advanced Usage Example — Serving with Content Type

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-static-file.md

An example of integrating the function into a middleware to serve static files with appropriate content types.

```ts
import { resolveStaticFilePath } from "./static-file"

app.use("*", async (c, next) => {
  const path = c.req.path
  if (path.startsWith("/api/")) return await next()
  if (!path.includes(".")) {
    const indexFile = Bun.file(join(distRoot, "index.html"))
    if (await indexFile.exists()) return c.html(await indexFile.text())
    return c.notFound()
  }

  const filePath = resolveStaticFilePath(distRoot, path)
  if (!filePath) return c.notFound()

  const file = Bun.file(filePath)
  if (await file.exists()) {
    const ext = path.split(".").pop() || ""
    return new Response(file, { headers: { "Content-Type": getContentType(ext) } })
  }
  return c.notFound()
})
```

--------------------------------

### Basic example of createApi usage

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-api.md

Shows how to set up a Hono app with createApi, using a dashboard store and storage backend, and serve it with Bun.

```TypeScript
import { Hono } from "hono"
import { createApi } from "./api"
import { createDashboardStore } from "./dashboard"
import { selectStorageBackend, getLegacyStorageRootForBackend } from "../ingest/storage-backend"

const storageBackend = selectStorageBackend()
const store = createDashboardStore({
  projectRoot: "/path/to/project",
  storageRoot: getLegacyStorageRootForBackend(storageBackend),
  storageBackend,
  watch: true,
  pollIntervalMs: 2000,
})

const app = new Hono()
app.route("/api", createApi({
  store,
  storageRoot: getLegacyStorageRootForBackend(storageBackend),
  projectRoot: "/path/to/project",
  storageBackend,
}))

Bun.serve({ fetch: app.fetch, hostname: "127.0.0.1", port: 51234 })
```

--------------------------------

### readBoulderState Usage Example

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-boulder.md

Example demonstrating how to import and use readBoulderState with optional chaining for safe access to state properties.

```ts
import { readBoulderState } from "./boulder"

const boulder = readBoulderState("/home/me/proj") ?? null
const planName = boulder?.plan_name ?? "(no active plan)"
const sessionIds = boulder?.session_ids ?? []
```

--------------------------------

### Build and run production server

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Builds the project and starts a single production server that serves both the UI and API. Requires an absolute path to the project directory.

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

--------------------------------

### resolveServerHost example

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-host.md

Example usage of resolveServerHost and getPublicHost in production wiring. Shows CLI flag wins over env var, both default to '127.0.0.1'. The publicHost is used for the banner, with a note when bound to a different host.

```typescript
import { resolveServerHost, getPublicHost, DEFAULT_HOST } from "./host"

// production wiring in src/server/start.ts:
const host = resolveServerHost({
  cliHost: values.host, // --host flag (string | undefined)
  envHost: process.env.OMO_DASHBOARD_HOST,
})
// explicit CLI flag wins over the env var; both default to "127.0.0.1"

const publicHost = getPublicHost(host)
if (publicHost === host) {
  console.log(`Server running on http://${publicHost}:${port}`)
} else {
  console.log(`Server running on http://${publicHost}:${port} (bound to ${host})`)
}
```

--------------------------------

### Example: unlockAudio and playDing

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ui-sound.md

Example usage of unlockAudio and playDing. Call unlockAudio from a user gesture to satisfy autoplay policies, then play dings if it returns true.

```ts
import { unlockAudio, playDing } from "./sound"

const ok = await unlockAudio() // call from a user gesture
if (ok) {
  await playDing("task")
  await playDing("question")
}
```

--------------------------------

### extractModelString Usage Examples

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-model.md

Examples showing how to extract model strings from top-level keys, nested model objects, and handling unsupported formats.

```ts
import { extractModelString } from "./model"

extractModelString({ providerID: "anthropic", modelID: "claude-opus-4-5" }) // "anthropic/claude-opus-4-5"
extractModelString({ model: { provider_id: "openai", model_id: "gpt-5" } }) // "openai/gpt-5"
extractModelString({ model: "anthropic/claude-opus-4-5" }) // null — nested string form is not a record
```

--------------------------------

### pickLatestModelString Usage Example

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-model.md

Example demonstrating how to retrieve the latest model string from a list of message metadata.

```ts
import { pickLatestModelString } from "./model"

const model = pickLatestModelString(recentMessageMetas)
// e.g. "anthropic/claude-opus-4-5", preferring assistant-role messages
```

--------------------------------

### createDashboardStore with missing paths

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-dashboard.md

Example showing that getSnapshot() never throws for storage problems, returning a complete DashboardPayload with degraded values.

```ts
const store = createDashboardStore({
  projectRoot: "/missing/project",
  storageRoot: "/missing/storage",
  watch: false,
})
const snap = store.getSnapshot()
// planProgress.statusPill === "not started"; mainSession.agent === "unknown"
// snapshot is still a complete DashboardPayload
```

--------------------------------

### CLI error handling examples

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-start.md

Shows expected output and exit codes when providing invalid project paths or empty source names.

```bash
oh-my-opencode-dashboard add --project /does/not/exist
# "Project path does not exist."  (exit code 1)

oh-my-opencode-dashboard add --name "   " --project /path
# "Source name is required."     (exit code 1)
```

--------------------------------

### Run development server with bun run dev

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Starts the development environment, running both the API and UI dev server. Requires an absolute path to the project directory.

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

--------------------------------

### Advanced example with multi-source resolution and error checking

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-api.md

Shows how to use getStoreForSource to resolve stores per source, with validation and caching. Also demonstrates handling ok:false responses from the API.

```TypeScript
import { createApi } from "./api"
import { listSources, getSourceById } from "../ingest/sources-registry"

const storesByRoot = new Map<string, DashboardStore>()

const api = createApi({
  store: primaryStore,
  storageRoot,
  projectRoot,
  storageBackend,
  getStoreForSource: ({ sourceId, projectRoot }) => {
    // Source ids are sha256 hashes of canonical project roots; validate first.
    const source = getSourceById(storageRoot, sourceId)
    if (!source) throw new Error(`unknown source ${sourceId}`)
    const existing = storesByRoot.get(source.projectRoot)
    if (existing) return existing
    const created = createDashboardStore({
      projectRoot: source.projectRoot,
      storageRoot,
      storageBackend,
      watch: true,
      pollIntervalMs: 2000,
    })
    storesByRoot.set(source.projectRoot, created)
    return created
  },
})

// The API returns ok:false bodies rather than throwing — handle them at the client:
const res = await fetch("http://127.0.0.1:51234/api/dashboard?sourceId=nope")
const body = await res.json() // { ok: false, sourceId: "nope" } with HTTP 400
const dashboard = body.ok ? body : await fetch("/api/dashboard").then((r) => r.json())
```

--------------------------------

### Expose server with OMO_DASHBOARD_HOST=0.0.0.0

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Exposes the server on all interfaces, for example from a container. Use only on trusted networks.

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

--------------------------------

### Basic deriveToolCalls Usage

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-tool-calls.md

A standard implementation example showing how to initialize storage roots and invoke the tool call derivation for a specific session.

```ts
import { deriveToolCalls, MAX_TOOL_CALL_MESSAGES, MAX_TOOL_CALLS } from "./tool-calls"
import { getStorageRoots } from "./session"

const { toolCalls, truncated } = deriveToolCalls({
  storage: getStorageRoots("/home/me/.local/share/opencode/storage"),
  sessionId: "abc123",
  allowedRoots: ["/home/me/.local/share/opencode/storage"],
})
console.log(toolCalls[0]?.tool, toolCalls[0]?.status, { MAX_TOOL_CALL_MESSAGES, MAX_TOOL_CALLS }, truncated)
```

--------------------------------

### aggregateTokenUsage example

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-token-usage.md

Shows how to call aggregateTokenUsage with sample metas. User rows are ignored. Outputs the model and total.

```TypeScript
import { aggregateTokenUsage, EMPTY_TOKEN_USAGE_PAYLOAD } from "./token-usage-core"

const payload = aggregateTokenUsage([
  { id: "m1", role: "assistant", model: { providerID: "anthropic", modelID: "claude-opus-4-5" }, tokens: { input: 100, output: 50 } },
  { id: "m2", role: "user", tokens: { input: 999 } }, // ignored: not assistant
])
console.log(payload.rows[0].model, payload.totals.total) // "anthropic/claude-opus-4-5", 150
```

--------------------------------

### Basic deriveToolCallsSqlite usage

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-sqlite-derive.md

A basic example demonstrating how to call deriveToolCallsSqlite and handle the resulting success or failure.

```ts
import { deriveToolCallsSqlite } from "./sqlite-derive"

const result = deriveToolCallsSqlite({ sqlitePath, sessionId })
if (result.ok) {
  console.log(result.value.toolCalls, result.value.truncated, result.value.sessionExists)
} else {
  console.error("sqlite failure:", result.reason)
}
```

--------------------------------

### deriveTokenUsage example

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-token-usage.md

Shows how to call deriveTokenUsage with storage and session IDs. Logs total and row count.

```TypeScript
import { deriveTokenUsage } from "./token-usage"

const usage = deriveTokenUsage({
  storage,
  mainSessionId: sessionId,
  backgroundSessionIds: tasks.map((t) => t.sessionId),
})
console.log(usage.totals.total, usage.rows.length)
```

--------------------------------

### Basic example of deriveBackgroundTasks

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-background-tasks.md

Shows how to call deriveBackgroundTasks with storage and mainSessionId, then iterate over the returned tasks to log description, status, sessionId, and toolCalls.

```typescript
import { deriveBackgroundTasks } from "./background-tasks"

const tasks = deriveBackgroundTasks({
  storage,
  mainSessionId: sessionId,
})
for (const t of tasks) {
  console.log(t.description, t.status, t.sessionId, t.toolCalls)
}
```

--------------------------------

### assertAllowedPath Basic Usage

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-paths.md

Example of validating a path against an allowed root.

```ts
import { assertAllowedPath } from "./paths"

const planReal = assertAllowedPath({
  candidatePath: "/home/me/proj/.sisyphus/plans/plan.md",
  allowedRoots: ["/home/me/proj"],
})
```

--------------------------------

### GET /sources

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-api.md

Lists available sources. Returns a JSON response with ok status and a list of sources.

```APIDOC
## GET /sources

### Description
Lists available sources from the storage root.

### Method
GET

### Endpoint
/sources

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **sources** (array) - List of source objects.

#### Response Example
{
  "ok": true,
  "sources": []
}
```

--------------------------------

### Full Plan Flow with Error Degradation

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-boulder.md

Example showing how to chain boulder state reading with plan progress and step retrieval, handling missing states gracefully.

```ts
import { readBoulderState, readPlanProgress, readPlanSteps } from "./boulder"

const boulder = readBoulderState(projectRoot)
const plan = boulder
  ? readPlanProgress(projectRoot, boulder.active_plan)
  : { total: 0, completed: 0, isComplete: false, missing: true }
const steps = boulder ? readPlanSteps(projectRoot, boulder.active_plan) : { missing: true, steps: [] }

// Consumers (dashboard.ts) map this to UI fields directly:
// statusPill: missing ? "not started" : isComplete ? "complete" : "in progress"
```

--------------------------------

### Error Handling and Traversal Prevention

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-static-file.md

Examples showing how the function handles path traversal attempts and missing files by returning null.

```ts
resolveStaticFilePath("/app/dist", "/../../etc/passwd") // null (has "..")
resolveStaticFilePath("/app/dist", "/%2e%2e/%2e%2e/etc/passwd") // null (decoded to "..")
resolveStaticFilePath("/app/dist", "/favicon.ico") // null if file missing; note missing files resolve at realpath level only when parents exist
```

--------------------------------

### Advanced example — background vs sync classification

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-background-tasks.md

Demonstrates filtering tasks by status to identify running and queued tasks, with comments explaining the status semantics.

```typescript
import { deriveBackgroundTasks } from "./background-tasks"

const tasks = deriveBackgroundTasks({ storage, mainSessionId: sessionId, nowMs: Date.now() })
const running = tasks.filter((t) => t.status === "running")
const queued = tasks.filter((t) => t.status === "queued") // no linked session yet
// A task is "queued" exactly when no background session id could be resolved,
// "completed" when its session has tool activity older than 15 s.
```

--------------------------------

### Advanced full payload assembly with fallback

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-sqlite-derive.md

An advanced example showing how to pick an active session ID and derive time series activity and token usage with fallback logic.

```ts
import { pickActiveSessionIdSqlite, deriveTimeSeriesActivitySqlite, deriveTokenUsageSqlite } from "./sqlite-derive"
import { hasLegacyFallback } from "./dashboard" // pattern used in buildDashboardPayload

const active = pickActiveSessionIdSqlite({ sqlitePath, projectRoot, boulderSessionIds })
if (!active.ok && hasLegacyStorageRoots(storage)) {
  // fall back to files
}
const ts = deriveTimeSeriesActivitySqlite({ sqlitePath, mainSessionId: active.ok ? active.value : null })
const usage = deriveTokenUsageSqlite({ sqlitePath, mainSessionId, backgroundSessionIds })
```

--------------------------------

### Basic createDashboardStore usage

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-dashboard.md

Creates a dashboard store using the selected storage backend and legacy storage root, then retrieves a snapshot and logs the main session status pill.

```ts
import { createDashboardStore } from "./dashboard"
import { selectStorageBackend, getLegacyStorageRootForBackend } from "../ingest/storage-backend"

const backend = selectStorageBackend()
const store = createDashboardStore({
  projectRoot: process.cwd(),
  storageRoot: getLegacyStorageRootForBackend(backend),
  storageBackend: backend,
})

const snapshot = store.getSnapshot()
console.log(snapshot.mainSession.statusPill) // "running tool" | "thinking" | "busy" | "idle" | "unknown"
```

--------------------------------

### Basic example of computeStackedSegments

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ui-timeseries-stacked.md

Basic usage example. Computes stacked segments for counts with non-zero agents, producing segments for teal, red, and green tones.

```typescript
import { computeStackedSegments } from "./timeseries-stacked"

const segments = computeStackedSegments(
  { sisyphus: 4, prometheus: 1, atlas: 2, other: 0 },
  8,   // scaleMax
  28   // chartHeight
)
// segments: [{ tone: "teal", y, height }, { tone: "red", y, height }, { tone: "green", y, height }]
```

--------------------------------

### Example: computeWaitingDing in polling loop

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ui-sound.md

Example wiring computeWaitingDing into a polling loop (as in App.tsx). The waiting variable is a placeholder for the actual condition (idle && noTool && hasSession). The interval runs every 2200 ms.

```ts
import { computeWaitingDing } from "./ding-policy"

let state = { prevWaiting: null, lastLeftWaitingAtMs: null }
setInterval(() => {
  const waiting = idle && noTool && hasSession
  const decision = computeWaitingDing({ prev: state, waiting, nowMs: Date.now() })
  state = decision.next
  if (decision.play) void playDing("waiting")
}, 2200)
```

--------------------------------

### Register project source with bunx add

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Registers the current project as a source so the dashboard can display data after the OpenCode SQLite update. Run from the project directory.

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

--------------------------------

### GET /api/health

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/endpoints.md

Liveness probe endpoint that returns a simple OK status.

```APIDOC
## GET /api/health

### Description
Liveness probe for the dashboard server.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **ok** (boolean) - Always `true`

#### Response Example
```json
{ "ok": true }
```
```

--------------------------------

### GET /health

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-api.md

Health check endpoint that returns a JSON response with ok status.

```APIDOC
## GET /health

### Description
Health check endpoint for the dashboard API.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **ok** (boolean) - Always true for health check.

#### Response Example
{
  "ok": true
}
```

--------------------------------

### Standalone Helper Usage

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ui-app.md

Demonstrates how to use computeToolCallsFetchPlan to determine fetch requirements and buildDashboardUrl to generate API endpoints.

```tsx
import { computeToolCallsFetchPlan, buildDashboardUrl } from "./App"

const plan = computeToolCallsFetchPlan({
  sessionId: "abc",
  status: "running",
  cachedState: "ok",
  cachedDataOk: true,
  isExpanded: true,
}) // { shouldFetch: true, force: true } — refresh live-running task data

const url = buildDashboardUrl("src-1") // "/api/dashboard?sourceId=src-1"
```

--------------------------------

### Expose server via CLI --host 0.0.0.0

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Alternative CLI method to expose the server on all interfaces using the --host flag. Use only on trusted networks.

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

--------------------------------

### GET /api/sources

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/endpoints.md

Lists all registered dashboard sources, including their IDs, labels, and update timestamps.

```APIDOC
## GET /api/sources

### Description
Lists registered dashboard sources from the sources registry.

### Method
GET

### Endpoint
/api/sources

### Response
#### Success Response (200)
- **ok** (boolean) - Always `true`
- **sources** (Array<{ id, label?, updatedAt }>) - `listSources` output; sorted by `updatedAt` desc; `label` is optional
- **defaultSourceId** (string | null) - Most recently updated source id, or `null` when none registered

#### Response Example
```json
{
  "ok": true,
  "sources": [{ "id": "sha256-hex", "label": "My Project", "updatedAt": 1726000000000 }],
  "defaultSourceId": "sha256-hex"
}
```
```

--------------------------------

### Select and read storage backend

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-storage-backend.md

Demonstrates selecting a storage backend and conditionally reading session metadata based on whether the backend is SQLite or legacy mode.

```ts
import { selectStorageBackend, getLegacyStorageRootForBackend, getOpenCodeSqlitePath } from "./storage-backend"

const backend = selectStorageBackend()
const storageRoot = getLegacyStorageRootForBackend(backend)

if (backend.kind === "sqlite") {
  const metas = readMainSessionMetasSqlite({
    sqlitePath: backend.sqlitePath,
    directoryFilter: projectRoot,
  })
  if (metas.ok) {
    console.log("root sessions:", metas.rows.length)
  } else {
    console.error("sqlite read failed:", metas.reason) // "db_busy" | "db_corrupt" | ...
  }
} else {
  console.log("legacy files mode, storageRoot:", backend.storageRoot)
}
```

--------------------------------

### assertAllowedPath Symlink Rejection

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-paths.md

Example demonstrating that paths resolving outside the allowed root via symlinks are rejected.

```ts
try {
  const evil = assertAllowedPath({
    candidatePath: "/tmp/proj/link-to-outside/secret.md", // symlink → /etc
    allowedRoots: ["/tmp/proj"],
  })
} catch (error) {
  // Error: "Access denied" — realpath resolution escapes the allowed root
}
```

--------------------------------

### Basic usage: buildDashboardPayload with default storage

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-dashboard.md

Imports buildDashboardPayload and storage helpers, then builds a payload for a project root using defaultStorageRoots() or getStorageRoots(). Logs the number of background tasks and time series points.

```TypeScript
import { buildDashboardPayload } from "./dashboard"
import { getStorageRoots, defaultStorageRoots } from "../ingest/session"

const payload = buildDashboardPayload({
  projectRoot: "/path/to/project",
  storage: defaultStorageRoots(), // or getStorageRoots("/path/to/storage")
  nowMs: Date.now(),
})
console.log(payload.backgroundTasks.length, payload.timeSeries.series.length)
```

--------------------------------

### GET /api/health Response

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/endpoints.md

The liveness probe endpoint returns a simple JSON object indicating the server is operational.

```json
{ "ok": true }
```

--------------------------------

### Bind to localhost with OMO_DASHBOARD_HOST

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/README.md

Binds the server to localhost only, keeping it local-only. Requires an absolute path to the project directory.

```bash
OMO_DASHBOARD_HOST=localhost bun run start -- --project /absolute/path/to/your/project
```

--------------------------------

### GET /dashboard

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/server-api.md

Returns the dashboard data for the primary project or a specified source via the sourceId query parameter.

```APIDOC
## GET /dashboard

### Description
Returns the dashboard data for the primary project or a specified source via the sourceId query parameter.

### Method
GET

### Endpoint
/dashboard

### Parameters
#### Query Parameters
- **sourceId** (string) - Optional - The source identifier to fetch dashboard data for. When absent, the primary store is used.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **dashboard** (object) - The dashboard data.

#### Error Response (400)
- **ok** (boolean) - false.
- **sourceId** (string) - The invalid source identifier.

#### Response Example (Success)
{
  "ok": true,
  "dashboard": {}
}

#### Response Example (Error)
{
  "ok": false,
  "sourceId": "nope"
}
```

--------------------------------

### GET /api/sources Response

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/endpoints.md

Returns a list of registered dashboard sources from the sources.json file, including the default source ID.

```json
{
  "ok": true,
  "sources": [{ "id": "sha256-hex", "label": "My Project", "updatedAt": 1726000000000 }],
  "defaultSourceId": "sha256-hex"
}
```

--------------------------------

### readPlanSteps(projectRoot: string, planPath: string): { missing: boolean; steps: PlanStep[] }

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-boulder.md

Reads the plan markdown file and returns the parsed steps. Returns a missing state with empty steps on path denial, missing file, or read/parse failure.

```APIDOC
## readPlanSteps(projectRoot: string, planPath: string): { missing: boolean; steps: PlanStep[] }

### Description
Reads the plan markdown file and returns the parsed steps. Returns a missing state with empty steps on path denial, missing file, or read/parse failure.

### Signature
```ts
export function readPlanSteps(projectRoot: string, planPath: string): { missing: boolean; steps: PlanStep[] }
```

### Parameters
- **projectRoot** (string) - Required - Allowed root (assertAllowedPath); on failure returns the missing state
- **planPath** (string) - Required - Path from boulder.active_plan (relative to cwd via assertAllowedPath)

### Returns
- **{ missing: boolean; steps: PlanStep[] }** - An object with missing flag and steps array (empty when missing).
```

--------------------------------

### GET /api/dashboard Response

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/endpoints.md

Returns the full dashboard payload for a project, including session details, plan progress, and time series data.

```json
{
  "mainSession": {
    "agent": "sisyphus",
    "currentModel": "anthropic/claude-opus-4-5",
    "currentTool": "bash",
    "lastUpdatedLabel": "2026-01-01T00:00:00.000Z",
    "session": "Session title",
    "sessionId": "abc123",
    "statusPill": "running tool"
  },
  "planProgress": {
    "name": "(no active plan)", "completed": 4, "total": 7, "path": "",
    "statusPill": "in progress", "steps": [{ "checked": true, "text": "step" }]
  },
  "backgroundTasks": [ /* BackgroundTaskRow-shaped objects */ ],
  "mainSessionTasks": [ /* one "main-session" row, or [] */ ],
  "timeSeries": { "windowMs": 300000, "bucketMs": 2000, "buckets": 150, "anchorMs": 0, "serverNowMs": 0, "series": [ /* 5 series */ ] },
  "tokenUsage": { "rows": [], "totals": { "input": 0, "output": 0, "reasoning": 0, "cacheRead": 0, "cacheWrite": 0, "total": 0 } },
  "todos": [],
  "raw": { "mainSession": { }, "planProgress": { }, "backgroundTasks": [], "mainSessionTasks": [], "timeSeries": { } }
}
```

--------------------------------

### selectStorageBackend

Source: https://github.com/williamjudge94/oh-my-opencode-dashboard/blob/main/_autodocs/api-reference/ingest-storage-backend.md

Selects the storage backend based on environment, home directory, or explicit data directory. Returns a SQLite backend when usable, otherwise a files backend.

```APIDOC
## selectStorageBackend

### Description
Selects the storage backend based on environment, home directory, or explicit data directory. Returns a SQLite backend when usable, otherwise a files backend.

### Method
Function

### Signature
```ts
export function selectStorageBackend(opts?: {
  env?: Env
  homedir?: string
  dataDir?: string
}): StorageBackend
```

### Parameters
- **opts.env** (`Env`) - Optional - Forwarded to `getDataDir`
- **opts.homedir** (`string`) - Optional - Forwarded to `getDataDir`
- **opts.dataDir** (`string`) - Optional - Overrides the data dir detection

### Returns
- `{ kind: "sqlite", dataDir, sqlitePath: getOpenCodeSqlitePath(dataDir) }` when usable
- `{ kind: "files", dataDir, storageRoot: getOpenCodeStorageDirFromDataDir(dataDir) }` otherwise
```
Tokens:
Raw