Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: "How does X work?", "What calls this function?", "Show me the auth flow"

Exploring Codebases with GitNexus When to Use "How does authentication work?" "What's the project structure?" "Show me the main components" "Where is the database logic?" Understanding code you haven't seen before Bind the repository first Bind once per session using a confirmed registry name/path or configured MCP default; reuse it. Call list repos {} when the target is not yet known, not before every question. Never guess the registry name from the checkout directory. With one indexed repository, use the examples below as written. With more than one, pass repo on every call: an omitted repo normally errors, but under an MCP policy with a configured default it resolves to that default silently. If you cannot tell which repository is meant, stop and ask. Report the bound repository and index freshness alongside your explanation. list repos is paginated, so page with offset: pagination.nextOffset until hasMore is false before concluding a repository is absent. Workflow If the index is stale → run node .gitnexus/run.cjs analyze in terminal. Hot tool staleness names which index answered ( branch / lastCommit ) and how fresh it is ( status ). Re analyze only for behind or diverged — current is identity, unknown is unmeasurable. Ask for only the evidence needed Use options advertised by the connected server. response sections and context relationTypes are opt in views for a single repository, not @group routing. On an older server, use the existing limits and content/chain options instead. Use filters when unwanted sections are bulky; their omission metadata can make an already small response slightly larger. Aim for 2–3 focused calls after repository binding; stop when the question is answered, but expand if evidence or a required safety check is still missing. If the symbol is already known, start with context ; use uid , or name plus file path / kind , to avoid ambiguous results. To answer only “who calls it?”, request response sections: ["incoming"] , relationTypes: ["CALLS"] and leave include content false. Keep processes in a query when the question is about flows, rather than requesting a symbols only view. Do not request source and multi hop chains for every search hit. Fetch source for the selected symbol only; for a large class/file, prefer read file with a small 0 based startLine / endLine window (subtract 1 from graph line numbers), or maxLines for a whole file read, if that tool is available. Use trace for a known A→B path instead of repeatedly expanding context . Filters retain requested sections/categories and hide the others; they do not prove other references are absent or make the existing bounded search exhaustive. Read response filter , warning , partial , truncated , epistemic and staleness . Remove filters when broader evidence is needed. maxTokens is a last resort byte cutoff that can cut JSON: narrow the request rather than treating a cut response as complete. Never use a filtered caller view to waive the required impact check or an UNKNOWN risk. Checklist Resources Resource What you get gitnexus://repo/{name}/context Stats, staleness warning (~150 tokens) gitnexus://repo/{name}/clusters All functional areas with cohesion scores (~300 tokens) gitnexus://repo/{name}/cluster/{name} Area members with file paths (~500 tokens) gitnexus://repo/{name}/process/{name} Step by step execution trace (~200 tokens) Tools query — find execution flows related to a concept: context — 360 degree view of a symbol: repo is required once more than one repository is indexed, and may be omitted with a single one. Example: "How does payment processing work?" With my app already bound and the index current: Report the repository and index freshness with the explanation. If my app had not yet been bound, discover it once with list repos first.

gitnexus-exploring