opencode-local

library1.3.11jsnpmunverified

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.

database data devops

npm install opencode-local

github ↗package ↗

INSTALL

IMPORT

SIG · OPENCODE-LOCAL

opencode-local

databasejavascriptv1.3.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createLocal

✓ import { createLocal } from 'opencode-local'

✗ const createLocal = require('opencode-local').createLocal

Package primarily uses ES modules syntax. CommonJS `require` will not work directly for named exports in many environments.

exportProjects

✓ import { exportProjects } from 'opencode-local/export'

✗ import { exportProjects } from 'opencode-local'

This utility is accessed via a subpath import for modularity, not directly from the main package entry.

ProjectRow

✓ import type { ProjectRow } from 'opencode-local'

✗ import { 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.

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()

Debug

Known issues

gotchaThis 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.

affects: >=1.0.0

breakingThis 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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaThe `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'`.

affects: >=1.0.0

Errors

Common errors & fixes

Error: SQLITE_CANTOPEN: unable to open database file

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: spawn opencode ENOENT

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()`.

FetchError: connect ECONNREFUSED 127.0.0.1:4096

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.

Upgrade

Version history

1.3.11latest on npm

Audit

Dependencies

opencoderequiredRequires a local installation of Opencode for its SQLite database file and optionally for the `opencode` binary if custom paths are used.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/anduimagui/opencode-local ↗

packagehttps://www.npmjs.com/package/opencode-local ↗