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
The current package manifest resolves to:
npm install opencode-codegraph@0.1.38
Register the package in the OpenCode configuration:
{
"plugin": ["opencode-codegraph"]
}
For the CodeGraph source checkout, prefer the repository launcher because it also prepares the matching MCP, LSP, package, project, and API configuration:
python scripts/run_opencode_codegraph.py --project <project-name>
The launcher’s current default model is openai/gpt-5.4; override it only through the documented
launcher option or CODEGRAPH_OPENCODE_MODEL. At this source revision the server catalog contains
95 tools in the full profile. That count is revision-bound: verify it in
src/mcp/surface_catalog.py instead of treating it as a stable plugin contract.
Do not compensate for failed project discovery with raw database parameters. Repair the project registration or launcher configuration.
Runtime inputs
The adapter reads:
| Variable | Meaning |
|---|---|
CODEGRAPH_API_URL |
CodeGraph API root; default http://localhost:8000 |
CODEGRAPH_PROJECT |
Explicit project scope for plugin API calls |
The API, MCP server, and CPG lifecycle remain CodeGraph runtime responsibilities. Installing the npm package adds the client integration; the CodeGraph runtime starts the services, authorizes the client, and reports project-graph freshness.
OpenCode hook contract
The maintained source registers these OpenCode hooks:
| 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 also consumes OpenCode lifecycle events for child-session memory. Hook output supplies context; Git, CI, review, security, and release owners record their decisions in the corresponding workflow.
Guided commands and tools
The supported command files are the current contents of .opencode/commands: /audit,
/continue, /explain, /next, /onboard, /review, /status, and /update. A command absent
from that directory is not supported merely because an old article mentioned it.
The adapter exposes a small set of direct graph/review tools and explicit CodeGraph context-session tools. The full MCP catalog is discovered from the configured server and changes independently; this page describes the discovery mechanism rather than a fixed tool count. Native MCP arrays and objects must remain native values.
Context and continuity
The plugin distinguishes full context, sync-pending, and graph-only fallback. Degraded mode is labelled and must not be reported as full semantic context. Explicit sessions may be reopened, shared read-only, or handed off only through the corresponding server contract.
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 rather than loading the
portable Agent Plugins package. Follow Remote MCP authentication for
opencode mcp auth codegraph, logout, project binding, and recovery.
python scripts/run_opencode_codegraph.py --project <project-name> --run "/status"
Verify the intended project, API endpoint, plugin version, context mode, and freshness. Then run one
bounded /explain or /review and confirm its source references. To roll back, reinstall the
previous approved package and remove only the tested plugin registration; do not modify customer
repository files or re-enable retired MCP aliases.
Source of truth
- Package and version:
integrations/opencode/opencode-codegraph/package.json - Adapter:
integrations/opencode/opencode-codegraph/src/index.ts - API client:
integrations/opencode/opencode-codegraph/src/api.ts - Launcher:
scripts/run_opencode_codegraph.py