gitnexus 1.2.8 → 1.3.0

package/README.md

@@ -1,186 +1,194 @@
-# GitNexus
-
-**Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
-
-Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
-
-[![npm version](https://img.shields.io/npm/v/gitnexus.svg)](https://www.npmjs.com/package/gitnexus)
-[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
-
----
-
-## Why?
-
-AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. GitNexus fixes this by **precomputing every dependency, call chain, and relationship** into a queryable graph.
-
-**Three commands to give your AI agent full codebase awareness.**
-
-## Quick Start
-
-```bash
-# Index your repo (run from repo root)
-npx gitnexus analyze
-```
-
-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.
-
-To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
-
-`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
-
-### Editor Support
-
-| Editor | MCP | Skills | Hooks (auto-augment) | Support |
-|--------|-----|--------|---------------------|---------|
-| **Claude Code** | Yes | Yes | Yes (PreToolUse) | **Full** |
-| **Cursor** | Yes | Yes | — | MCP + Skills |
-| **Windsurf** | Yes | — | — | MCP |
-| **OpenCode** | Yes | Yes | — | MCP + Skills |
-
-> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context.
-
-## MCP Setup (manual)
-
-If you prefer to configure manually instead of using `gitnexus setup`:
-
-### Claude Code (full support — MCP + skills + hooks)
-
-```bash
-claude mcp add gitnexus -- npx -y gitnexus@latest mcp
-```
-
-### Cursor / Windsurf
-
-Add to `~/.cursor/mcp.json` (global — works for all projects):
-
-```json
-{
-  "mcpServers": {
-    "gitnexus": {
-      "command": "npx",
-      "args": ["-y", "gitnexus@latest", "mcp"]
-    }
-  }
-}
-```
-
-### OpenCode
-
-Add to `~/.config/opencode/config.json`:
-
-```json
-{
-  "mcp": {
-    "gitnexus": {
-      "command": "npx",
-      "args": ["-y", "gitnexus@latest", "mcp"]
-    }
-  }
-}
-```
-
-## 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 and function calls 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
-
-The result is a **KuzuDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
-
-## MCP Tools
-
-Your AI agent gets these tools automatically:
-
-| Tool | What It Does | `repo` Param |
-|------|-------------|--------------|
-| `list_repos` | Discover all indexed repositories | — |
-| `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 |
-
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({query: "auth", repo: "my-app"})`.
-
-## MCP Resources
-
-| Resource | Purpose |
-|----------|---------|
-| `gitnexus://repos` | List all indexed repositories (read 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 |
-
-## MCP Prompts
-
-| 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 |
-
-## CLI Commands
-
-```bash
-gitnexus setup                    # Configure MCP for your editors (one-time)
-gitnexus analyze [path]           # Index a repository (or update stale index)
-gitnexus analyze --force          # Force full re-index
-gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
-gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
-gitnexus serve                   # Start HTTP server for web UI
-gitnexus list                    # List all indexed repositories
-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 <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
-```
-
-## Multi-Repo Support
-
-GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically.
-
-## Supported Languages
-
-TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
-
-## Agent Skills
-
-GitNexus ships with skill files that teach AI agents how to use the tools effectively:
-
-- **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
-
-Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global).
-
-## Requirements
-
-- Node.js >= 18
-- Git repository (uses git for commit tracking)
-
-## Privacy
-
-- All processing happens locally on your machine
-- No code is sent to any server
-- Index stored in `.gitnexus/` inside your repo (gitignored)
-- Global registry at `~/.gitnexus/` stores only paths and metadata
-
-## Web UI
-
-GitNexus also has a browser-based UI at [gitnexus.vercel.app](https://gitnexus.vercel.app) — 100% client-side, your code never leaves the browser.
-
-## License
-
-[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
-
-Free for non-commercial use. Contact for commercial licensing.
+# GitNexus
+
+**Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
+
+Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
+
+[![npm version](https://img.shields.io/npm/v/gitnexus.svg)](https://www.npmjs.com/package/gitnexus)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+---
+
+## Why?
+
+AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. GitNexus fixes this by **precomputing every dependency, call chain, and relationship** into a queryable graph.
+
+**Three commands to give your AI agent full codebase awareness.**
+
+## Quick Start
+
+```bash
+# Index your repo (run from repo root)
+npx gitnexus analyze
+```
+
+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.
+
+To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
+
+`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
+
+### Editor Support
+
+| Editor | MCP | Skills | Hooks (auto-augment) | Support |
+|--------|-----|--------|---------------------|---------|
+| **Claude Code** | Yes | Yes | Yes (PreToolUse) | **Full** |
+| **Cursor** | Yes | Yes | — | MCP + Skills |
+| **Windsurf** | Yes | — | — | MCP |
+| **OpenCode** | Yes | Yes | — | MCP + Skills |
+
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context.
+
+### Community Integrations
+
+| Agent | Install | Source |
+|-------|---------|--------|
+| [pi](https://pi.dev) | `pi install npm:pi-gitnexus` | [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus) |
+
+## MCP Setup (manual)
+
+If you prefer to configure manually instead of using `gitnexus setup`:
+
+### Claude Code (full support — MCP + skills + hooks)
+
+```bash
+claude mcp add gitnexus -- npx -y gitnexus@latest mcp
+```
+
+### Cursor / Windsurf
+
+Add to `~/.cursor/mcp.json` (global — works for all projects):
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add to `~/.config/opencode/config.json`:
+
+```json
+{
+  "mcp": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+## 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 and function calls 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
+
+The result is a **KuzuDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
+
+## MCP Tools
+
+Your AI agent gets these tools automatically:
+
+| Tool | What It Does | `repo` Param |
+|------|-------------|--------------|
+| `list_repos` | Discover all indexed repositories | — |
+| `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 |
+
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({query: "auth", repo: "my-app"})`.
+
+## MCP Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `gitnexus://repos` | List all indexed repositories (read 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 |
+
+## MCP Prompts
+
+| 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 |
+
+## CLI Commands
+
+```bash
+gitnexus setup                    # Configure MCP for your editors (one-time)
+gitnexus analyze [path]           # Index a repository (or update stale index)
+gitnexus analyze --force          # Force full re-index
+gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
+gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
+gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
+gitnexus list                    # List all indexed repositories
+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 <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
+```
+
+## Multi-Repo Support
+
+GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically.
+
+## Supported Languages
+
+TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
+
+## Agent Skills
+
+GitNexus ships with skill files that teach AI agents how to use the tools effectively:
+
+- **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
+
+Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global).
+
+## Requirements
+
+- Node.js >= 18
+- Git repository (uses git for commit tracking)
+
+## Privacy
+
+- All processing happens locally on your machine
+- No code is sent to any server
+- Index stored in `.gitnexus/` inside your repo (gitignored)
+- Global registry at `~/.gitnexus/` stores only paths and metadata
+
+## Web UI
+
+GitNexus also has a browser-based UI at [gitnexus.vercel.app](https://gitnexus.vercel.app) — 100% client-side, your code never leaves the browser.
+
+**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.
+
+## License
+
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+Free for non-commercial use. Contact for commercial licensing.

package/dist/cli/ai-context.js

@@ -24,67 +24,67 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
  * - Tools/Resources sections are labeled "Reference" — agents treat them as lookup, not workflow
  */
 function generateGitNexusContent(projectName, stats) {
-    return `${GITNEXUS_START_MARKER}
-# GitNexus MCP
-
-This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows).
-
-GitNexus provides a knowledge graph over this codebase — call chains, blast radius, execution flows, and semantic search.
-
-## Always Start Here
-
-For any task involving code understanding, debugging, impact analysis, or refactoring, you must:
-
-1. **Read \`gitnexus://repo/{name}/context\`** — codebase overview + check index freshness
-2. **Match your task to a skill below** and **read that skill file**
-3. **Follow the skill's workflow and checklist**
-
-> If step 1 warns the index is stale, run \`npx gitnexus analyze\` in the terminal first.
-
-## Skills
-
-| Task | Read this skill file |
-|------|---------------------|
-| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/exploring/SKILL.md\` |
-| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/impact-analysis/SKILL.md\` |
-| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/debugging/SKILL.md\` |
-| Rename / extract / split / refactor | \`.claude/skills/gitnexus/refactoring/SKILL.md\` |
-
-## 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 |
-
-## 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
-
-\`\`\`cypher
-MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
-RETURN caller.name, caller.filePath
-\`\`\`
-
+    return `${GITNEXUS_START_MARKER}
+# GitNexus MCP
+
+This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows).
+
+GitNexus provides a knowledge graph over this codebase — call chains, blast radius, execution flows, and semantic search.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring, you must:
+
+1. **Read \`gitnexus://repo/{name}/context\`** — codebase overview + check index freshness
+2. **Match your task to a skill below** and **read that skill file**
+3. **Follow the skill's workflow and checklist**
+
+> If step 1 warns the index is stale, run \`npx gitnexus analyze\` in the terminal first.
+
+## Skills
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/exploring/SKILL.md\` |
+| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/impact-analysis/SKILL.md\` |
+| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/debugging/SKILL.md\` |
+| Rename / extract / split / refactor | \`.claude/skills/gitnexus/refactoring/SKILL.md\` |
+
+## 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 |
+
+## 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
+
+\`\`\`cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+\`\`\`
+
 ${GITNEXUS_END_MARKER}`;
 }
 /**
@@ -168,16 +168,16 @@ async function installSkills(repoPath) {
             }
             catch {
                 // Fallback: generate minimal skill content
-                skillContent = `---
-name: gitnexus-${skill.name}
-description: ${skill.description}
----
-
-# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
-
-${skill.description}
-
-Use GitNexus tools to accomplish this task.
+                skillContent = `---
+name: gitnexus-${skill.name}
+description: ${skill.description}
+---
+
+# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
+
+${skill.description}
+
+Use GitNexus tools to accomplish this task.
 `;
             }
             await fs.writeFile(skillPath, skillContent, 'utf-8');