Opencode Local Data Access

1.3.11 verified Thu Apr 23 auth: no javascript

The `opencode-local` package provides a Node.js interface for programmatic access to local Opencode project data. It allows developers to read information directly from the local Opencode SQLite database, bypassing the need to shell out to `opencode db` for each query. Additionally, it supports querying a running Opencode server for project lists, offering flexibility to retrieve data from either the local database or a live instance. The current stable version is 1.3.11, and while a specific release cadence isn't documented, its versioning suggests ongoing maintenance. A key differentiator is its dual capability to interface with both the local SQLite file and a remote Opencode server's API, along with dedicated utilities for exporting project data to JSON, making it a powerful tool for integrating Opencode project insights into developer workflows or custom tooling. It requires Node.js >=22.5.0 and an existing local Opencode installation.

Common errors

error Error: SQLITE_CANTOPEN: unable to open database file ↓

cause The specified `dbPath` is incorrect, the Opencode database file (`opencode.db`) doesn't exist at that location, or the current user has insufficient permissions to read the file.

fix

Verify the absolute path provided to dbPath in createLocal() and ensure the current user has read permissions for the file. Check if Opencode is installed and has created its database.

error Error: spawn opencode ENOENT ↓

cause The `opencode` binary (CLI tool) cannot be found in the system's PATH or at the custom path provided to the `bin` option in `createLocal()`.

fix

Ensure the opencode CLI is installed and accessible in your system's PATH, or provide the absolute path to the opencode binary using the bin option in createLocal().

error FetchError: connect ECONNREFUSED 127.0.0.1:4096 ↓

cause The Opencode server is not running or is not listening on the specified `baseUrl` and port (default 4096) when attempting to use server-based client methods like `search()` or `listProjectsFromServer()`.

fix

Start your Opencode server. If it's already running, confirm the baseUrl in createLocal().search() options (or similar) is correct and matches the server's listening address and port.

Warnings

gotcha This package requires a local Opencode installation and an accessible database (`opencode.db`). Failure to meet this prerequisite will result in runtime errors when attempting to query local data. ↓

fix Ensure Opencode is installed locally and that the database file exists and is readable. Use the `dbPath` option in `createLocal()` if the database is not in its default location.

breaking This package explicitly requires Node.js version 22.5.0 or higher as defined in its `engines` field. Running with older Node.js versions will lead to immediate runtime errors due to incompatible syntax or API usage. ↓

fix Upgrade your Node.js environment to version 22.5.0 or newer. Use `nvm` or `volta` to manage Node.js versions if necessary.

gotcha When using server-related methods like `search` or `listProjectsFromServer`, a running Opencode server must be accessible. An incorrect `baseUrl` or a down server will lead to network connection errors. ↓

fix Verify that your Opencode server is running and listening on the specified `baseUrl` (default is `http://localhost:4096`). Check firewall rules if connection issues persist.

gotcha The `exportProjects` utility function is accessed via a subpath import (`opencode-local/export`), not directly from the main package entry. Importing it incorrectly will result in module not found errors. ↓

fix Always import `exportProjects` using `import { exportProjects } from 'opencode-local/export'`.

Install

npm install opencode-local

yarn add opencode-local

pnpm add opencode-local

Imports

createLocal
wrong
```
const createLocal = require('opencode-local').createLocal
```
correct
```
import { createLocal } from 'opencode-local'
```
Package primarily uses ES modules syntax. CommonJS `require` will not work directly for named exports in many environments.
exportProjects
wrong
```
import { exportProjects } from 'opencode-local'
```
correct
```
import { exportProjects } from 'opencode-local/export'
```
This utility is accessed via a subpath import for modularity, not directly from the main package entry.
ProjectRow
wrong
```
import { ProjectRow } from 'opencode-local'
```
correct
```
import type { ProjectRow } from 'opencode-local'
```
This is a TypeScript type definition. Using `import type` is recommended to prevent runtime issues and ensure type-only imports are handled correctly by bundlers.

Quickstart

This example demonstrates how to initialize the client, list projects from the local Opencode database, and then fetch sessions for a subset of those projects, logging the first results.

import { createLocal } from "opencode-local"

async function run() {
  const client = createLocal()

  try {
    const projects = await client.listProjects()
    // Get IDs of the first 5 projects to list sessions
    const projectIds = projects.slice(0, 5).map((project) => project.id)
    const sessions = await client.listSessions(projectIds)

    console.log("First project:", projects[0])
    console.log("First session:", sessions[0])
  } catch (error) {
    console.error("Failed to fetch data:", error)
  } finally {
    client.close()
  }
}

run()