Skip to main content

Scenario 01: Onboard to an unfamiliar codebase

Map an unfamiliar CodeGraph workspace from source and graph evidence. Check project scope, graph freshness and unanswered questions before changes.

User Guides

Start here when you join a project or prepare to change an unfamiliar component. CodeGraph builds a first map of the repository: languages, subsystems, entry points, and their connections. Source references help you check the findings and choose files for the next investigation.

Quick start

Follow the OpenCode quick start to configure the CodeGraph connection and check the repository commands. Return here to build the first map of the project.

Use an OpenCode workspace with the CodeGraph MCP connection and the onboard command installed. The repository command definition is .opencode/commands/onboard.md; installing OpenCode alone does not install it. Confirm that the active CodeGraph connection points to the intended project, then open the repository and run:

/onboard

CodeGraph uses the selected project’s metadata, graph, and documentation. Check the project name and detected root directory in the result: they should match the repository you want to explore.

What the workflow checks

The command gathers project context in this order:

  1. codegraph_project_context_status reports whether project context is usable.
  2. codegraph_project_context_sync_status reports pending or stale synchronization.
  3. codegraph_context_session_open opens or reuses an explicit context session.
  4. codegraph://project/context supplies detected project metadata and languages.
  5. codegraph_context_retrieval_evidence_fetch and codegraph_context_retrieval_fused_search retrieve architecture and documentation evidence.
  6. codegraph_context_retrieval_file_read reads only the source slices needed to confirm a claim.

codegraph_digital_employee_skill_search selects an onboarding hint. The command checks discovered components and entry points against source files.

Pass a nonempty session_id to codegraph_context_session_open or reuse an open session for this work. The server associates the collected context with that identifier. If the call returns an error, follow the action in the response and retry opening the session.

Interpret readiness before trusting the answer

Read the actual readiness_mode, reason, and next action returned by the server. The table summarizes common outcomes; stale or locked conditions may be reported in other status fields.

Interpret readiness before trusting the answer
Mode What it means Next action
ready Project context and the required evidence surfaces are available. Continue with targeted questions and source reads.
sync_pending Context projection has not caught up with the workspace. Record the pending state and wait for or run the documented synchronization action.
graph_only Structural graph evidence is available, but semantic or memory context is unavailable. Use bounded graph facts and label missing semantic context explicitly.
stale or locked The server reports that the context needs refresh or recovery. State the blocker and next action from the server response, then follow its recovery step.

A useful onboarding result

The result should let another engineer answer these questions:

  • What directory and project boundary did CodeGraph detect?
  • Which languages and major subsystems are supported by evidence?
  • Which startup paths or entry points were actually inspected?
  • What is the readiness mode, and which limitations follow from it?
  • Which claims are source-backed, and which remain unknown?
  • What is the smallest next investigation that would reduce uncertainty?

Use the map to choose your next step. Open an entry point’s source reference, follow a call to the component you want to understand, and ask about that connection. This takes you from the project overview to a specific part of the code.

Continue the investigation

If the repository contains several products, choose one user journey or component. For example: “Where does handling an HTTP request to create an order start, and which components does it call?” Replace the action with one from your project. Follow the references to check the files, functions, and connections in the answer. Then investigate dependencies, review changes, or audit the selected area.

See also Security Audit for a bounded audit after onboarding, and Feature Development after the implementation scope is accepted.

Report a documentation issue