abhigyanpatwari/gitnexus-guide

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

| Task | Skill to read | | -------------------------------------------- | ------------------- | | Understand architecture / "How does X work?" | gitnexus-exploring | | Blast radius / "What breaks if I change X?" | gitnexus-impact-analysis | | Trace bugs / "Why is X failing?" | gitnexus-debugging | | Rename / extract / split / refactor | gitnexus-refactoring | | Tools, resources, schema reference | gitnexus-guide (this file) | | Index, status, clean, wiki CLI commands | gitnexus-cli |

Tools Reference

| Tool | What it gives you | | ---------------- | ------------------------------------------------------------------------ | | query | Process-grouped code intelligence — execution flows related to a concept | | context | 360-degree symbol view — categorized refs, processes it participates in | | impact | Symbol blast radius — what breaks at depth 1/2/3 with confidence | | trace | Shortest path between two symbols — "how does A reach B?" in one call | | detect_changes | Git-diff impact — what do your current changes affect | | rename | Multi-file coordinated rename with confidence-tagged edits | | cypher | Raw graph queries (read gitnexus://repo/{name}/schema first) | | explain | Persisted taint findings — source→sink data flows (needs analyze --pdg) | | pdg_query | Control/data dependence — what gates X (CDG) / where Y flows (REACHING_DEF); needs analyze --pdg | | check | Check graph invariants such as circular imports | | route_map | API route map — which components/hooks fetch which endpoints, and the handler files that serve them | | shape_check | Response-shape drift — keys each route returns vs keys its consumers access (flags MISMATCH) | | api_impact | Pre-change report for an API route — consumers, middleware, shape mismatches, risk level | | tool_map | MCP/RPC tool definitions and the files that handle them | | group_list | List configured multi-repo groups, or one group's config | | group_sync | Rebuild a group's Contract Registry (cross-repo HTTP contract links); run after group.yaml changes or member re-index | | list_repos | Discover indexed repos (paginated — limit/offset) |

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 list_repos already reports — so a direct tool call surfaces a behind-HEAD index without a separate list_repos 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)

pdg_query reads the control/data-dependence layers gitnexus analyze --pdg records (CDG + REACHING_DEF, 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).
• pdg_query { mode: "flows", target: "...", variable?: "..." } — REACHING_DEF 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 from_uid/to_uid (zero-ambiguity) or from_file/to_file; 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 (HAS_METHOD) 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 / no_path / 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 CONTRACT_LINK 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 group_list / group_sync.

Resources Reference

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

| Resource | Content | | ---------------------------------------------- | ----------------------------------------- | | gitnexus://repo/{name}/context | Stats, staleness check | | gitnexus://repo/{name}/clusters | All functional areas with cohesion scores | | gitnexus://repo/{name}/cluster/{clusterName} | Area members | | gitnexus://repo/{name}/processes | All execution flows | | gitnexus://repo/{name}/process/{processName} | Step-by-step trace | | gitnexus://repo/{name}/schema | Graph schema for Cypher |

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, MEMBER_OF, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, METHOD_IMPLEMENTS, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF, WRAPS, QUERIES, INJECTS, plus --pdg-only types (CFG, REACHING_DEF, 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