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

github ↗package ↗

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.

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

import { createLocal } from 'opencode-local'

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

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

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.

import type { ProjectRow } from 'opencode-local'

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 footguns

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.

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.

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.

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.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

11 hits · last 30 days

gptbot

ahrefsbot

bytedance

script

Resources

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

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