Skip to main content

OpenCode quick start with CodeGraph

Connect OpenCode to CodeGraph, select the project and run supported analysis commands. Check authentication, graph readiness and output limits.

User Guides

The repository launcher configures the CodeGraph MCP server, LSP server, and opencode-codegraph plugin for the current checkout. This guide helps you open an OpenCode session and verify that its answer uses the intended project and current context.

Prerequisites

Run these PowerShell commands from the CodeGraph source root with its Python dependencies. Install Node.js/npm and OpenCode, and configure access to the selected model. Import your project and verify CPG freshness first. Replace PROJECT with the registered project name, the --db path with its CPG path, PROVIDER/MODEL with an available model, SYMBOL with a project symbol, and SESSION_ID with the intended OpenCode session.

Without --db, the launcher uses data/projects/codegraph.duckdb; --project alone does not replace that path. A missing file can trigger a rebuild for the resolved registered project. The launcher prepares opencode.json, installs the package and starts the API when needed. An interactive run keeps the prepared configuration for subsequent sessions. After the headless OpenCode run finishes, the launcher restores the original opencode.json. Inspect arguments without starting services:

python scripts/run_opencode_codegraph.py --help

Start an interactive session

python scripts/run_opencode_codegraph.py --project 'PROJECT' --db 'data/projects/PROJECT.duckdb'

The current launcher default is openai/gpt-5.4. To use another model available in your OpenCode environment, pass its identifier with --model. CODEGRAPH_OPENCODE_MODEL sets the default model; --model selects it for an individual run:

python scripts/run_opencode_codegraph.py --project 'PROJECT' --db 'data/projects/PROJECT.duckdb' --model 'PROVIDER/MODEL'

Select a model for the configured account and send the first request in OpenCode. Check that the client received a model response. If the provider returns model is not supported, select an identifier supported by your account and restart with --model. Check the request result even when the command exits with code 0.

The source package version is opencode-codegraph 0.1.38. For npm installation, the launcher sets the dependency range to ^0.1.38 from the package manifest. The configured npm registry must contain a version that matches this range.

Supported CodeGraph commands

The current .opencode/commands directory contains:

  • /audit — run a bounded CodeGraph audit workflow;
  • /continue — continue the current explicit CodeGraph session;
  • /explain — explain selected code with project evidence;
  • /next — inspect session state and select the next governed action;
  • /onboard — inspect the current repository and project context;
  • /review — review a bounded change;
  • /status — show CodeGraph session and context status;
  • /update — recheck context readiness; refresh only through a server-authorized action.

The /status command requests project and context-sync status, then reports freshness and the next action. The /review command starts with project and session checks, reads the changes, and produces findings linked to the evidence it used.

Headless use

For one non-interactive request:

python scripts/run_opencode_codegraph.py `
  --project 'PROJECT' --db 'data/projects/PROJECT.duckdb' `
  --run "Explain the impact of changing SYMBOL and cite source locations"

Use --session 'SESSION_ID' or --continue-last only when continuing the intended session. Confirm the project name in the response and keep freshness or degraded-mode warnings with the result.

For OpenCode 1.2.27, or when its version is unknown, the launcher disables plugin and LSP registration in headless mode. To verify hooks, open an interactive session and follow the plugin reference.

Verification and recovery

  1. Confirm the launcher reports the intended project and API endpoint.
  2. Run /status before the first code task.
  3. If MCP is unavailable, verify CodeGraph service health and the registered project name in the connection configuration.
  4. If the plugin is stale, rerun the launcher without --no-plugin-install.
  5. If evidence is stale, refresh the project before accepting the answer.

Open the source locations cited in the answer and compare them with the reviewed project revision. Save the reviewer’s conclusion with the analysis result.

To connect an editor separately, configure opencode.json using the LSP guide. It explains the CPG path, transport, and diagnostic checks.

Reference material

See the CLI guide for command parameters and troubleshooting for connection checks.

Report a documentation issue