{"id":17857,"library":"opencode-local","title":"Opencode Local Data Access","description":"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.","status":"active","version":"1.3.11","language":"javascript","source_language":"en","source_url":"https://github.com/anduimagui/opencode-local","tags":["javascript","opencode","sqlite","database","local","node","local-database","developer-tools"],"install":[{"cmd":"npm install opencode-local","lang":"bash","label":"npm"},{"cmd":"yarn add opencode-local","lang":"bash","label":"yarn"},{"cmd":"pnpm add opencode-local","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Requires a local installation of Opencode for its SQLite database file and optionally for the `opencode` binary if custom paths are used.","package":"opencode","optional":false}],"imports":[{"note":"Package primarily uses ES modules syntax. CommonJS `require` will not work directly for named exports in many environments.","wrong":"const createLocal = require('opencode-local').createLocal","symbol":"createLocal","correct":"import { createLocal } from 'opencode-local'"},{"note":"This utility is accessed via a subpath import for modularity, not directly from the main package entry.","wrong":"import { exportProjects } from 'opencode-local'","symbol":"exportProjects","correct":"import { exportProjects } from 'opencode-local/export'"},{"note":"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.","wrong":"import { ProjectRow } from 'opencode-local'","symbol":"ProjectRow","correct":"import type { ProjectRow } from 'opencode-local'"}],"quickstart":{"code":"import { createLocal } from \"opencode-local\"\n\nasync function run() {\n  const client = createLocal()\n\n  try {\n    const projects = await client.listProjects()\n    // Get IDs of the first 5 projects to list sessions\n    const projectIds = projects.slice(0, 5).map((project) => project.id)\n    const sessions = await client.listSessions(projectIds)\n\n    console.log(\"First project:\", projects[0])\n    console.log(\"First session:\", sessions[0])\n  } catch (error) {\n    console.error(\"Failed to fetch data:\", error)\n  } finally {\n    client.close()\n  }\n}\n\nrun()","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 22.5.0 or newer. Use `nvm` or `volta` to manage Node.js versions if necessary.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always import `exportProjects` using `import { exportProjects } from 'opencode-local/export'`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","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.","error":"Error: SQLITE_CANTOPEN: unable to open database file"},{"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()`.","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()`.","error":"Error: spawn opencode ENOENT"},{"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.","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()`.","error":"FetchError: connect ECONNREFUSED 127.0.0.1:4096"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}