+
+
+ 
+
+
+ 
+
+
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
-
-
-
-
-
+ The nervous system for agent context.
-Enterprise (SaaS & Self-hosted) - akonlabs.com
++ Indexes any codebase into a knowledge graph — every dependency, call chain, cluster, and execution flow — + then exposes it through smart MCP tools so AI agents never miss code. +
+ ++ 💬 Discord · + 🌐 Web UI · + 🏢 Enterprise (SaaS & self-hosted) +
-**Building nervous system for agent context.** - -Indexes any codebase into a knowledge graph — every dependency, call chain, cluster, and execution flow — then exposes it through smart tools so AI agents never miss code. - https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72 -> _Like DeepWiki, but deeper._ DeepWiki helps you _understand_ code. GitNexus lets you _analyze_ it — because a knowledge graph tracks every relationship, not just descriptions. +> _Like DeepWiki, but deeper._ DeepWiki helps you _understand_ code. GitNexus lets you _analyze_ it — a knowledge graph tracks every relationship, not just descriptions. -**TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, Antigravity, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with Goliath models. +**TL;DR:** The **CLI + MCP** makes your AI agent reliable — it gives Cursor, Claude Code, Antigravity, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity. The **Web UI** is a quick way to chat with any repo in the browser. ---- - -## Star History - -[](https://www.star-history.com/#abhigyanpatwari/GitNexus&type=date&legend=top-left) - -## Two Ways to Use GitNexus - -| | **CLI + MCP** | **Web UI** | -| ----------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- | -| **What** | Index repos locally, connect AI agents via MCP | Visual graph explorer + AI chat in browser | -| **For** | Daily development with Cursor, Claude Code, Antigravity, Codex, Windsurf, OpenCode | Quick exploration, demos, one-off analysis | -| **Scale** | Full repos, any size | Limited by browser memory (~5k files), or unlimited via backend mode | -| **Install** | `npm install -g gitnexus` | No install — [gitnexus.vercel.app](https://gitnexus.vercel.app) | -| **Storage** | LadybugDB native (fast, persistent) | LadybugDB WASM (in-memory, per session) | -| **Parsing** | Tree-sitter native bindings | Tree-sitter WASM | -| **Privacy** | Everything local, no network | Everything in-browser, no server | - -> **Bridge mode:** `gitnexus serve` connects the two — the web UI auto-detects the local server and can browse all your CLI-indexed repos without re-uploading or re-indexing. - ---- - -## Enterprise - -GitNexus is available as an **enterprise offering** - either as a fully managed **SaaS** or a **self-hosted** deployment. Also available for **commercial use** of the OSS version with proper licensing. - -Enterprise includes: - -- **PR Review** - automated blast radius analysis on pull requests -- **Auto-updating Code Wiki** - always up-to-date documentation (Code Wiki is also available in OSS) -- **Auto-reindexing** - knowledge graph stays fresh automatically -- **Multi-repo support** - unified graph across repositories -- **OCaml support** - additional language coverage -- **Priority feature/language support** - request new languages or features - -**Upcoming:** - -- Auto regression forensics -- End-to-end test generation - -👉 Learn more at [akonlabs.com](https://akonlabs.com) - -💬 For commercial licensing or enterprise inquiries, ping us on [Discord](https://discord.gg/AAsRVT6fGb) or drop an email at founders@akonlabs.com - ---- - -## Development - -- [ARCHITECTURE.md](ARCHITECTURE.md) — packages, index → graph → MCP flow, where to change code -- [RUNBOOK.md](RUNBOOK.md) — analyze, embeddings, stale index, MCP recovery, CI snippets -- [GUARDRAILS.md](GUARDRAILS.md) — safety rules and operational “Signs” for contributors and agents -- [CONTRIBUTING.md](CONTRIBUTING.md) — license, setup, commits, and pull requests -- [TESTING.md](TESTING.md) — test commands for `gitnexus` and `gitnexus-web` - -## CLI + MCP (recommended) - -The CLI indexes your repository and runs an MCP server that gives AI agents deep codebase awareness. - -### Quick Start +## Quick Start ```bash -# Index your repo (run from repo root) +# 1. Index your repo (run from repo root) npx gitnexus analyze + +# 2. Connect your editors (one-time, auto-detects Claude Code, Cursor, Codex, …) +npx gitnexus setup ``` -That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command. +That's it. `analyze` indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command. `setup` writes the MCP config so your AI agent can use the graph. + +gitnexus setup)# Search execution flows across all repos in a group -gitnexus group status# Check staleness of repos in a group +gitnexus uninstall # Preview removal of GitNexus MCP/skills/hooks (--force to apply) ``` -> **`gitnexus uninstall`** reverses `gitnexus setup` — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified **by bundled gitnexus skill name** (e.g. `gitnexus-cli/`), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass `--force` to apply. Per-repo indexes (`gitnexus clean --all`) and the global npm package (`npm uninstall -g gitnexus`) are left for you to remove. +You can also query the graph directly from the terminal — `gitnexus query`, `context`, `impact`, `trace`, `cypher`, `detect-changes`, and `check` mirror the MCP tools of the same names, and `gitnexus doctor` prints runtime platform capabilities. -If `analyze` reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use `gitnexus analyze --worker-timeout 60` or set `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000`. For very large files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget. - -#### Embeddings node limit - -`gitnexus analyze --embeddings` generates semantic search vectors with a default 50,000-node safety cap to protect memory on large repositories. Override the cap when you know the host has enough memory for a larger graph, or disable it entirely for a one-off full embeddings run. + ++ +All
```bash -# Generate embeddings with the default 50,000 node safety cap -gitnexus analyze --embeddings - -# Disable the safety cap entirely -gitnexus analyze --embeddings 0 - -# Use a custom cap -gitnexus analyze --embeddings 100000 +gitnexus analyze --force # Full rebuild: re-parse + graph rebuild + FTS rebuild +gitnexus analyze --repair-fts # Fast path: rebuild/verify only FTS indexes on existing index data +gitnexus analyze --skills # Generate repo-specific skill files from detected communities +gitnexus analyze --skip-embeddings # Skip embedding generation (faster) +gitnexus analyze --embeddings [limit] # Enable embedding generation (slower, better search) +gitnexus analyze --skip-agents-md # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits +gitnexus analyze --skip-skills # Skip installing .claude/skills/gitnexus/ skill files +gitnexus analyze --skip-git # Index folders that are not Git repositories +gitnexus analyze --default-branch develop # Branch used in the generated regression-compare example (base_ref) +gitnexus analyze --verbose # Log skipped files when parsers are unavailable +gitnexus analyze --worker-timeout 60 # Increase worker idle timeout for slow parses +gitnexus analyze --workersanalyzeflags# Parse worker pool size (>=1; default: cores-1, capped at 16, + # auto-sized to the repo). 0 is rejected — there is no sequential mode. +gitnexus analyze --wal-checkpoint-threshold 67108864 # LadybugDB WAL auto-checkpoint threshold in bytes + # (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB) ``` -If embeddings are skipped on a large repository, the indexed graph likely exceeds the default safety cap. Re-run with `gitnexus analyze --embeddings 0` to remove the cap, or `gitnexus analyze --embeddings ` to choose a higher limit while still keeping memory bounded. +If `analyze` reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use `--worker-timeout 60` or set `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000`. For very large files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget. -#### Project config (`.gitnexusrc`) +**Embeddings node limit** — `gitnexus analyze --embeddings` generates semantic search vectors with a default 50,000-node safety cap to protect memory on large repositories: + +```bash +gitnexus analyze --embeddings # default 50,000 node safety cap +gitnexus analyze --embeddings 0 # disable the cap entirely +gitnexus analyze --embeddings 100000 # custom cap +``` + +If embeddings are skipped on a large repository, the indexed graph likely exceeds the default cap — re-run with `--embeddings 0` or a higher limit. + + ++ +Repository groups (multi-repo / monorepo service tracking)
+ +```bash +gitnexus group create# Create a repository group +gitnexus group add # Add a repo. is a hierarchy path + # (e.g. hr/hiring/backend); is the + # repo's name from the registry (see `gitnexus list`) +gitnexus group remove # Remove a repo by its hierarchy path +gitnexus group list [name] # List groups, or show one group's config +gitnexus group sync # Extract contracts and match across repos/services +gitnexus group contracts # Inspect extracted contracts and cross-links +gitnexus group query # Check staleness of repos in a group +gitnexus group impact --target --repo # Cross-repo blast radius +``` + + ++ +Project config (
Commit a `.gitnexusrc` JSON file at the repo root to preconfigure recurring `analyze` options per project, instead of re-passing the same flags every run. It is read from the resolved repo root (not `.gitnexus/`, which is gitignored index storage). **CLI flags always override `.gitnexusrc`.** @@ -314,7 +381,10 @@ Notes: - Supported keys: `defaultBranch` (`branch`), `skipAgentsMd` (`skipContextFiles`, `skipAiContext`), `skipSkills`, `indexOnly`, `stats`/`noStats`, `embeddings`, `dropEmbeddings`, `name`, `allowDuplicateName`, `maxFileSize`, `workerTimeout`, `walCheckpointThreshold`, `workers`, `embeddingThreads`, `embeddingBatchSize`, `embeddingSubBatchSize`, `embeddingDevice`. - The file is JSON only. Unknown keys and invalid values fail fast with an actionable error before analysis starts. -#### Environment variables +.gitnexusrc)++ +Environment variables
Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max-file-size`, `--verbose`). Use the env-var form when you'd otherwise repeat the same flag every run, or when invoking GitNexus from a long-running host (MCP server, eval-server, CI shell) that already manages its own environment. CLI flags take precedence over env vars; env vars take precedence over built-in defaults. @@ -338,69 +408,67 @@ Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max | `GITNEXUS_NO_GITIGNORE` | unset | When set, skips `.gitignore` parsing. `.gitnexusignore` is still honored. | Indexing a repo whose `.gitignore` excludes files you actually want indexed (e.g., generated code committed for cross-repo lookup). | | `GITNEXUS_SKIP_OPTIONAL_GRAMMARS` | unset | When `=1` strictly, skips the vendored grammar materialize for `tree-sitter-dart`, `tree-sitter-proto`, `tree-sitter-swift`, and `tree-sitter-kotlin` at install time (and the Dart/Proto source builds). Those four won't be parsed; the install still succeeds. | Installing on a host without a C++ toolchain or where the vendored prebuilds don't match; willing to skip Dart/Proto/Swift/Kotlin parsing. | -#### Publishing to understand-quickly (opt-in) +++ ++ +`gitnexus uninstall` reverses `gitnexus setup` — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified **by bundled gitnexus skill name** (e.g. `gitnexus-cli/`), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass `--force` to apply. Per-repo indexes (`gitnexus clean --all`) and the global npm package (`npm uninstall -g gitnexus`) are left for you to remove. + +
gitnexus uninstall+-**16 tools** exposed via MCP (11 per-repo + 5 group): +## How It Works -| Tool | What It Does | `repo` Param | -| ----------------- | ---------------------------------------------------------------- | ------------ | -| `list_repos` | Discover all indexed repositories (paginated — `limit`/`offset`) | — | -| `query` | Process-grouped hybrid search (BM25 + semantic + RRF) | Optional | -| `context` | 360-degree symbol view — categorized refs, process participation | Optional | -| `impact` | Blast radius analysis with depth grouping and confidence | Optional | -| `detect_changes` | Git-diff impact — maps changed lines to affected processes | Optional | -| `rename` | Multi-file coordinated rename with graph + text search | Optional | -| `cypher` | Raw Cypher graph queries | Optional | -| `group_list` | List configured repository groups | — | -| `group_sync` | Extract contracts and match across repos/services | — | -| `group_contracts` | Inspect extracted contracts and cross-links | — | -| `group_query` | Search execution flows across all repos in a group | — | -| `group_status` | Check staleness of repos in a group | — | +GitNexus builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline: -> When only one repo is indexed, the `repo` parameter is optional. With multiple repos, specify which one: `query({search_query: "auth", repo: "my-app"})`. +1. **Structure** — walks the file tree and maps folder/file relationships +2. **Parsing** — extracts functions, classes, methods, and interfaces using Tree-sitter ASTs +3. **Resolution** — resolves imports, function calls, heritage, constructor inference, and `self`/`this` receiver types across files with language-aware logic +4. **Clustering** — groups related symbols into functional communities +5. **Processes** — traces execution flows from entry points through call chains +6. **Search** — builds hybrid search indexes for fast retrieval -**Resources** for instant context: +### Supported Languages -| Resource | Purpose | -| --------------------------------------- | ---------------------------------------------------- | -| `gitnexus://repos` | List all indexed repositories (read this first) | -| `gitnexus://repo/{name}/context` | Codebase stats, staleness check, and available tools | -| `gitnexus://repo/{name}/clusters` | All functional clusters with cohesion scores | -| `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details | -| `gitnexus://repo/{name}/processes` | All execution flows | -| `gitnexus://repo/{name}/process/{name}` | Full process trace with steps | -| `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries | +| Language | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points | +| ---------- | ------- | -------------- | ------- | -------- | ---------------- | --------------------- | ------ | ---------- | ------------ | +| TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| JavaScript | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | +| Python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Java | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | +| Kotlin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | +| C# | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Go | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Rust | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | +| PHP | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | +| Ruby | ✓ | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ | +| Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ | +| C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | +| Dart | ✓ | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | -**2 MCP prompts** for guided workflows: +**Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics -| Prompt | What It Does | -| --------------- | ------------------------------------------------------------------------- | -| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level | -| `generate_map` | Architecture documentation from the knowledge graph with mermaid diagrams | +**Control flow (CFG, opt-in `--pdg`)** — per-function control-flow graphs (`BasicBlock` nodes + `CFG` edges) feeding the PDG/taint substrate, currently **TypeScript & JavaScript** (#2081 M1); other languages planned. Off by default. -**4 agent skills** installed to `.claude/skills/` automatically: - -- **Exploring** — Navigate unfamiliar code using the knowledge graph -- **Debugging** — Trace bugs through call chains -- **Impact Analysis** — Analyze blast radius before changes -- **Refactoring** — Plan safe refactors using dependency mapping - -**Repo-specific skills** generated with `--skills`: - -When you run `gitnexus analyze --skills`, GitNexus detects the functional areas of your codebase (via Leiden community detection) and generates a `SKILL.md` file for each one under `.claude/skills/generated/`. Each skill describes a module's key files, entry points, execution flows, and cross-area connections — so your AI agent gets targeted context for the exact area of code you're working in. Skills are regenerated on each `--skills` run to stay current with the codebase. - ---- - -## Multi-Repo MCP Architecture +### Multi-Repo Architecture GitNexus uses a **global registry** so one MCP server can serve multiple indexed repos. No per-project MCP config needed — set it up once and it works everywhere. +Each `gitnexus analyze` stores the index in `.gitnexus/` inside the repo (portable, gitignored) and registers a pointer in `~/.gitnexus/registry.json`. When an AI agent starts, the MCP server reads the registry and can serve any indexed repo. LadybugDB connections are opened lazily on first query and evicted after 5 minutes of inactivity (max 5 concurrent). If only one repo is indexed, the `repo` parameter is optional on all tools — agents don't need to change anything. + +Publishing to understand-quickly (opt-in)
[`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly) is a public registry of code-knowledge graphs that lists `gitnexus@1` as a first-class format. After registering your repo once (`npx @understand-quickly/cli add` or the [wizard](https://looptech-ai.github.io/understand-quickly/add.html)), `gitnexus publish` fires a single `repository_dispatch` event so the registry resyncs your entry on demand instead of waiting for the nightly job. It is opt-in and a no-op without `UNDERSTAND_QUICKLY_TOKEN` — a fine-grained GitHub PAT with `Repository dispatches: write` on the registry repo. Nothing else happens; no graph file is uploaded. See the [protocol spec](https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md) for the full contract. -### What Your AI Agent Gets ++## Tool Examples @@ -738,6 +539,9 @@ gitnexus impact get_embeddings --file src/embed.py # → resolves to the one i gitnexus impact get_embeddings --uid "Function:src/embed.py:get_embeddings" # exact ``` +Architecture diagram
+ ```mermaid flowchart TD subgraph CLI [CLI Commands] @@ -441,274 +509,7 @@ flowchart TD ConnB -->|"queries"| RepoB ``` -**How it works:** Each `gitnexus analyze` stores the index in `.gitnexus/` inside the repo (portable, gitignored) and registers a pointer in `~/.gitnexus/registry.json`. When an AI agent starts, the MCP server reads the registry and can serve any indexed repo. LadybugDB connections are opened lazily on first query and evicted after 5 minutes of inactivity (max 5 concurrent). If only one repo is indexed, the `repo` parameter is optional on all tools — agents don't need to change anything. - ---- - -## Web UI (browser-based) - -A client-side graph explorer and AI chat — your code never leaves your machine. - -**Try it now:** [gitnexus.vercel.app](https://gitnexus.vercel.app) — run `npx gitnexus@latest serve` locally and the page auto-connects to your local backend. - -- -Or run the frontend locally: - -```bash -git clone https://github.com/abhigyanpatwari/gitnexus.git -cd gitnexus/gitnexus-shared && npm install && npm run build -cd ../gitnexus-web && npm install -npm run dev -# Then in another terminal, start the backend the frontend connects to: -npx gitnexus@latest serve -``` - -## Docker - -The official Docker setup ships **two signed images** orchestrated by `docker-compose.yaml`. Each image is published to both **GitHub Container Registry** (GHCR) and **Docker Hub** — same build, same digest, same Cosign signature — so pick whichever registry you prefer: - -| Purpose | GHCR (default in `docker-compose.yaml`) | Docker Hub mirror | -| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------ | -| CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) | `ghcr.io/abhigyanpatwari/gitnexus:latest` | `akonlabs/gitnexus:latest` | -| Static web UI (port `4173`) | `ghcr.io/abhigyanpatwari/gitnexus-web:latest` | `akonlabs/gitnexus-web:latest` | - -> **Heads-up — image rename.** Earlier releases published the web UI under -> `ghcr.io/abhigyanpatwari/gitnexus`. Starting with the introduction of the -> bundled backend, that slug now hosts the CLI/server image and the UI moved -> to `ghcr.io/abhigyanpatwari/gitnexus-web`. The previous tags remain -> available for pulling, but new versions are only published under the new -> slugs. Update your `docker run` / compose files accordingly (or just adopt -> the bundled compose). - -### One-command setup - -```bash -docker compose up -d -``` - -This starts the server on `http://localhost:4747` and the web UI on -`http://localhost:4173`. The UI auto-detects the server because the browser -runs on the host and reaches the container via the mapped port. - -A named volume (`gitnexus-data`) persists the global registry, indexes, and -cloned repos at `/data/gitnexus` inside the server container. To make repos on -your host machine indexable, set `WORKSPACE_DIR` before bringing the stack up: - -```bash -WORKSPACE_DIR=$HOME/code docker compose up -d -# Inside the server container the directory is mounted read-only at /workspace. -docker compose exec gitnexus-server gitnexus index /workspace/my-repo -``` - -### Direct `docker run` - -```bash -# Server -docker run --rm -d \ - --name gitnexus-server \ - -p 4747:4747 \ - -v gitnexus-data:/data/gitnexus \ - ghcr.io/abhigyanpatwari/gitnexus:latest - -# Web UI -docker run --rm -d \ - --name gitnexus-web \ - -p 4173:4173 \ - ghcr.io/abhigyanpatwari/gitnexus-web:latest -``` - -Optional env file (override image tags, container names, ports, workspace dir): - -```bash -cp .env.example .env -docker compose --env-file .env up -d -``` - -### Versioning & supply-chain protection - -The Docker images are version-locked to the npm package: - -- Stable images are **only published from `vX.Y.Z` git tags** (via `docker.yml` - triggered directly by the tag push), and the workflow refuses to build unless - the tag exactly matches `gitnexus/package.json`'s version. So - `ghcr.io/abhigyanpatwari/gitnexus:1.6.2` (and its Docker Hub mirror - `akonlabs/gitnexus:1.6.2`) is byte-for-byte the same release as - `npm install gitnexus@1.6.2` — no drift, no floating builds from `main`. - Both registries receive the same digest from a single build step, so you can - pull from either and the signature verifies identically. -- Release-candidate images (e.g. `:1.7.0-rc.1`) are published alongside each - RC npm release. They are built by `publish.yml` calling `docker.yml` - as a reusable workflow after the RC tag is created and pushed. -- `:latest` is auto-promoted only from non-prerelease tags by the Docker - metadata action, so it always points at a real, npm-published version. - -Both images are signed with [Cosign keyless signing][cosign-keyless] using the -workflow's GitHub OIDC identity, and shipped with build provenance and SBOM -attestations. **This is your protection against supply-chain attacks**: even if -an attacker republishes a same-named image elsewhere (or somehow pushes to a -typo-squatted registry), they cannot forge a Cosign signature tied to -`abhigyanpatwari/GitNexus`'s `docker.yml`. Always verify before pulling into -sensitive environments: - -**Stable releases** — signed from the `v*` tag ref: - -```bash -cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \ - --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \ - --certificate-oidc-issuer https://token.actions.githubusercontent.com - -# Same signature verifies the Docker Hub mirror (identical digest): -cosign verify docker.io/akonlabs/gitnexus:1.6.2 \ - --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \ - --certificate-oidc-issuer https://token.actions.githubusercontent.com -``` - -The regex pins the certificate identity to this repo's `docker.yml` workflow -**run from a `v*` tag** — rejecting unsigned images, images signed by other -workflows, and images signed from unprotected refs. It is identical for both -registries because both sets of tags were signed at the same digest in one -workflow run. - -**Release candidates** — signed from `refs/heads/main` (the caller's ref when -`publish.yml` invokes `docker.yml` as a reusable workflow): - -```bash -cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \ - --certificate-identity 'https://github.com/abhigyanpatwari/GitNexus/.github/workflows/docker.yml@refs/heads/main' \ - --certificate-oidc-issuer https://token.actions.githubusercontent.com -``` - -You can also inspect the build provenance and SBOM: - -```bash -cosign download attestation ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \ - --predicate-type https://slsa.dev/provenance/v1 -``` - -#### Kubernetes: enforce signatures at admission - -For Kubernetes deployments, ship the bundled -[`ClusterImagePolicy`](deploy/kubernetes/cluster-image-policy.yaml) so the -[Sigstore policy-controller][policy-controller] rejects any GitNexus pod whose -image is not signed by this repo's `docker.yml` running from a `vX.Y.Z` tag — -the same identity the `cosign verify` snippet above pins. - -```bash -# 1. Install the controller (one-time, cluster-wide) -helm repo add sigstore https://sigstore.github.io/helm-charts && helm repo update -helm install policy-controller -n cosign-system --create-namespace \ - sigstore/policy-controller - -# 2. Opt your namespace in -kubectl label namespace
policy.sigstore.dev/include=true - -# 3. Apply the policy -kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml -``` - -After this, attempting to deploy an unsigned image — or one signed by anything -other than `abhigyanpatwari/GitNexus`'s `docker.yml` at a `v*` tag — fails the -admission webhook before a pod is ever created. This turns the verifiable -signature into an enforced policy, which is the supply-chain control most -clusters actually need. - -[cosign-keyless]: https://docs.sigstore.dev/cosign/signing/overview/ -[policy-controller]: https://docs.sigstore.dev/policy-controller/overview/ - -### Files - -- [Dockerfile.web](Dockerfile.web) — builds `gitnexus-shared` and `gitnexus-web`, then serves the production frontend. -- [Dockerfile.cli](Dockerfile.cli) — builds the CLI/server (with its native deps) and runs `gitnexus serve --host 0.0.0.0`. -- [docker-compose.yaml](docker-compose.yaml) — starts both signed images side by side. -- [.env.example](.env.example) — overrides for image names, container names, ports, and the workspace mount. - -The web UI uses the same indexing pipeline as the CLI but runs entirely in WebAssembly (Tree-sitter WASM, LadybugDB WASM, in-browser embeddings). It's great for quick exploration but limited by browser memory for larger repos. - -**Local Backend Mode:** Run `gitnexus serve` and open the web UI locally — it auto-detects the server and shows all your indexed repos, with full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically. - ---- - -## The Problem GitNexus Solves - -Tools like **Cursor**, **Claude Code**, **Codex**, **Cline**, **Roo Code**, and **Windsurf** are powerful — but they don't truly know your codebase structure. - -**What happens:** - -1. AI edits `UserService.validate()` -2. Doesn't know 47 functions depend on its return type -3. **Breaking changes ship** - -### Traditional Graph RAG vs GitNexus - -Traditional approaches give the LLM raw graph edges and hope it explores enough. GitNexus **precomputes structure at index time** — clustering, tracing, scoring — so tools return complete context in one call: - -```mermaid -flowchart TB - subgraph Traditional["Traditional Graph RAG"] - direction TB - U1["User: What depends on UserService?"] - U1 --> LLM1["LLM receives raw graph"] - LLM1 --> Q1["Query 1: Find callers"] - Q1 --> Q2["Query 2: What files?"] - Q2 --> Q3["Query 3: Filter tests?"] - Q3 --> Q4["Query 4: High-risk?"] - Q4 --> OUT1["Answer after 4+ queries"] - end - - subgraph GN["GitNexus Smart Tools"] - direction TB - U2["User: What depends on UserService?"] - U2 --> TOOL["impact UserService upstream"] - TOOL --> PRECOMP["Pre-structured response: - 8 callers, 3 clusters, all 90%+ confidence"] - PRECOMP --> OUT2["Complete answer, 1 query"] - end -``` - -**Core innovation: Precomputed Relational Intelligence** - -- **Reliability** — LLM can't miss context, it's already in the tool response -- **Token efficiency** — No 10-query chains to understand one function -- **Model democratization** — Smaller LLMs work because tools do the heavy lifting - ---- - -## How It Works - -GitNexus builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline: - -1. **Structure** — Walks the file tree and maps folder/file relationships -2. **Parsing** — Extracts functions, classes, methods, and interfaces using Tree-sitter ASTs -3. **Resolution** — Resolves imports, function calls, heritage, constructor inference, and `self`/`this` receiver types across files with language-aware logic -4. **Clustering** — Groups related symbols into functional communities -5. **Processes** — Traces execution flows from entry points through call chains -6. **Search** — Builds hybrid search indexes for fast retrieval - -### Supported Languages - -| Language | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points | -| ---------- | ------- | -------------- | ------- | -------- | ---------------- | --------------------- | ------ | ---------- | ------------ | -| TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| JavaScript | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | -| Python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Java | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | -| Kotlin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | -| C# | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Go | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Rust | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | -| PHP | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | -| Ruby | ✓ | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ | -| Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ | -| C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | -| Dart | ✓ | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | - -**Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics - -**Control flow (CFG, opt-in `--pdg`)** — per-function control-flow graphs (`BasicBlock` nodes + `CFG` edges) feeding the PDG/taint substrate, currently **TypeScript & JavaScript** (#2081 M1); other languages planned. Off by default. - ---- + +## Wiki Generation @@ -835,25 +639,224 @@ Generate LLM-powered documentation from your knowledge graph: # Requires an LLM API key (OPENAI_API_KEY, etc.) gitnexus wiki -# Use a custom model or provider +# Use a custom model or provider (default model: minimax/minimax-m2.5) gitnexus wiki --model gpt-4o gitnexus wiki --base-url https://api.anthropic.com/v1 # Force full regeneration gitnexus wiki --force +# Increase the timeout or retries for large codebases or slow LLM providers +gitnexus wiki --timeoutMore examples: search · context · detect_changes · rename · Cypher
+ ### Process-Grouped Search ``` @@ -825,7 +629,7 @@ RETURN caller.name, fn.name, r.confidence ORDER BY r.confidence DESC ``` ---- +# LLM request timeout in seconds (default: disabled) +gitnexus wiki --retries # Max LLM retry attempts per request (default: 3) -# Increase the timeout or retries for large codebase or slow LLM providers -gitnexus wiki --timeout # LLM request timeout in seconds (default: disabled) -gitnexus wiki --retries # Max LLM retry attempts per request (default: 3) - -# Change the language generation for wiki -gitnexus wiki --lang # Output language for generated documentation (e.g. english, chinese, spanish, japanese) +# Change the output language +gitnexus wiki --lang # e.g. english, chinese, spanish, japanese ``` The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph. ---- +## Web UI (browser-based) + +A client-side graph explorer and AI chat — your code never leaves your machine. + +**Try it now:** [gitnexus.vercel.app](https://gitnexus.vercel.app) — run `npx gitnexus@latest serve` locally and the page auto-connects to your local backend. + + ++ +## Docker + +```bash +docker compose up -d +``` + +This starts the server on `http://localhost:4747` and the web UI on `http://localhost:4173`. The UI auto-detects the server because the browser runs on the host and reaches the container via the mapped port. + +The official setup ships **two signed images**, published identically to **GitHub Container Registry** (GHCR) and **Docker Hub** — same build, same digest, same Cosign signature: + +| Purpose | GHCR (default in `docker-compose.yaml`) | Docker Hub mirror | +| ----------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------- | +| CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) | `ghcr.io/abhigyanpatwari/gitnexus:latest` | `akonlabs/gitnexus:latest` | +| Static web UI (port `4173`) | `ghcr.io/abhigyanpatwari/gitnexus-web:latest` | `akonlabs/gitnexus-web:latest` | + +A named volume (`gitnexus-data`) persists the global registry, indexes, and cloned repos at `/data/gitnexus` inside the server container. To make repos on your host machine indexable, set `WORKSPACE_DIR` before bringing the stack up: + +```bash +WORKSPACE_DIR=$HOME/code docker compose up -d +# Inside the server container the directory is mounted read-only at /workspace. +docker compose exec gitnexus-server gitnexus index /workspace/my-repo +``` + +> **Heads-up — image rename.** Earlier releases published the web UI under `ghcr.io/abhigyanpatwari/gitnexus`. That slug now hosts the CLI/server image and the UI moved to `ghcr.io/abhigyanpatwari/gitnexus-web`. Previous tags remain pullable, but new versions are only published under the new slugs — update your `docker run` / compose files (or just adopt the bundled compose). + +Run the frontend locally
+ +```bash +git clone https://github.com/abhigyanpatwari/gitnexus.git +cd gitnexus/gitnexus-shared && npm install && npm run build +cd ../gitnexus-web && npm install +npm run dev +# Then in another terminal, start the backend the frontend connects to: +npx gitnexus@latest serve +``` + +++ +Direct
+ +```bash +# Server +docker run --rm -d \ + --name gitnexus-server \ + -p 4747:4747 \ + -v gitnexus-data:/data/gitnexus \ + ghcr.io/abhigyanpatwari/gitnexus:latest + +# Web UI +docker run --rm -d \ + --name gitnexus-web \ + -p 4173:4173 \ + ghcr.io/abhigyanpatwari/gitnexus-web:latest +``` + +Optional env file (override image tags, container names, ports, workspace dir): + +```bash +cp .env.example .env +docker compose --env-file .env up -d +``` + +Files: + +- [Dockerfile.web](Dockerfile.web) — builds `gitnexus-shared` and `gitnexus-web`, then serves the production frontend. +- [Dockerfile.cli](Dockerfile.cli) — builds the CLI/server (with its native deps) and runs `gitnexus serve --host 0.0.0.0`. +- [docker-compose.yaml](docker-compose.yaml) — starts both signed images side by side. +- [.env.example](.env.example) — overrides for image names, container names, ports, and the workspace mount. + +docker run& env file++ +## Enterprise + +GitNexus is available as an **enterprise offering** — fully managed **SaaS** or **self-hosted** deployment. Commercial use of the OSS version is also available with proper licensing. + +Enterprise includes: + +- **PR Review** — automated blast radius analysis on pull requests +- **Auto-updating Code Wiki** — always up-to-date documentation (Code Wiki is also available in OSS) +- **Auto-reindexing** — knowledge graph stays fresh automatically +- **Multi-repo support** — unified graph across repositories +- **OCaml support** — additional language coverage +- **Priority feature/language support** — request new languages or features + +**Upcoming:** auto regression forensics · end-to-end test generation + +👉 Learn more at [akonlabs.com](https://akonlabs.com) — for commercial licensing or enterprise inquiries, ping us on [Discord](https://discord.gg/AAsRVT6fGb) or email founders@akonlabs.com + +## Community Integrations + +Built by the community — not officially maintained, but worth checking out. + +| Project | Author | Description | +| ------------------------------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------ | +| [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus) | [@tintinweb](https://github.com/tintinweb) | GitNexus plugin for [pi](https://pi.dev) — `pi install npm:pi-gitnexus` | +| [gitnexus-stable-ops](https://github.com/ShunsukeHayashi/gitnexus-stable-ops) | [@ShunsukeHayashi](https://github.com/ShunsukeHayashi) | Stable ops & deployment workflows (Miyabi ecosystem) | +| [KiloCode MCP workflow](Documentation/kilo-code-mcp.md) | [@oktanishq](https://github.com/oktanishq) | Guide to connect GitNexus MCP to Kilo Code and verify tools. | + +> Have a project built on GitNexus? Open a PR to add it here! + +## Roadmap + +**Actively building:** + +- [ ] **LLM Cluster Enrichment** — semantic cluster names via LLM API +- [ ] **AST Decorator Detection** — parse @Controller, @Get, etc. +- [ ] **Incremental Indexing** — only re-index changed files + +**Recently completed:** + +- [x] Constructor-Inferred Type Resolution, `self`/`this` Receiver Mapping +- [x] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis +- [x] Process-Grouped Search, 360-Degree Context, Claude Code Hooks +- [x] Multi-Repo MCP, Zero-Config Setup, 14 Language Support +- [x] Community Detection, Process Detection, Confidence Scoring +- [x] Hybrid Search, Vector Index + +## Development + +- [ARCHITECTURE.md](ARCHITECTURE.md) — packages, index → graph → MCP flow, where to change code +- [RUNBOOK.md](RUNBOOK.md) — analyze, embeddings, stale index, MCP recovery, CI snippets +- [GUARDRAILS.md](GUARDRAILS.md) — safety rules and operational "Signs" for contributors and agents +- [CONTRIBUTING.md](CONTRIBUTING.md) — license, setup, commits, and pull requests +- [TESTING.md](TESTING.md) — test commands for `gitnexus` and `gitnexus-web` ## Tech Stack @@ -870,40 +873,21 @@ The wiki generator reads the indexed graph structure, groups files into modules | **Clustering** | Graphology | Graphology | | **Concurrency** | Worker threads + async | Web Workers + Comlink | ---- - -## Roadmap - -### Actively Building - -- [ ] **LLM Cluster Enrichment** — Semantic cluster names via LLM API -- [ ] **AST Decorator Detection** — Parse @Controller, @Get, etc. -- [ ] **Incremental Indexing** — Only re-index changed files - -### Recently Completed - -- [x] Constructor-Inferred Type Resolution, `self`/`this` Receiver Mapping -- [x] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis -- [x] Process-Grouped Search, 360-Degree Context, Claude Code Hooks -- [x] Multi-Repo MCP, Zero-Config Setup, 14 Language Support -- [x] Community Detection, Process Detection, Confidence Scoring -- [x] Hybrid Search, Vector Index - ---- - ## Security & Privacy -- **CLI**: Everything runs locally on your machine. No network calls. Index stored in `.gitnexus/` (gitignored). Global registry at `~/.gitnexus/` stores only paths and metadata. -- **Web**: Everything runs in your browser. No code uploaded to any server. API keys stored in localStorage only. +- **CLI**: everything runs locally on your machine. No network calls. Index stored in `.gitnexus/` (gitignored). Global registry at `~/.gitnexus/` stores only paths and metadata. +- **Web**: everything runs in your browser. No code uploaded to any server. API keys stored in localStorage only. - Open source — audit the code yourself. ---- +## Star History + +[](https://www.star-history.com/#abhigyanpatwari/GitNexus&type=date&legend=top-left) ## Acknowledgments - [Tree-sitter](https://tree-sitter.github.io/) — AST parsing -- [LadybugDB](https://ladybugdb.com/) — Embedded graph database with vector support (formerly KuzuDB) +- [LadybugDB](https://ladybugdb.com/) — embedded graph database with vector support (formerly KuzuDB) - [Sigma.js](https://www.sigmajs.org/) — WebGL graph rendering -- [transformers.js](https://huggingface.co/docs/transformers.js) — Browser ML -- [Graphology](https://graphology.github.io/) — Graph data structures +- [transformers.js](https://huggingface.co/docs/transformers.js) — browser ML +- [Graphology](https://graphology.github.io/) — graph data structures - [MCP](https://modelcontextprotocol.io/) — Model Context Protocol diff --git a/eval/README.md b/eval/README.md index 1b01bce59..92e45e180 100644 --- a/eval/README.md +++ b/eval/README.md @@ -16,18 +16,19 @@ Evaluate whether GitNexus code intelligence improves AI agent performance on rea > **Recommended**: Use `native_augment` mode. It mirrors the Claude Code model — the agent gets both explicit GitNexus tools (fast bash commands) AND automatic enrichment of grep results with callers, callees, and execution flows. The agent decides when to use explicit tools vs rely on enriched search output. -**Models supported:** +**Models supported** (see `configs/models/` for the current list): -- Claude 3.5 Haiku, Claude Sonnet 4, Claude Opus 4 -- MiniMax M1 2.5 +- Claude Haiku 4.5, Claude Sonnet 4, Claude Opus 4 +- MiniMax M1 2.5, MiniMax M2.5 - GLM 4.7, GLM 5 +- DeepSeek - Any model supported by litellm (add a YAML config) ## Prerequisites - Python 3.11+ - Docker (for SWE-bench containers) -- Node.js 18+ (for GitNexus) +- Node.js 22+ (for GitNexus) - API keys for your chosen models ## Setup diff --git a/gitnexus-cursor-integration/README.md b/gitnexus-cursor-integration/README.md index 948757eca..c7e4c5f93 100644 --- a/gitnexus-cursor-integration/README.md +++ b/gitnexus-cursor-integration/README.md @@ -8,8 +8,8 @@ Static config that adds GitNexus knowledge-graph augmentation and skill files to | Layer | What it does | How it's installed | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| **MCP** | `gitnexus` MCP server with 16 tools (`query`, `context`, `impact`, `detect_changes`, `rename`, …) | `npx gitnexus setup` writes `~/.cursor/mcp.json` automatically. | -| **Skills** | `/gitnexus-exploring`, `/gitnexus-debugging`, `/gitnexus-impact-analysis`, `/gitnexus-refactoring`, `/gitnexus-pr-review` markdown skills | `npx gitnexus setup` copies them to `~/.cursor/skills/gitnexus/`. | +| **MCP** | `gitnexus` MCP server with 17 tools (`query`, `context`, `impact`, `detect_changes`, `rename`, …) | `npx gitnexus setup` writes `~/.cursor/mcp.json` automatically. | +| **Skills** | All bundled markdown skills (`/gitnexus-exploring`, `/gitnexus-debugging`, `/gitnexus-impact-analysis`, `/gitnexus-refactoring`, `/gitnexus-guide`, `/gitnexus-cli`, `/gitnexus-pr-review`, `/gitnexus-pdg-query`, `/gitnexus-taint-analysis`) | `npx gitnexus setup` copies them to `~/.cursor/skills/gitnexus/`. | | **Hooks** _(this README)_ | `postToolUse` hook that enriches `Shell` / `Read` / `Grep` tool calls with graph context — same augmentation Claude Code gets | **Manual** — copy the files described below into your project's `.cursor/`. | ## Hook install diff --git a/gitnexus/README.md b/gitnexus/README.md index 2919fb719..f2fa459a3 100644 --- a/gitnexus/README.md +++ b/gitnexus/README.md @@ -40,14 +40,14 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up | Editor | MCP | Skills | Hooks (auto-augment) | Support | | ------------------------ | --- | ------ | ------------------------------------------------------------------------------------------ | ------------ | -| **Claude Code** | Yes | Yes | Yes (PreToolUse) | **Full** | +| **Claude Code** | Yes | Yes | Yes (PreToolUse + PostToolUse) | **Full** | | **Cursor** | Yes | Yes | Yes (postToolUse, [manual install](../gitnexus-cursor-integration/README.md#hook-install)) | **Full** | | **Antigravity** (Google) | Yes | Yes | Yes (AfterTool, [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/)) | **Full** | | **Codex** | Yes | Yes | — | MCP + Skills | -| **Windsurf** | Yes | — | — | MCP | | **OpenCode** | Yes | Yes | — | MCP + Skills | +| **Windsurf** | Yes | — | — | MCP | -> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context. +> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex. ### Community Integrations @@ -122,31 +122,44 @@ The result is a **LadybugDB graph database** stored locally in `.gitnexus/` with ## MCP Tools -Your AI agent gets these tools automatically: +Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically: -| Tool | What It Does | `repo` Param | -| ---------------- | ---------------------------------------------------------------- | ------------ | -| `list_repos` | Discover all indexed repositories (paginated — `limit`/`offset`) | — | -| `query` | Process-grouped hybrid search (BM25 + semantic + RRF) | Optional | -| `context` | 360-degree symbol view — categorized refs, process participation | Optional | -| `impact` | Blast radius analysis with depth grouping and confidence | Optional | -| `detect_changes` | Git-diff impact — maps changed lines to affected processes | Optional | -| `rename` | Multi-file coordinated rename with graph + text search | Optional | -| `cypher` | Raw Cypher graph queries | Optional | +| Tool | What It Does | +| ---------------- | ----------------------------------------------------------------------- | +| `list_repos` | Discover all indexed repositories (paginated — `limit`/`offset`) | +| `query` | Process-grouped hybrid search (BM25 + semantic + RRF) | +| `context` | 360-degree symbol view — categorized refs, process participation | +| `impact` | Blast radius analysis with depth grouping and confidence | +| `trace` | Shortest directed path between two symbols (call + class-member edges) | +| `detect_changes` | Git-diff impact — maps changed lines to affected processes | +| `check` | Read-only structural checks against the indexed graph | +| `rename` | Multi-file coordinated rename with graph + text search | +| `cypher` | Raw Cypher graph queries | +| `route_map` | API route map — which components fetch which endpoints, and handlers | +| `tool_map` | MCP/RPC tool definitions — where they're defined and handled | +| `shape_check` | Validate API response shapes against consumers' property accesses | +| `api_impact` | Pre-change impact report for an API route handler | +| `explain` | Explain persisted taint findings (source→sink flows, `--pdg` indexes) | +| `pdg_query` | Query control/data dependence at statement level (`--pdg` indexes) | +| `group_list` | List configured repository groups | +| `group_sync` | Rebuild a group's Contract Registry and cross-repo links | -> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`. +> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for multi-branch indexes. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`. ## MCP Resources | Resource | Purpose | | --------------------------------------- | ---------------------------------------------------- | | `gitnexus://repos` | List all indexed repositories (read first) | +| `gitnexus://setup` | Setup and usage guidance for agents | | `gitnexus://repo/{name}/context` | Codebase stats, staleness check, and available tools | | `gitnexus://repo/{name}/clusters` | All functional clusters with cohesion scores | | `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details | | `gitnexus://repo/{name}/processes` | All execution flows | | `gitnexus://repo/{name}/process/{name}` | Full process trace with steps | | `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries | +| `gitnexus://group/{name}/contracts` | A group's extracted contracts and cross-links | +| `gitnexus://group/{name}/status` | Staleness of repos in a group | ## MCP Prompts @@ -164,7 +177,11 @@ gitnexus analyze [path] # Index a repository (or update stale index) gitnexus analyze --repair-fts # Fast path: rebuild/verify only FTS indexes on existing index data gitnexus analyze --force # Full rebuild: re-parse + graph rebuild + FTS rebuild gitnexus analyze --embeddings # Enable embedding generation (slower, better search) +gitnexus analyze --skills # Generate repo-specific skill files from detected communities gitnexus analyze --skip-agents-md # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits +gitnexus analyze --skip-skills # Skip installing .claude/skills/gitnexus/ skill files +gitnexus analyze --skip-git # Index folders that are not Git repositories +gitnexus analyze --workersVersioning & supply-chain protection (Cosign signatures, provenance, Kubernetes admission policy)
+ +The Docker images are version-locked to the npm package: + +- Stable images are **only published from `vX.Y.Z` git tags** (via `docker.yml` triggered directly by the tag push), and the workflow refuses to build unless the tag exactly matches `gitnexus/package.json`'s version. So `ghcr.io/abhigyanpatwari/gitnexus:1.6.2` (and its Docker Hub mirror `akonlabs/gitnexus:1.6.2`) is byte-for-byte the same release as `npm install gitnexus@1.6.2` — no drift, no floating builds from `main`. Both registries receive the same digest from a single build step, so you can pull from either and the signature verifies identically. +- Release-candidate images (e.g. `:1.7.0-rc.1`) are published alongside each RC npm release. They are built by `publish.yml` calling `docker.yml` as a reusable workflow after the RC tag is created and pushed. +- `:latest` is auto-promoted only from non-prerelease tags by the Docker metadata action, so it always points at a real, npm-published version. + +Both images are signed with [Cosign keyless signing][cosign-keyless] using the workflow's GitHub OIDC identity, and shipped with build provenance and SBOM attestations. **This is your protection against supply-chain attacks**: even if an attacker republishes a same-named image elsewhere (or somehow pushes to a typo-squatted registry), they cannot forge a Cosign signature tied to `abhigyanpatwari/GitNexus`'s `docker.yml`. Always verify before pulling into sensitive environments. + +**Stable releases** — signed from the `v*` tag ref: + +```bash +cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \ + --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com + +# Same signature verifies the Docker Hub mirror (identical digest): +cosign verify docker.io/akonlabs/gitnexus:1.6.2 \ + --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com +``` + +The regex pins the certificate identity to this repo's `docker.yml` workflow **run from a `v*` tag** — rejecting unsigned images, images signed by other workflows, and images signed from unprotected refs. It is identical for both registries because both sets of tags were signed at the same digest in one workflow run. + +**Release candidates** — signed from `refs/heads/main` (the caller's ref when `publish.yml` invokes `docker.yml` as a reusable workflow): + +```bash +cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \ + --certificate-identity 'https://github.com/abhigyanpatwari/GitNexus/.github/workflows/docker.yml@refs/heads/main' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com +``` + +You can also inspect the build provenance and SBOM: + +```bash +cosign download attestation ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \ + --predicate-type https://slsa.dev/provenance/v1 +``` + +**Kubernetes: enforce signatures at admission.** Ship the bundled [`ClusterImagePolicy`](deploy/kubernetes/cluster-image-policy.yaml) so the [Sigstore policy-controller][policy-controller] rejects any GitNexus pod whose image is not signed by this repo's `docker.yml` running from a `vX.Y.Z` tag — the same identity the `cosign verify` snippet above pins. + +```bash +# 1. Install the controller (one-time, cluster-wide) +helm repo add sigstore https://sigstore.github.io/helm-charts && helm repo update +helm install policy-controller -n cosign-system --create-namespace \ + sigstore/policy-controller + +# 2. Opt your namespace in +kubectl label namespacepolicy.sigstore.dev/include=true + +# 3. Apply the policy +kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml +``` + +After this, attempting to deploy an unsigned image — or one signed by anything other than `abhigyanpatwari/GitNexus`'s `docker.yml` at a `v*` tag — fails the admission webhook before a pod is ever created. This turns the verifiable signature into an enforced policy, which is the supply-chain control most clusters actually need. + +[cosign-keyless]: https://docs.sigstore.dev/cosign/signing/overview/ +[policy-controller]: https://docs.sigstore.dev/policy-controller/overview/ + + # Parse worker pool size (>=1; default: cores-1, capped at 16) gitnexus analyze --verbose # Log skipped files when parsers are unavailable gitnexus analyze --max-file-size 1024 # Skip files larger than N KB (default: 512, cap: 32768) gitnexus analyze --worker-timeout 60 # Increase worker idle timeout for slow parses @@ -177,13 +194,16 @@ gitnexus status # Show index status for current repo gitnexus clean # Delete index for current repo gitnexus clean --all --force # Delete all indexes gitnexus wiki [path] # Generate LLM-powered docs from knowledge graph -gitnexus wiki --model # Wiki with custom LLM model (default: gpt-4o-mini) +gitnexus wiki --model # Wiki with custom LLM model (default: minimax/minimax-m2.5) +gitnexus doctor # Show runtime platform capabilities and embedding configuration # Direct graph queries — the same tools the MCP server exposes, no MCP daemon needed gitnexus query " " # Process-grouped hybrid search gitnexus context [--uid | --file ] # 360° symbol view; flags disambiguate a shared name gitnexus impact [--uid | --file | --kind ] # Blast radius; flags disambiguate a shared name +gitnexus trace # Shortest directed path between two symbols gitnexus detect-changes # Map the working-tree diff to affected symbols and execution flows +gitnexus check # Read-only structural checks against the indexed graph gitnexus cypher " " # Run a raw Cypher query against the knowledge graph # Repository groups (multi-repo / monorepo service tracking) @@ -195,6 +215,7 @@ gitnexus group sync # Extract contrac gitnexus group contracts # Inspect extracted contracts and cross-links gitnexus group query # Check staleness of repos in a group +gitnexus group impact --target --repo # Cross-repo blast radius ``` > **`gitnexus uninstall`** reverses `gitnexus setup` — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified **by bundled gitnexus skill name** (e.g. `gitnexus-cli/`), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass `--force` to apply. Per-repo indexes (`gitnexus clean --all`) and the global npm package (`npm uninstall -g gitnexus`) are left for you to remove. @@ -219,7 +240,7 @@ GitNexus supports indexing multiple repositories. Each `gitnexus analyze` regist ## Supported Languages -TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, Ruby +TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, Ruby, Dart ### Language Feature Matrix @@ -238,6 +259,7 @@ TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, | Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ | | C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | +| Dart | ✓ | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | **Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics @@ -249,12 +271,14 @@ GitNexus ships with skill files that teach AI agents how to use the tools effect - **Debugging** — Trace bugs through call chains - **Impact Analysis** — Analyze blast radius before changes - **Refactoring** — Plan safe refactors using dependency mapping +- **Guide** — GitNexus tool/resource/schema reference for the agent +- **CLI** — Run analyze/status/clean/wiki commands on request -Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global). +Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global). Run `gitnexus analyze --skills` to additionally generate repo-specific skills for each detected functional area under `.claude/skills/generated/`. ## Requirements -- Node.js >= 18 +- Node.js >= 22 - Git repository (uses git for commit tracking) ## Release candidates @@ -340,7 +364,7 @@ gitnexus serve ### Installation fails with native module errors -Some optional language grammars (Dart, Kotlin, Swift) require native compilation. If they fail, GitNexus still works — those languages will be skipped. +Some optional language grammars (Dart, Proto, Swift, Kotlin) require native compilation. If they fail, GitNexus still works — those languages will be skipped. To skip them intentionally (no C++ toolchain needed), set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before installing. If `npm install -g gitnexus` fails on native modules: