GitNexus

Overview

GitNexus parses a repository with Tree-sitter, resolves imports and calls across files, groups symbols into clusters, traces execution flows from entry points, and stores the result in an embedded graph database inside the repo (.gitnexus/). Agents query that graph through an MCP server (gitnexus mcp); people query it with the same commands on the CLI. Indexing and queries run locally. A browser UI at gitnexus.vercel.app can explore small repos in WebAssembly or connect to a local gitnexus serve. This skill follows GitNexus 1.6.12.

Instructions

Install and index a repository

npm install -g gitnexus          # or run each command as: npx gitnexus@latest ...
cd ~/code/checkout-service
gitnexus analyze                 # index the repo that contains the current directory
gitnexus list                    # all indexed repos (registry in ~/.gitnexus/registry.json)
gitnexus status                  # freshness of this repo's index (needs a Git repository)

analyze writes more than the index. By default it also creates or updates a GitNexus section in AGENTS.md and CLAUDE.md and installs six skills under .claude/skills/gitnexus-*. Control that with flags:

gitnexus analyze --index-only        # index only: no AGENTS.md, CLAUDE.md or skills
gitnexus analyze --skip-agents-md    # keep your own AGENTS.md / CLAUDE.md untouched
gitnexus analyze --skip-skills       # do not install the standard skills
gitnexus analyze --force             # full rebuild instead of an incremental update
gitnexus analyze --embeddings        # add semantic vectors (off by default, slower)
gitnexus analyze --skip-git          # index a folder that is not a Git repository
gitnexus analyze --watch             # keep the index current while you edit (Git repos only)

Recurring options can live in a committed .gitnexusrc JSON file at the repo root, for example { "skipSkills": true, "defaultBranch": "develop" }; CLI flags override it. Files are skipped according to .gitignore and .gitnexusignore, and anything over 512 KB is skipped unless --max-file-size raises the limit.

Connect an agent over MCP

gitnexus setup                       # detect installed editors; write their MCP config, skills and hooks
gitnexus setup -c cursor,codex       # only the listed agents

# Or register the server by hand
claude mcp add gitnexus -- npx -y gitnexus@latest mcp
codex mcp add gitnexus -- npx -y gitnexus@latest mcp

For Cursor, add the same server to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gitnexus": { "command": "npx", "args": ["-y", "gitnexus@latest", "mcp"] }
  }
}

One server process serves every indexed repo. The tools an agent gets in 1.6.12:

Set GITNEXUS_MCP_READ_ONLY=1 in the server's environment to hide cypher, rename and the group tools.

Query from the terminal

The CLI mirrors the MCP tools and prints JSON:

gitnexus query "checkout total"                         # flows related to a concept
gitnexus context OrderService                           # callers, callees, methods, flows
gitnexus impact calculateTotal                          # who breaks if this changes (upstream)
gitnexus impact calculateTotal --direction downstream   # what it depends on
gitnexus impact subtotal --file src/pricing.ts          # disambiguate a common name
gitnexus trace handleCheckout applyDiscount             # shortest call path
gitnexus detect-changes --scope all                     # staged + unstaged diff -> affected flows
gitnexus detect-changes --scope compare --base-ref main # branch vs main
gitnexus check --cycles                                 # non-zero exit on circular imports
gitnexus cypher "MATCH (f:Function) RETURN f.name, f.filePath LIMIT 5"

Add -r checkout-service (name or path) when more than one repository is indexed.

Web UI and wiki

gitnexus serve                       # HTTP API on http://127.0.0.1:4747 for the web UI
gitnexus wiki --provider openai --model gpt-4o   # LLM-written docs; reads OPENAI_API_KEY

With gitnexus serve running, gitnexus.vercel.app connects to the local server and shows the repos you already indexed. Without it the page indexes an uploaded repo in the browser, which is limited by browser memory (about 5,000 files).

Remove

gitnexus clean          # show which index would be deleted for this repo; --force deletes it
gitnexus uninstall      # preview removal of MCP entries, skills and hooks; --force applies it

Examples

Example 1: What breaks if I change this function?

User request: "Index this repo and tell me what depends on calculateTotal before I change its signature."

