CodeGraph + OpenCode Quick Start

This guide is the shortest honest path to a useful setup.

If you are new to the stack, think about it like this:

GoCPG keeps the code graph fresh.
OpenViking keeps project memory and session context.
PostgreSQL keeps the rules: who owns a session, who can read it, who can take it over, and which saved knowledge is still safe to trust.
OpenCode is the place where you ask questions, review changes, continue work, or hand context to another person.

You do not need to learn every moving part on day one. You only need to know what to start, what OpenCode can do, and what the normal daily flow looks like.

What You Get¶

After setup, OpenCode can:

understand the code graph of the current project;
use OpenViking-backed project memory when it needs wider context;
keep an explicit work session instead of starting from zero every time;
continue the same context after a restart or compaction;
let one person hand the same AI-backed session to another person for testing or review;
avoid trusting stale saved knowledge by treating it as current, needs_review, or deprecated.
access all 149 CodeGraph MCP tools, including focused tools such as codegraph_hypothesis for security hypothesis generation.

The Simple Mental Model¶

CodeGraph gives OpenCode three kinds of understanding:

Live code structure - functions, callers, callees, impact, complexity, data flow - source of truth: GoCPG
Project memory - curated skills, synced repository context, useful session-derived memory - source of truth: OpenViking
Rules and ownership - who opened a context session - who can read it - who can write to it - who accepted a handoff - whether saved knowledge is still trusted - source of truth: PostgreSQL

Before You Start¶

Make sure you have:

CodeGraph installed;
a parsed project graph (.duckdb) managed by GoCPG;
the CodeGraph API running;
OpenCode installed;
the opencode-codegraph extension enabled.

Recommended local services:

GoCPG
CodeGraph API
OpenViking
PostgreSQL

Fast Setup¶

Create opencode.json in the project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codegraph": {
      "type": "local",
      "command": ["python", "-m", "src.mcp", "--transport", "stdio", "--db", "data/projects/codegraph.duckdb"],
      "environment": {
        "CODEGRAPH_PROJECT": ""
      }
    }
  },
  "lsp": {
    "codegraph": {
      "command": ["python", "-m", "codegraph_lsp", "--db", "data/projects/codegraph.duckdb"],
      "extensions": [".py", ".go", ".js", ".ts", ".java", ".c", ".cpp", ".cs", ".kt", ".php", ".rb"]
    }
  },
  "plugin": ["opencode-codegraph"],
  "instructions": [".codegraph/AGENTS.md", ".codegraph/SCENARIO_PLAYBOOK.md"]
}

Then start OpenCode:

opencode

Or use the repository launcher:

python scripts/run_opencode_codegraph.py --model openai/gpt-5.3-codex

Quick Check¶

Run these checks:

opencode mcp list
opencode agent list
opencode debug config

Good signs:

codegraph MCP is connected;
the codegraph agent is visible;
the extension opencode-codegraph is loaded;
the LSP section points to the correct .duckdb file.

Your First 10 Minutes¶

1. Understand the project¶

In OpenCode:

/onboard how does this repository work?

What happens:

OpenCode checks whether project memory is ready;
opens or reconnects an explicit context session;
loads the right onboarding skill;
pulls only the relevant context instead of dumping everything.

2. Understand one function¶

/explain create_app

What happens:

OpenCode uses graph evidence first;
widens into project memory only when needed;
keeps the explanation inside the same investigation context.

3. Review your changes¶

/review

What happens:

OpenCode reuses the active context session when possible;
checks impact and security evidence from the graph;
adds wider memory context when it helps;
keeps the review trace connected to the same work session.

4. Check what to do next¶

/status

/next

Use these when you want one clear answer instead of guessing whether to review, update, continue, or push.

Daily Workflow¶

Here is the normal single-person flow:

Start with /onboard or /explain.
Work inside one explicit context session.
Use /review before shipping meaningful changes.
Use /status or /next when you are unsure.
Use /continue after a pause, restart, or compaction.
Use /update when the graph or project memory needs a refresh.

