Skip to main content

OpenCode plugin

Install and configure the opencode-codegraph adapter. Check plugin startup, authentication and supported commands before analyzing a project.

Integrations

opencode-codegraph is the maintained OpenCode adapter for CodeGraph. It adds graph-backed prompt context, guided CodeGraph commands, explicit context-session tools, review tools, and post-command workflow guidance. The OpenCode quick start is the operator procedure; this page explains what the adapter does and where its boundary ends.

Install and register

For a direct setup, add opencode-codegraph to the plugin array in opencode.json at the project root. OpenCode loads npm plugins listed there when it starts. See the OpenCode plugin guide. Keep the other plugins and configuration settings:

{
  "plugin": ["opencode-codegraph"]
}

To prepare a CodeGraph source checkout, run the repository launcher from its source root. This path requires the CodeGraph Python dependencies, Node.js/npm, an installed OpenCode client, and a registered project with a CPG. Replace PROJECT with your project name. The launcher prepares MCP, LSP, plugin and API configuration:

python scripts/run_opencode_codegraph.py --project 'PROJECT'

The launcher’s default model is openai/gpt-5.4. Choose a model available to your OpenCode account and set it through --model or CODEGRAPH_OPENCODE_MODEL. The MCP catalog depends on the server profile. Discover available tools through the configured connection. Follow the MCP operator guide to initialize the connection, inspect tools/list, and check the invocation policy for the selected profile.

If the launcher cannot find the project, check its registration and the --project value. Follow the project checks in the quick start.

Runtime inputs

The adapter reads:

Runtime inputs
Variable Meaning
CODEGRAPH_API_URL CodeGraph API root; default http://localhost:8000
CODEGRAPH_PROJECT Explicit project scope for plugin API calls

The adapter connects to the CodeGraph API and configured MCP server. Its context and follow-up guidance reflect the graph and workflow evidence available for the selected project.

OpenCode hook contract

The maintained source registers these OpenCode hooks:

OpenCode hook contract
Hook Current role
experimental.chat.system.transform Add project and workflow context to the system prompt
command.execute.before Prepare guided slash-command context
chat.message Enrich file/edit/workflow intents with bounded evidence
tool.execute.after React to tests, Git commands, and commits with workflow guidance

The plugin consumes OpenCode lifecycle events and saves child-session context. Hooks add project context to prompts and provide follow-up guidance. After a recognized Git commit, the plugin requests an incremental CPG update and reports its asynchronous status.

Guided commands and tools

The supported command files are the current contents of .opencode/commands: /audit, /continue, /explain, /next, /onboard, /review, /status, and /update. Each file defines the instructions for its command.

The adapter provides direct graph and review tools, plus explicit CodeGraph context-session tools. The full MCP catalog comes from the configured server. Use tools/list to inspect the selected server profile. Pass MCP arrays and objects as native values.

The guided commands give common CodeGraph tasks a consistent entry point:

Guided commands and tools
Command Result
/audit A bounded audit with readiness, findings, evidence and next action
/continue The next authorized step for the current explicit task and session
/explain A source-backed explanation of code behavior and dependencies
/next The best next governed action, without executing it
/onboard Workspace boundaries, languages, architecture signals and readiness
/review Findings for a bounded change, linked to the evidence used
/status Project, context-session and CPG readiness
/update A readiness recheck and any supported refresh action

Context and continuity

The plugin reports its context mode: full, sync-pending, or graph-only. This status shows which data is available for the prompt. Use CodeGraph context-session tools to reopen a session, share read-only access, or hand off ownership.

Lightweight resume state under .opencode/state links a local OpenCode session to CodeGraph. It stores the local binding; the authoritative server session stores the workflow history and mutation state. Closed or archived sessions cannot be used for further mutation.

Post-commit behavior

After a recognized Git commit, tool.execute.after can request a local incremental update through the authenticated CodeGraph runtime route and then show pending or completed workflow guidance. Request acceptance is asynchronous: use the CPG, context-sync, and review evidence statuses to follow the request to completion.

Verification and rollback

For remote MCP, OpenCode uses its own configuration and OAuth adapter. Follow Remote MCP authentication for opencode mcp auth codegraph, logout, project binding, and recovery.

python scripts/run_opencode_codegraph.py --project 'PROJECT' --run "/status"

For OpenCode 1.2.27, or when its version cannot be determined, the launcher uses headless-safe mode without plugin or LSP registration. Check the /status response in this mode; check plugin hooks in an interactive session.

Check the project, context mode and CPG freshness in the /status response. Then run /explain for one file or function and check its source references against the code.

To disable the plugin, remove only opencode-codegraph from the plugin array in your working opencode.json and reopen OpenCode. Keep the other array entries. To return to a previous approved version, install that version and keep the plugin registered.

Report a documentation issue