GitNexus

Code knowledge graph for coding agents: symbol context, change impact, call paths and renames.

By Abhigyan Patwari (individual) TypeScript Local · stdio Developer toolsKnowledge and memory

86 popularity score ★ 48k ↓ 53k/wk

Connect your client

Local (npm)

Add in one click

Opens the app, which asks before it adds the server.

Or add it by command or config

FirstTerminal
npx gitnexus analyze
Claude CodeTerminal
claude mcp add gitnexus -- npx -y gitnexus@latest mcp
Claude Desktopclaude_desktop_config.json
{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": [
        "-y",
        "gitnexus@latest",
        "mcp"
      ]
    }
  }
}
Cursor~/.cursor/mcp.json
{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": [
        "-y",
        "gitnexus@latest",
        "mcp"
      ]
    }
  }
}
VS Code.vscode/mcp.json
{
  "servers": {
    "gitnexus": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "gitnexus@latest",
        "mcp"
      ]
    }
  }
}
Codex~/.codex/config.toml
[mcp_servers.gitnexus]
command = "npx"
args = ["-y", "gitnexus@latest", "mcp"]
Gemini CLITerminal
gemini mcp add --scope user gitnexus npx -- -y gitnexus@latest mcp

Settings 2

GITNEXUS_MCP_READ_ONLY Optional: Set to 1 to hide rename, cypher, group_list and group_sync and refuse group routing; any value other than 0 or 1 stops the server. Default 0.
GITNEXUS_MCP_DEFAULT_MAX_TOKENS Optional: Default cap on the estimated tokens in one tool response; a maxTokens argument overrides it.

What it does

GitNexus turns a code repository into a graph of symbols, references, call chains, clusters and execution flows, and gives a coding agent MCP tools, resources and prompts over that graph. The agent can search code by keyword and meaning, pull up everything about one symbol, see what a change would break before making it, trace the path between two functions, map changed git lines to affected flows, run Cypher queries and preview or apply a rename across files. Groups of indexed repositories can be synced to check API contracts across them.

You index a repository with `npx gitnexus analyze` from its root; the graph is stored locally in LadybugDB under `.gitnexus/`. `npx gitnexus setup` writes the MCP entry for the editors it finds (Claude Code, Cursor, Codex, Windsurf, OpenCode and others), and the server itself is started with `npx -y gitnexus@latest mcp` over stdio. Besides the MCP server, `analyze` installs agent skills, registers Claude Code hooks and writes AGENTS.md and CLAUDE.md files; a web UI backend (`gitnexus serve`) and opt-in local embeddings are also offered.

The released version 1.6.12 registers 17 tools in its source (`src/mcp/tools.ts`). The `read_file` and `grep` tools, a shared HTTP transport (`gitnexus mcp --http`, with a required auth token for non-loopback binds) and a `plan_token` step for applying renames appear in the main-branch README and 1.6.13 release candidates, not in 1.6.12. Not in the README: setting `GITNEXUS_MCP_READ_ONLY=1` hides `rename`, `cypher`, `group_list` and `group_sync` and refuses group routing (`src/mcp/read-only-policy.ts`).

The package is licensed PolyForm Noncommercial 1.0.0, which does not permit commercial use without other terms.

What it needs

RuntimeNode.js 22.18+
Runs onmacOS, Windows, Linux

Node must be ^22.18.0 or 24.11.0 and later (package engines). Each repository must be indexed with `npx gitnexus analyze` before the tools return anything. On npm 11, `npx` can crash during install; the README gives a `pnpm dlx` form instead. The install builds native tree-sitter grammars; set GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 to skip the optional ones on hosts without a C/C++ toolchain.

Limits

  • Cost PolyForm Noncommercial 1.0.0 licence: commercial use needs other terms from the maker.
  • Not covered Tools only see repositories you have indexed with `gitnexus analyze`; results go stale until you re-run it or use --watch.
  • Limit explain and pdg_query need an index built with the --pdg option.
  • Limit In 1.6.12 the MCP server speaks stdio only; the --http shared server in the main README is not yet released.
  • Limit read_file and grep tools and the plan_token rename step are on main and 1.6.13 release candidates, not in 1.6.12.
  • Early release The Icebug community-detection engine is marked experimental and not supported for production indexes.
  • Limit npx can crash during install on npm 11; the README suggests pnpm dlx, a global install or an npm downgrade.