cd ~/code/checkout-service
gitnexus analyze --index-only
gitnexus impact calculateTotal --summary-only

  Repository indexed successfully (7.1s)
  28 nodes | 47 edges | 4 clusters | 2 flows

{
  "target": { "id": "Function:src/pricing.ts:calculateTotal", "type": "Function", "filePath": "src/pricing.ts" },
  "direction": "upstream",
  "impactedCount": 2,
  "risk": "LOW",
  "summary": { "direct": 1, "processes_affected": 1, "modules_affected": 1 },
  "byDepthCounts": { "1": 1, "2": 1 },
  "affected_processes": [ { "name": "handleCheckout", "filePath": "src/api.ts", "earliest_broken_step": 1 } ]
}

The JSON is trimmed to its main fields. Depth 1 is the direct caller (OrderService.placeOrder), depth 2 the route handler that reaches it. Drop --summary-only to list each symbol with its file. An agent connected over MCP gets the same data from impact({target: "calculateTotal", direction: "upstream"}).

Example 2: How does a request reach this code?

User request: "Show me how the checkout handler ends up in the discount logic, and who else calls calculateTotal."

gitnexus trace handleCheckout applyDiscount
gitnexus cypher "MATCH (a)-[r:CodeRelation {type: 'CALLS'}]->(b:Function {name: 'calculateTotal'}) RETURN a.name, a.filePath"

{ "status": "ok", "hopCount": 3,
  "hops": [ { "name": "handleCheckout", "filePath": "src/api.ts", "startLine": 4 },
            { "name": "placeOrder", "filePath": "src/orders.ts", "startLine": 5 },
            { "name": "calculateTotal", "filePath": "src/pricing.ts", "startLine": 10 },
            { "name": "applyDiscount", "filePath": "src/pricing.ts", "startLine": 6 } ] }

{ "markdown": "| a.name | a.filePath |\n| --- | --- |\n| placeOrder | src/orders.ts |", "row_count": 1 }

All relationships are CodeRelation edges with a type property, such as CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, MEMBER_OF (symbol to cluster) and STEP_IN_PROCESS (symbol to execution flow). The MCP resource gitnexus://repo/checkout-service/schema lists the full schema.

Guidelines

1. License — GitNexus is published under PolyForm Noncommercial 1.0.0. Commercial use needs a license from the maintainers (Akon Labs); check before adding it to a company workflow.
2. analyze edits the repo — it rewrites the GitNexus block in AGENTS.md and CLAUDE.md and adds .claude/skills/. Use --index-only in CI and in repos where those files are maintained by hand. .gitnexus/ ignores itself, so the index is never committed.
3. A stale index gives wrong answers — re-run gitnexus analyze after pulling or committing, or keep gitnexus analyze --watch running. gitnexus status shows whether the index matches the current commit.
4. Empty impact is not proof — dynamic dispatch, reflection and cross-language calls may not resolve. A result with risk: UNKNOWN or zero callers should be confirmed with a text search before deleting or renaming.
5. Keep the servers on loopback — gitnexus serve and gitnexus mcp --http bind to 127.0.0.1. Binding mcp --http to another interface requires --auth-token or GITNEXUS_MCP_AUTH_TOKEN; anyone who reaches the API can read every indexed repo.
6. Limit what agents can do — rename edits files and cypher can run any query. Use GITNEXUS_MCP_READ_ONLY=1, and GITNEXUS_MCP_ALLOWED_REPOS to expose only named repositories.
7. Install problems — on npm 11 npx gitnexus can crash with Cannot destructure property 'package' of 'node.target'; install globally instead. A global install also starts the MCP server faster than npx. Without a C++ toolchain, set GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 before installing (Dart, Proto, Swift, Kotlin and Zig files are then not parsed).
8. Wiki sends code to an LLM — unlike indexing and querying, gitnexus wiki sends repository content to the LLM provider you configure, and --api-key saves the key in ~/.gitnexus/config.json. Prefer GITNEXUS_API_KEY or OPENAI_API_KEY in the environment.
9. When not to use it — for a small project that fits in the agent's context, plain search is enough; the graph pays off on large or unfamiliar codebases and before risky refactors.