opencode-local

opencode-local

Read local Opencode project data directly from Node.js without shelling out to opencode db for every query. It can also read project.list() directly from a running Opencode server.

Requirements

• Node.js >=22.5.0
• A local Opencode installation with an accessible database

Install

npm install opencode-local

Usage

import { createLocal } from "opencode-local"

const client = createLocal()

const projects = await client.listProjects()
const sessions = await client.listSessions(projects.slice(0, 5).map((project) => project.id))

console.log(projects[0])
console.log(sessions[0])

client.close()

Use a custom database path or CLI binary when needed:

import { createLocal } from "opencode-local"

const client = createLocal({
  dbPath: "/absolute/path/to/opencode.db",
  bin: "/absolute/path/to/opencode",
})

Read projects from the running server instead of the SQLite database when needed:

import { createLocal } from "opencode-local"

const client = createLocal()

const projects = await client.search({
  baseUrl: "http://localhost:4096",
  directory: "/absolute/path/to/project",
})

Export the merged project list to JSON when needed:

import { exportProjects } from "opencode-local/export"

const file = await exportProjects({
  outputPath: "/absolute/path/to/projects.json",
})

console.log(file)

When a project worktree is a git repository with a GitHub remote, the exported row also includes a url field for that repository.

API

createLocal(options?)

type CreateLocalOptions = {
  dbPath?: string
  bin?: string
}

Returns a client with these methods:

• path()
• close()
• search(options?)
• listProjectsFromServer(options?)
• listProjects()
• listVisibleProjects()
• listSessionOnlyProjects()
• listProjectSessions(projectIds)
• listSessions(projectIds)
• fetchProjectIcons(projectIds)
• saveProjectIcon(worktree, icon)

Additional export helper:

• exportProjects(options?)

type SearchOptions = {
  baseUrl?: string
  directory?: string
  workspace?: string
  headers?: Record<string, string>
  type?: "projects"
}

type ProjectRow = {
  id: string
  worktree: string
  name?: string | null
  worktree_name?: string | null
  latest_session_title?: string | null
  icon_color?: string | null
  startup_command?: string | null
  time_updated?: number | null
  sandbox_count?: number | null
  has_icon?: number | null
}

type VisibleProjectRow = ProjectRow & {
  kind: "project" | "session_only"
}

type ServerProject = {
  id: string
  worktree: string
  vcs?: "git"
  name?: string
  icon?: {
    url?: string
    override?: string
    color?: string
  }
  commands?: {
    start?: string
  }
  time: {
    created: number
    updated: number
    initialized?: number
  }
  sandboxes: string[]
}

type SessionDirectoryRow = {
  id: string
  directory: string
  latest_session_title?: string | null
  time_updated?: number | null
}

type ProjectSessionRow = {
  id: string
  project_id: string
  title?: string | null
  updated_at?: number | null
  waiting?: number | null
}

type SessionRow = {
  id: string
  directory: string
  title?: string | null
  updated_at?: number | null
  waiting?: number | null
}

type ExportProjectsOptions = {
  dbPath?: string
  bin?: string
  outputPath?: string
}

type ExportProjectRow = ProjectRow & {
  url?: string
}

Method return values:

• path(): Promise<string>
• close(): void
• search(options?): Promise<ServerProject[]>
• listProjectsFromServer(options?): Promise<ServerProject[]>
• listProjects(): Promise<ProjectRow[]>
• listVisibleProjects(): Promise<VisibleProjectRow[]>
• listSessionOnlyProjects(): Promise<SessionDirectoryRow[]>
• listProjectSessions(projectIds): Promise<ProjectSessionRow[]>
• listSessions(projectIds): Promise<SessionRow[]>
• fetchProjectIcons(projectIds): Promise<Map<string, string>>
• saveProjectIcon(worktree, icon): Promise<void>
• exportProjects(options?): Promise<string>

listProjects() returns one merged list:

• desktop-opened projects from the persisted app cache first
• database-backed projects from opencode.db
• session-only directories that have no project row yet

Merged visible rows now also:

• prefer saved workspace names before Desktop-synced names
• fall back to humanized folder names like House Apartment Kassandras
• pull Desktop-synced icon color, startup command, timestamp, and sandbox counts when the database row is incomplete

Use listVisibleProjects() when you also want the per-row kind (project or session_only).

Search helpers are also exported for downstream palettes and filters:

• getProjectDisplayName(project)
• getProjectSearchAliases(project)
• getProjectSearchText(project)
• matchesProjectQuery(project, query)

These helpers search across project name, workspace/display name, worktree path, latest session title, and path-derived aliases while normalizing spaces, hyphens, and underscores.

The search helpers live with the search API exports so matching code stays separate from project-loading code.

Database Resolution

By default the client resolves the database path like this:

• options.dbPath, when provided
• opencode db path, when options.bin is provided
• OPENCODE_DB, when set
• the default Opencode application support directory for the current platform

Relevant environment variables:

• OPENCODE_DB
• OPENCODE_CHANNEL
• OPENCODE_DISABLE_CHANNEL_DB
• XDG_DATA_HOME

Supported Platforms

• macOS
• Linux

The fallback path logic currently targets those platforms. Windows is not implemented in the path helper.

Development

bun install
bun run typecheck
bun run build
bun run test

Git hooks are installed automatically via Husky on bun install.

• pre-commit runs typecheck, test, and requires a staged CHANGELOG.md update or .changeset/*.md entry when staged changes touch src/, package.json, or tsconfig.json.
• pre-push runs the same publish-readiness checks used by prepublishOnly.

Release

bun run changeset
bun run version-packages
bun run release

version-packages applies pending changesets, updates package.json, and regenerates CHANGELOG.md.

release runs the full publish verification and then publishes through Changesets. If npm two-factor auth is enabled, npm will still prompt for the OTP during publish.

GitHub Actions can also publish directly to npm when you push a v* tag that matches package.json. The workflow in .github/workflows/publish.yml:

• installs dependencies with Bun
• runs the same check:publish verification as local release
• publishes with npm publish --provenance --access public

The separate workflow in .github/workflows/release.yml creates the GitHub release for the same tag.

For the GitHub workflow to publish to npm, configure npm Trusted Publishing for this repository so GitHub Actions can mint the npm publish token via OIDC.

Changelog

Release notes live in CHANGELOG.md.