Who it suits

Suits developers who want an agent to check callers, blast radius and execution flows before editing a codebase, and who are fine running a local Node process over a local index. Reads stay on your machine and a read-only switch removes the editing and raw-query tools. Pick something else for commercial work unless you get other licence terms, or if you need a hosted endpoint: 1.6.12 has none and no shared HTTP mode.

Tools 17

15 only read, 1 changes things, 1 can delete or overwrite. A ? marks an optional parameter.

list_repos
Lists the indexed repositories, one page at a time.limit?: integeroffset?: integer
query
Hybrid keyword and semantic search over the graph, with results grouped by execution flow.search_query: stringtask_context?: stringgoal?: stringlimit?: numbermax_symbols?: numberinclude_content?: booleanmaxTokens?: integerrepo?: stringservice?: string
context
Everything known about one symbol: callers, callees, references and the flows it takes part in.name?: stringuid?: stringfile_path?: stringfile?: stringkind?: stringinclude_content?: booleanmaxTokens?: integerrepo?: stringservice?: string
impact
Works out what a change to a function, class or file would affect, grouped by depth with a confidence for each hit.target?: stringdirection: stringtarget_uid?: stringmode?: stringline?: integerfile_path?: stringkind?: stringmaxDepth?: numberrelationTypes?: arrayincludeTests?: booleanminConfidence?: numberrepo?: stringlimit?: integeroffset?: integersummaryOnly?: booleanmaxTokens?: integertimeoutMs?: number
trace
Finds the shortest directed path of calls and member edges between two symbols.from?: stringfrom_uid?: stringfrom_file?: stringto?: stringto_uid?: stringto_file?: stringmaxDepth?: numberincludeTests?: booleanpdg?: boolean
detect_changes
Maps the lines changed in git (working tree or against a base ref) to the symbols and flows they touch.scope?: stringbase_ref?: stringworktree?: stringrepo?: string
check
Runs structural checks on the indexed graph, such as import cycles.cycles?: booleanrepo?: string
rename deletes
Renames a symbol across files using graph and text matches; only previews unless dry_run is false, then edits files in place.new_name: stringsymbol_name?: stringsymbol_uid?: stringfile_path?: stringdry_run?: booleanrepo?: string
cypher
Runs a Cypher query straight against the code graph.statement: stringparams?: objectrepo?: string
route_map
Shows API routes, their handlers and the components that call them.route?: stringrepo?: string
tool_map
Finds where MCP or RPC tools are defined and handled in the code.tool?: stringrepo?: string
shape_check
Compares an API's response shape with the properties its consumers read.route?: stringrepo?: string
api_impact
Reports what depends on an API route handler before you change it.route?: stringfile?: stringmethod?: stringrepo?: string
explain
Explains stored taint findings as source-to-sink flows (needs an index built with --pdg).target?: stringlimit?: integerrepo?: string
pdg_query
Asks statement-level control and data dependence questions (needs an index built with --pdg).mode: stringtarget: stringvariable?: stringlimit?: integerrepo?: string
group_list
Lists the configured repository groups, or one group by name.name?: string
group_sync changes
Rebuilds a group's contract registry and the links between its repositories.name: stringexactOnly?: boolean

Resources 10

gitnexus://repos
All indexed repositories.
gitnexus://setup
Setup and usage guidance for agents.
gitnexus://repo/{name}/context
Codebase statistics, index staleness and available tools.
gitnexus://repo/{name}/clusters
Functional clusters with cohesion scores.
gitnexus://repo/{name}/cluster/{name}
Members and details of one cluster.
gitnexus://repo/{name}/processes
All execution flows found in the repository.
gitnexus://repo/{name}/process/{name}
Step-by-step trace of one execution flow.
gitnexus://repo/{name}/schema
Graph schema to write Cypher queries against.
gitnexus://group/{name}/contracts
Contracts extracted for a group and their cross-repository links.
gitnexus://group/{name}/status
How stale each repository in a group is.

Prompts 2

detect_impact
Pre-commit review of a change: scope, affected flows and risk.
generate_map
Writes architecture documentation from the graph, with Mermaid diagrams.

Similar servers