| name | codehub-guide |
| description | Use when the user asks about OpenCodeHub itself — available MCP tools, resources, graph schema, or workflow reference. Examples: "What OpenCodeHub tools are available?", "How do I query the code graph?", "Show me the schema". |
OpenCodeHub Guide
Quick reference for every OpenCodeHub MCP tool, MCP resource, and the graph + temporal store schema.
Always Start Here
For any task that touches code understanding, debugging, impact analysis, refactoring, or PR review:
- Call
mcp__codehub__list_repos — confirm the repo is indexed and pick a repo name.
- Read
codehub://repo/{name}/context — codebase stats and a staleness envelope.
- Match the task to a skill below and follow that skill's checklist.
If the context envelope reports the index is stale, run codehub analyze in the terminal first. If it says weights are missing, run codehub setup --embeddings to fetch the 768d gte-modernbert-base ONNX weights.
Skills · analysis
| Task | Skill to read |
|---|
| Understand architecture / "How does X work?" | codehub-exploring |
| Blast radius / "What breaks if I change X?" | codehub-impact-analysis |
| Trace bugs / "Why is X failing?" | codehub-debugging |
| Plan a rename / extract / move (analysis only) | codehub-refactoring |
| Review a PR / "Is this safe to merge?" | codehub-pr-review |
| Tools, resources, schema reference | codehub-guide (here) |
Skills · artifact factory (spec 001)
These skills produce committed Markdown artifacts — the durable output
Principal engineers ship. See ADR 0007
for the scope rationale.
| Task | Skill to invoke | Trigger phrase |
|---|
| Generate the full doc tree (single or group) | codehub-document | "document this repo", "regenerate architecture docs" |
| Draft a PR description from the current diff | codehub-pr-description | "write the PR description", "summarize this branch" |
| Write an onboarding guide with reading order | codehub-onboarding | "write ONBOARDING.md", "what should a new hire read first" |
| Map inter-repo contracts for a group | codehub-contract-map | "map the contracts", "show the contract matrix for " |
| Build a deterministic 9-item code-pack BOM | codehub-code-pack | "pack this repo for an LLM", "deterministic code pack", "pack the platform group" |
| Draft an ADR (P1 — not yet shipped) | codehub-adr (P1 backlog) | — |
Fire these directly; do not nest them inside analysis skills. Each is a
standalone artifact producer with its own preconditions and output path.
Tool Inventory (28 MCP tools)
Every tool is read-only with respect to your source. No MCP tool edits the working tree; planning and verification tools surface what to change, and you (or your editor) apply the edit.
Code intelligence (per-repo)
| Tool | What it gives you |
|---|
mcp__codehub__list_repos | Enumerate indexed repos on this machine |
mcp__codehub__query | Hybrid BM25 + vector search over symbols, grouped by process |
mcp__codehub__context | 360-degree symbol view + confidenceBreakdown + cochanges side-section |
mcp__codehub__impact | Blast radius with risk tier + confidenceBreakdown |
mcp__codehub__detect_changes | Map an uncommitted or committed diff to affected symbols and flows |
mcp__codehub__sql | Read-only query: sql arg → temporal DuckDB (cochanges/summaries); cypher arg → lbug graph (5 s timeout) |
mcp__codehub__signature | Symbol declaration + stubbed members (class/interface header + method/property signatures, bodies elided) |
HTTP / RPC surface
| Tool | What it gives you |
|---|
mcp__codehub__route_map | HTTP route inventory (method, path, handler, middleware) |
mcp__codehub__tool_map | MCP tool inventory exported by this repo |
mcp__codehub__shape_check | Producer/consumer response-shape mismatches |
mcp__codehub__api_impact | HTTP consumer chain + middleware + affected processes for one route |
Cross-repo (groups)
| Tool | What it gives you |
|---|
mcp__codehub__group_list | Discover named repo groups |
mcp__codehub__group_query | BM25 fan-out across a group with reciprocal-rank fusion |
mcp__codehub__group_status | Per-repo staleness + contract freshness for a group |
mcp__codehub__group_contracts | HTTP contract cross-links (consumer FETCHES edge → producer Route) |
mcp__codehub__group_cross_repo_links | Audit trail of every typed cross-repo edge, both endpoints repo_uri-qualified |
mcp__codehub__group_sync | Rebuild the cross-repo contract registry + link table after a re-index |
Supply-chain / PR review (OpenCodeHub differentiators)
| Tool | What it gives you |
|---|
mcp__codehub__verdict | 5-tier PR decision (auto_merge → block) with top drivers |
mcp__codehub__scan | Run Priority-1 scanners (openWorld — spawns child processes) |
mcp__codehub__list_findings | Browse SARIF findings produced by scan or ingest-sarif |
mcp__codehub__list_findings_delta | Diff latest scan vs. frozen baseline (new / fixed / unchanged / updated) |
mcp__codehub__list_dead_code | Unreferenced exported symbols (read-only listing — you delete them) |
mcp__codehub__license_audit | Copyleft / unknown / proprietary tier check over dependencies |
mcp__codehub__dependencies | External package list (ecosystem + version + manifest path) |
mcp__codehub__owners | File/symbol ownership from CODEOWNERS + git blame signal |
mcp__codehub__risk_trends | Per-community trend lines and 30-day projections |
mcp__codehub__project_profile | High-level repo summary (languages, stacks, entry points) |
mcp__codehub__pack_codebase | Deterministic LLM-ready code-pack snapshot of the repo |
Differentiators to surface in responses
confidenceBreakdown — every context and impact response carries a {confirmed, heuristic, unknown} tally. confirmed means a SCIP indexer (scip-typescript / scip-python / scip-go / rust-analyzer / scip-java) has confirmed the edge at confidence ≥ 0.95. heuristic is tree-sitter or tier-1/tier-2 inference the SCIP oracle has not confirmed. unknown is demoted (≤ 0.2) — a SCIP-confirmed edge exists at the same triple and the heuristic carries a +scip-unconfirmed reason suffix. Report this breakdown when an agent is about to take a destructive action based on edges.cochanges side-section — context includes files historically co-edited with the target (by lift, from the dedicated cochanges table). This is a git-history signal, not call dependencies — label it that way when you report it. It is excluded from the graph hash.verdict + list_findings + list_findings_delta — PR review grade is deterministic, not opinion.license_audit + risk_trends + owners — first-class audit workflows without writing SQL.
Resource Inventory
Lightweight reads for navigation (every URI uses the codehub:// scheme):
| Resource | Content |
|---|
codehub://repos | Registry list: names, roots, graph hashes |
codehub://repo/{name}/context | Stats + staleness envelope |
codehub://repo/{name}/schema | Live node kinds / relation types for sql |
Cluster and process navigation resources (codehub://repo/{name}/clusters, codehub://repo/{name}/processes, etc.) are slated for a later wave. Until then, use the typed tools or Cypher (below) filtered to kind = 'Community' / kind = 'Process'.
Where the graph lives (ADR 0016)
There are two stores, and they are queried differently:
- Graph tier —
graph.lbug (ladybug, Cypher dialect). Holds nodes, edges,
and embeddings. Query it via the typed tools (query / context / impact /
route_map / …) or, for bespoke questions, Cypher via the MCP sql
tool's cypher argument. There is NO nodes or relations SQL table.
- Temporal tier —
temporal.duckdb (DuckDB SQL). Holds only the
cochanges and symbol_summaries tables. The sql argument of the MCP
sql tool (and codehub sql on the CLI) targets THIS store.
Pass exactly one of sql (temporal DuckDB) or cypher (lbug graph) to the MCP
sql tool.
Graph schema (lbug / Cypher)
One node label CodeNode carrying kind as a property (NOT a per-kind
label). One relationship table per relation type. Properties are snake_case
(file_path, start_line, inferred_label, step_count, entry_point_id);
a camelCase RETURN alias comes back as the alias you give it, but the stored
property names are snake_case.
Node kinds (n.kind values): File, Folder, Function, Class, Method,
Interface, Constructor, Struct, Enum, Macro, Typedef, Union, Namespace, Trait,
Impl, TypeAlias, Const, Static, Variable, Property, Record, Delegate,
Annotation, Template, Module, CodeElement, Community, Process, Route, Tool,
Finding, Dependency, Contributor, Repo, ProjectProfile, Section.
Relationship types (each is its own edge label): CONTAINS, DEFINES, IMPORTS,
CALLS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES,
OVERRIDES, METHOD_IMPLEMENTS, MEMBER_OF, PROCESS_STEP, HANDLES_ROUTE, FETCHES,
HANDLES_TOOL, ENTRY_POINT_OF, WRAPS, QUERIES, REFERENCES, FOUND_IN, DEPENDS_ON,
OWNED_BY.
Cochanges live only in the temporal cochanges table (DuckDB SQL), never as
graph edges.
Cypher cheat-sheet (MCP sql tool, cypher arg)
All inbound callers of a function by name:
MATCH (caller:CodeNode)-[r:CALLS]->(callee:CodeNode)
WHERE callee.name = 'validateUser' AND callee.kind = 'Function'
RETURN caller.name AS name, caller.file_path AS file, caller.start_line AS line,
r.confidence AS confidence, r.reason AS reason
ORDER BY r.confidence DESC
LIMIT 50
Top communities by cohesion:
MATCH (n:CodeNode)
WHERE n.kind = 'Community'
RETURN n.name AS name, n.inferred_label AS label, n.cohesion AS cohesion,
n.symbol_count AS symbols
ORDER BY n.cohesion DESC
LIMIT 20
Process entry points:
MATCH (n:CodeNode)
WHERE n.kind = 'Process'
RETURN n.name AS name, n.inferred_label AS label, n.step_count AS steps,
n.entry_point_id AS entry_point
ORDER BY n.step_count DESC
SCIP-confirmed CALLS edges only (strict impact):
MATCH ()-[r:CALLS]->()
WHERE r.confidence >= 0.95 AND r.reason STARTS WITH 'scip:'
RETURN r
Temporal SQL cheat-sheet (MCP sql tool, sql arg)
Tightest co-change pairs (DuckDB SQL — temporal store):
SELECT source_file, target_file, lift, cocommit_count
FROM cochanges
ORDER BY lift DESC
LIMIT 20;
Invariants agents must respect
- Every per-repo tool accepts an optional
repo argument. When exactly one repo is indexed, repo is optional. When two or more are indexed and repo is omitted, the tool returns AMBIGUOUS_REPO — pass repo explicitly.
- Every response may carry
_meta.codehub/staleness when the index is behind HEAD. Surface that to the user when it is present.
- Every response includes a
next_steps array under structuredContent. Use it to pick the next tool without guessing.
- No MCP tool edits user source. Tools like
impact, context, and detect_changes tell you what a change touches; you (or your editor) make the edit, then re-run detect_changes to verify.
scan has openWorldHint: true — it spawns child processes. Do not invoke it on every turn.
