Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: "What GitNexus tools are available?", "How do I use GitNexus?"

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: To enumerate every repository, keep calling with offset set to pagination.nextOffset until hasMore is false : 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 not at the checkout's current HEAD — the same { status, commitsBehind?, hint? } shape list repos already reports — so a direct tool call surfaces a stale index without a separate list repos call: commitsBehind is present only when git counted the gap. When git could not count it but HEAD still resolves to a commit other than the indexed one — usually because the indexed commit is no longer in the clone's history — the index is provably not at HEAD with no countable gap, so no number is reported: The field is absent when the index is current , and these four tools also omit it when the freshness check could not run at all — that case is status: "unknown" , which only the list repos listing reports. So its presence means the status is not current : read status before using commitsBehind . 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.

gitnexus-guide