The important idea is this: OpenCode should not behave like it forgot everything after every pause. The system now tries to keep the same context thread alive across real work.

Team Workflow¶

The system now supports shared AI-backed work sessions inside the same project.

That means one person can start the investigation, and another person can continue from the same evidence trail.

Typical examples:

developer -> reviewer
developer -> tester
reviewer -> developer

What is supported:

a session can be opened explicitly;
a session can be shared read-only;
a session can be handed off to a new owner;
a session can be reopened later;
a session can be closed or archived when work is done.

Why this matters:

the second person does not need to rebuild context from scratch;
the same project memory and evidence chain stay attached to the same project;
ownership and access are recorded instead of being implicit or fragile.

How Memory Works¶

Not all saved knowledge is equally safe.

CodeGraph now treats OpenViking-backed knowledge with a lifecycle:

current — safe to use by default
needs_review — maybe still useful, but potentially stale
deprecated — should stay out of default retrieval

Why this matters:

old memory can actively damage answer quality;
a saved note that was correct two weeks ago may now be misleading;
the assistant should not quietly mix trusted and stale context.

Default behavior:

OpenCode prefers current;
needs_review is included only when explicitly requested;
deprecated is excluded from normal guidance.

What OpenCode Does Automatically¶

The extension already handles a lot for you:

adds code graph context when file names or change intent appear in chat;
keeps a lightweight summary of project state in the conversation;
tries to preserve explicit context continuity across long sessions;
adds scenario-aware guidance to commands like /onboard, /review, /continue, /status, /next, and /update;
runs best-effort post-commit follow-up when appropriate.

This means you usually do not need to manually call low-level memory operations.

What You Can Still Control Explicitly¶

If you want full control, the extension and API also support explicit operations:

open session
list sessions
inspect session metadata
share session
accept or reject handoff
revoke access
close session
archive session
fetch context
read a specific resource
browse a namespace
record used context
start background commit
check commit status

Most users should stay on scenario commands first and use explicit tools only when they need precision.

When Things Fall Back¶

OpenCode can work in three practical modes:

Full context - graph + project memory are both ready
Sync pending - memory is configured but not ready yet - OpenCode stays more narrow and careful
Graph-only fallback - OpenViking is unavailable or degraded - graph-backed understanding still works

This matters because the assistant should tell you the truth about what it can see right now.

Troubleshooting¶

I do not see CodeGraph tools¶

Check:

opencode mcp list
python -m src.mcp --transport stdio --db data/projects/codegraph.duckdb

`/onboard` or `/continue` feels too shallow¶

Check:

/status

If project memory is still syncing, OpenCode will stay bounded on purpose.

The assistant seems to ignore saved memory¶

Possible reasons:

the memory is still syncing;
the relevant item is marked needs_review;
the item is deprecated;
the system is in graph-only fallback mode.

Another teammate cannot continue my AI context¶

Check whether the session was:

shared read-only;
handed off explicitly;
closed or archived too early.

Recommended First Habits¶

If you want the shortest path to value, build these habits:

use /onboard when entering unfamiliar code;
use /explain before changing risky functions;
use /review before you call work done;
use /status when you feel unsure;
use /continue instead of rebuilding context manually;
hand off the session explicitly when another person takes over.

That is enough to get real value from the new architecture without learning every internal detail.

CodeGraph + OpenCode Quick Start

What You Get¶

The Simple Mental Model¶

Before You Start¶

Fast Setup¶

Quick Check¶

Your First 10 Minutes¶

1. Understand the project¶

2. Understand one function¶

3. Review your changes¶

4. Check what to do next¶

Daily Workflow¶

Team Workflow¶

How Memory Works¶

What OpenCode Does Automatically¶

What You Can Still Control Explicitly¶

When Things Fall Back¶

Troubleshooting¶

I do not see CodeGraph tools¶

/onboard or /continue feels too shallow¶

The assistant seems to ignore saved memory¶

Another teammate cannot continue my AI context¶

Recommended First Habits¶

`/onboard` or `/continue` feels too shallow¶