/gitnexus-guide

name: gitnexus-guide
description: "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. **Bind the repository once** — use a confirmed registry name/path or configured default; call `list_repos` if unknown. Read hot-tool `staleness`; use `gitnexus://repo/{name}/context` when an overview is needed. 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. > On `query` / `context` / `impact` / `cypher`, read `staleness.status` and `staleness.branch`/`lastCommit` before using the answer. Re-analyze only for `behind` or `diverged`.

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` | Semantic rename: previews by default (`dry_run` omitted/true), applies with `dry_run: false` and the preview's `plan_token`; inspect application status and failures | | `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`) |

Choose a focused response

Use the connected server's schema; older servers may not advertise the new filters. All options below are explicit: omitting them preserves existing output. Use filters for bulky unwanted sections; on an already-small response, omission metadata can outweigh the bytes saved.

| Question | Options | | --- | --- | | Which symbols implement this? | `query`: `limit: 3`, `max_symbols: 3`, `include_content: false`, `chain_depth: 0`, `response_sections: ["process_symbols", "definitions"]` | | Which execution flows match? | `query`: keep `processes` in `response_sections`; join its `id` to `process_symbols[].process_id` | | Who calls this exact symbol? | `context`: `uid`, `response_sections: ["incoming"]`, `relationTypes: ["CALLS"]` | | What does it call, with source? | `context`: `uid`, `include_content: true`, `response_sections: ["outgoing"]`, `relationTypes: ["CALLS"]` | | What is the impact summary? | `impact`: `direction: "upstream"`, `summaryOnly: true`; risk calculation and totals are retained | | Which affected symbols need inspection? | `impact`: `limit: 10`, `offset: 0`; page as indicated by the response | | How does A reach B? | `trace`: `from_uid`, `to_uid` |

`response_sections` selects data sections for single-repository MCP `query` or `context` (not `@group` routes). Query choices: `processes`, `process_symbols`, `definitions`. Context choices: `incoming`, `outgoing`, `processes`, `chain`, `routes`, `typed_properties`; the selected symbol always remains. Context `relationTypes` accepts uppercase relationship names advertised by its schema and filters only the existing incoming/outgoing categories. It does not change ranking, traversal, source retention or the bounded candidate/reference windows.

Filters add `response_filter` with the selection and omitted fields/categories. Warnings, ambiguity, staleness and completeness metadata always remain. An empty filtered view is not proof of absence. Omit filters to expand, and never waive impact checks because a selected category is empty. `maxTokens` is a byte cutoff, not pagination: it can cut JSON. Prefer these filters, small result counts, and source/chain expansion for