GitNexus Guide

Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.

Always Start Here

For any task involving code understanding, debugging, impact analysis, or refactoring:

1. Read gitnexus://repo/{name}/context — codebase overview + check index freshness
2. Match your task to a skill below and read that skill file
3. Follow the skill's workflow and checklist

If step 1 warns the index is stale, run node .gitnexus/run.cjs analyze in the terminal first.

Skills

Tools Reference

Paginating list_repos

list_repos is paginated so a large registry is not truncated by MCP/LLM token limits. It takes optional limit (default 50, max 200) and offset, and returns:

{
  "repositories": [
    { "name": "...", "path": "...", "indexedAt": "...", "lastCommit": "...", "stats": { } }
  ],
  "pagination": {
    "total": 437,
    "limit": 50,
    "offset": 0,
    "returned": 50,
    "hasMore": true,
    "nextOffset": 50
  }
}

To enumerate every repository, keep calling with offset set to pagination.nextOffset until hasMore is false:

list_repos {}               → repos 1–50,    nextOffset 50,  hasMore true
list_repos { offset: 50 }   → repos 51–100,  nextOffset 100, hasMore true
…
list_repos { offset: 400 }  → repos 401–437,                 hasMore false   (done)

Notes: offset ≥ total returns an empty page (with total still reported). Out-of-range or malformed limit/offset (non-integer, limit outside [1, 200], offset < 0) are rejected with a clear error — limit above the max is rejected, not silently capped. The order is deterministic (lower-cased name, then path), so paging never skips or duplicates an entry while the registry is unchanged.

Inline staleness signal (query / context / impact / cypher)

These four hot read tools attach a non-blocking staleness field to their response when the index is behind the checkout's current HEAD — the same { commitsBehind, hint } shape listrepos already reports — so a direct tool call surfaces a behind-HEAD index without a separate listrepos call:

{ /* …the tool's normal result… */
  "staleness": { "commitsBehind": 3, "hint": "⚠️ Index is 3 commits behind HEAD. Run analyze tool to update." }
}

The field is absent when the index is current (or when the freshness check can't run), so its presence is the signal. It is only ever added to object results — raw-array cypher output and error envelopes are returned unchanged. @group-targeted calls do not carry it (multi-repo staleness is ill-defined). When you see it, the graph may be behind the working tree — re-run analyze before trusting blast-radius or dependence answers.

Taint findings (explain)

explain returns taint findings recorded by gitnexus analyze --pdg — intra-procedural TAINTED edges plus cross-function TAINT_PATH hops where the interprocedural taint phase found a function-level source→sink chain. Each finding includes a sink category (command-injection, code-injection, path-traversal, sql-injection, xss), source/sink lines, and the ordered hop path with the variable carried on each hop.

• explain {} — enumerate all findings for the repo (bounded by limit, deterministic order)
• explain { target: "src/vuln.ts" } — findings in a file (suffix path match accepted)
• explain { target: "runUserCommand" } — findings in a function (resolved like context; ambiguous names return ranked candidates)

A repo indexed without --pdg returns a clear "no taint layer" note. Caveats: closure/callback, property/field, and implicit flows are not modeled, and interprocedural findings are function-level TAINT_PATH hops rather than statement-level path proof, so the absence of a finding is not proof of safety. SANITIZES (sanitizer-kill) edges are queryable via cypher.

Control & data dependence (pdg_query)

pdgquery reads the control/data-dependence layers gitnexus analyze --pdg records (CDG + REACHINGDEF, basic-block granular) — the control/data analog of explain. It is always anchored (a target file path or symbol, resolved like context) and has two modes:

• pdg_query { mode: "controls", target: "..." } — CDG: "under what condition does X run?". Each edge is a controlling predicate block → dependent block with the branch sense ('T'/'F') in reason; an edge into an early return/throw is flagged guard: true (guard-clause discovery — the sense depends on the predicate, so don't filter guards by a fixed label).
• pdgquery { mode: "flows", target: "...", variable?: "..." } — REACHINGDEF def→use edges within the function; pass variable to trace one binding.

A repo indexed without --pdg returns a "no PDG layer" note (or "status unknown" when the layer can't be confirmed). Intra-procedural only — cross-function flow is taint's domain (explain). The raw CDG/REACHING_DEF edges are also queryable via cypher. See the gitnexus-pdg-query skill for the full query surface.

Shortest path between two symbols (trace)

trace answers "how does A reach B?" in one call — the shortest directed path over CALLS (plus HAS_METHOD, so a class-rooted trace descends into its methods) instead of chaining 3–8 context/impact hops by hand.

• trace { from: "validateUser", to: "executeQuery" } — shortest path between two symbols.
• Disambiguate common names with fromuid/touid (zero-ambiguity) or fromfile/tofile; an ambiguous name returns ranked candidates.
• maxDepth (default 10, max 30) bounds the search; includeTests (default false) lets the traversal pass through test-file symbols.

Returns ordered hops (each { name, filePath, startLine }) and an aligned edges[] of { relType, confidence }, so call hops and containment (HASMETHOD) hops stay distinguishable. When no path exists it reports the furthest reachable node (where the chain breaks) and sets truncated: true if a traversal cap was hit first. Every result carries a status: ok / nopath / ambiguous / not_found / error.

Cross-repo (experimental): pass repo: "@groupName" to trace across a group's member repos — the path may cross one ContractLink boundary (reported as a CONTRACTLINK hop with the bridged contract in crossings[]). Omit to entirely to follow from's outgoing HTTP call to whatever provider endpoint it lands on. Groups are configured via grouplist / group_sync.

Resources Reference

Lightweight reads (~100-500 tokens) for navigation:

Graph Schema

Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process, Route, Tool, plus language-specific types (Struct, Enum, Trait, Impl, Namespace, Module, …) and BasicBlock (--pdg indexes only). The full node list lives in gitnexus://repo/{name}/schema. Edges (via CodeRelation.type): CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, CONTAINS, MEMBEROF, HASMETHOD, HASPROPERTY, ACCESSES, METHODOVERRIDES, METHODIMPLEMENTS, STEPINPROCESS, HANDLESROUTE, FETCHES, HANDLESTOOL, ENTRYPOINTOF, WRAPS, QUERIES, INJECTS, plus --pdg-only types (CFG, REACHINGDEF, TAINTED, SANITIZES, TAINT_PATH, CDG — zero rows on a default index).

Read gitnexus://repo/{name}/schema before writing Cypher — it is the authoritative schema for the indexed repo.

MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
RETURN caller.name, caller.filePath