opencode-codegraph

OpenCode plugin for CodeGraph CPG-powered code analysis.

Automatically enriches AI conversations with Code Property Graph data -- security findings, call graphs, complexity metrics, and taint analysis -- without manual tool invocation.

Install

// opencode.json
{
  "plugin": ["opencode-codegraph"]
}

Prerequisites

• CodeGraph installed with CPG database built
• CodeGraph API running (uvicorn src.api.main:app --port 8000)
• CodeGraph MCP server configured in opencode.json

Features

Auto-Enrichment

When you mention a file in chat, the plugin adds CPG context automatically:

You: "Refactor src/api/routers/webhook.py"

Plugin injects:
  ### CPG context: src/api/routers/webhook.py
  **12 methods** in file:
  - `receive_github_webhook` CC=5 fan_in=0 fan_out=3 [entry]
  - `_handle_push` CC=2 fan_in=4 fan_out=2
  **2 security findings:**
  - CWE-89 L42: SQL injection in query parameter

If the message also suggests an edit intent (refactor, fix, modify, update, etc.), the plugin appends a pre-edit warning block with complexity, fan-out, dead-code, and security hints for the referenced file.

If the message suggests workflow guidance intent (what next, am I done, can I push, etc.), the plugin appends the current dogfooding status summary so the session can answer with the right next command immediately.

System Prompt

Every conversation includes:

• a project summary with file count, top complexity hotspots, and open security findings;
• a lightweight dogfooding status block when available, including freshness, current HEAD, git branch/worktree cleanliness, review-trace state, and recommended next action.
• the same status block now also includes branch and worktree cleanliness, which lets guided commands distinguish changes_pending_review from ready_to_push.
• a recommended command (/status, /update, or /review) when the workflow can point to a deterministic next step.
• a normalized workflow state so the session can distinguish refresh_needed, trace_pending, review_required, and ready_to_continue.
• a ready_to_push state when the session is fresh, the review trace is green, and the worktree is clean.
• database availability is reported as read-only session status; manual maintenance and unlock controls are intentionally not exposed through the plugin.

Post-Commit Updates

After git commit, the plugin triggers incremental CPG re-parsing via GoCPG and syncs the ChromaDB vector store. If durable review-trace artifacts exist for the new HEAD, the plugin also appends a structured post-commit block plus the current workflow guidance with:

• what changed in the review trace
• why it matters
• top recommendations
• one clear next action
• one suggested command to run next
• one normalized workflow state

If the durable review trace is not available yet, the plugin still appends a pending summary telling the developer to check /status instead of leaving the post-commit state ambiguous.

This means the post-commit UX now has two explicit states:

• trace ready -> structured summary with findings, recommendations, and next action
• trace pending/missing -> structured pending summary with deterministic follow-up

Custom Tools

| Tool | Description | |------|-------------| | codegraph_review | Security + impact analysis on current diff | | codegraph_explain_function | Deep function analysis with call graph |

Permissions

All codegraph_* MCP tools are auto-allowed -- no confirmation prompts.

Custom Commands

Place in .opencode/commands/:

| Command | Description | |---------|-------------| | /review | CPG-powered code review | | /audit | Full codebase audit (12 dimensions) | | /explain | Function analysis with call graph | | /onboard | Codebase understanding | | /update | Freshness check and incremental CPG update | | /status | Unified freshness + latest review-trace status | | /next | Single best next command for the current workflow state | | /continue | Safely execute the next refresh/review workflow step |

Custom Agent

.opencode/agents/codegraph.md -- CPG-focused analysis agent. Switch with /agent codegraph.

Configuration

| Variable | Default | Description | |----------|---------|-------------| | CODEGRAPH_API_URL | http://localhost:8000 | CodeGraph API base URL | | CODEGRAPH_PROJECT | (empty) | Default project ID |

Hooks

| Hook | Purpose | |------|---------| | experimental.chat.system.transform | Inject project summary into system prompt | | chat.message | Add CPG context for mentioned files | | chat.message (edit intent) | Add pre-edit warnings for files likely to be modified | | chat.message (workflow intent) | Add dogfooding status when the user asks what to do next | | tool.execute.after on test commands | Add after-test workflow guidance and detect failed test runs before suggesting the next command | | tool.execute.after on git status / git diff | Add the same normalized workflow guidance block used by other status-oriented surfaces | | tool.execute.after | Trigger CPG update after git commit and append structured post-commit review summary | | generic tool.execute.after | Surface workflow-state transitions after other bash commands when the underlying state changes | | codegraph_review tool | Returns review results together with current workflow guidance and suggested follow-up command | | codegraph_explain_function tool | Returns function analysis together with current workflow guidance | | experimental.session.compacting | Preserve current dogfooding status when OpenCode compacts long sessions | | command.execute.before | Inject current dogfooding status into /review, /audit, /update, /status, /next, and /continue | | permission.ask | Auto-allow codegraph_* tools |

Across status-oriented surfaces, the plugin is converging on one shared summary contract:

• workflow state
• policy version / priority reason
• primary issue
• recovery sequence
• blockers
• warnings
• what improved
• still blocked
• recommended command
• database access blockers when DuckDB reads are temporarily unavailable

License

MIT