| 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:
- Read
gitnexus://repo/{name}/context — codebase overview + check index freshness
- Match your task to a skill below and read that skill file
- 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 |
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) |
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.
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, Function, Class, Interface, Method, Community, Process
Edges (via CodeRelation.type): CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
RETURN caller.name, caller.filePath
