gitnexus 1.0.0 → 1.1.1

package/README.md

@@ -13,41 +13,46 @@ Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, a
 
 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.
 
-**One command to index. One MCP connection to give your AI agent full codebase awareness.**
+**Three commands to give your AI agent full codebase awareness.**
 
 ## Quick Start
 
 ```bash
-# Index your repository
-npx gitnexus analyze
+# Install
+npm install -g gitnexus
+
+# One-time: configure MCP for your editors
+gitnexus setup
+
+# Index your repository (run from repo root)
+gitnexus analyze
 
-# Start MCP server (for Cursor, Claude Code, etc.)
-npx gitnexus mcp
+# Done! Open your editor — MCP connects automatically.
 ```
 
-Or install globally:
+Or without installing globally:
 
 ```bash
-npm install -g gitnexus
-gitnexus analyze
-gitnexus mcp
+npx gitnexus setup       # one-time
+npx gitnexus analyze     # per repo
 ```
 
-## MCP Setup
+The `setup` command auto-detects Cursor, Claude Code, and OpenCode, then writes the correct global MCP config. You only run it once.
+
+## MCP Setup (manual)
+
+If you prefer to configure manually instead of using `gitnexus setup`:
 
 ### Cursor / Windsurf
 
-Add to your MCP config (`.cursor/mcp.json` or equivalent):
+Add to `~/.cursor/mcp.json` (global — works for all projects):
 
 ```json
 {
   "mcpServers": {
     "gitnexus": {
       "command": "npx",
-      "args": ["-y", "gitnexus", "mcp"],
-      "env": {
-        "GITNEXUS_CWD": "/path/to/your/repo"
-      }
+      "args": ["-y", "gitnexus", "mcp"]
     }
   }
 }
@@ -61,7 +66,7 @@ claude mcp add gitnexus -- npx -y gitnexus mcp
 
 ### OpenCode
 
-Add to your `opencode.json`:
+Add to `~/.config/opencode/config.json`:
 
 ```json
 {
@@ -92,39 +97,48 @@ The result is a **KuzuDB graph database** stored locally in `.gitnexus/` with fu
 
 Your AI agent gets these tools automatically:
 
-| Tool | What It Does | Example |
-|------|-------------|---------|
-| `search` | Hybrid search (BM25 + semantic) with cluster context | "Find authentication logic" |
-| `overview` | List all clusters and processes | "Show me the codebase structure" |
-| `explore` | Deep dive on a symbol, cluster, or process | "Tell me about UserService" |
-| `impact` | Blast radius analysis | "What breaks if I change validateUser?" |
-| `cypher` | Raw Cypher graph queries | Complex relationship queries |
-| `read` | Smart file reader with fuzzy path matching | Read specific files |
-| `grep` | Regex pattern search | Find TODOs, error codes |
+| Tool | What It Does | `repo` Param |
+|------|-------------|--------------|
+| `list_repos` | Discover all indexed repositories | — |
+| `search` | Hybrid search (BM25 + semantic) with cluster context | Optional |
+| `overview` | List all clusters and processes | Optional |
+| `explore` | Deep dive on a symbol, cluster, or process | Optional |
+| `impact` | Blast radius analysis | Optional |
+| `cypher` | Raw Cypher graph queries | Optional |
+| `analyze` | Index or re-index a repository | Optional |
+
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `search({query: "auth", repo: "my-app"})`.
 
 ## MCP Resources
 
 | Resource | Purpose |
 |----------|---------|
-| `gitnexus://context` | Codebase stats and overview |
-| `gitnexus://clusters` | All functional clusters |
-| `gitnexus://cluster/{name}` | Cluster members and details |
-| `gitnexus://processes` | All execution flows |
-| `gitnexus://process/{name}` | Full process trace |
-| `gitnexus://schema` | Graph schema for Cypher queries |
+| `gitnexus://repos` | List all indexed repositories (read first) |
+| `gitnexus://repo/{name}/context` | Codebase stats and overview |
+| `gitnexus://repo/{name}/clusters` | All functional clusters |
+| `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details |
+| `gitnexus://repo/{name}/processes` | All execution flows |
+| `gitnexus://repo/{name}/process/{name}` | Full process trace |
+| `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries |
 
 ## CLI Commands
 
 ```bash
-gitnexus analyze [path]    # Index a repository (or update stale index)
-gitnexus analyze --force   # Force full re-index
-gitnexus mcp               # Start MCP server (stdio)
-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 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 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          # Delete all indexes
 ```
 
+## 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 with lazy KuzuDB connections.
+
 ## Supported Languages
 
 TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
@@ -132,7 +146,7 @@ TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
 ## How Impact Analysis Works
 
 ```
-gitnexus_impact("UserService", "upstream")
+gitnexus_impact({target: "UserService", direction: "upstream", repo: "my-app"})
 
 TARGET: Class UserService (src/services/user.ts)
 
@@ -169,6 +183,7 @@ These are installed automatically to `.claude/skills/` when you run `gitnexus an
 - 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
 

package/dist/cli/ai-context.js

@@ -20,7 +20,7 @@ function generateGitNexusContent(projectName, stats) {
     return `${GITNEXUS_START_MARKER}
 # GitNexus MCP
 
-This project is indexed by GitNexus, providing AI agents with deep code intelligence.
+This project is indexed as **${projectName}** by GitNexus, providing AI agents with deep code intelligence.
 
 ## Project: ${projectName}
 
@@ -35,48 +35,53 @@ This project is indexed by GitNexus, providing AI agents with deep code intellig
 ## Quick Start
 
 \`\`\`
-1. READ gitnexus://context        → Get codebase overview (~150 tokens)
-2. READ gitnexus://clusters       → See all functional clusters
-3. READ gitnexus://cluster/{name} → Deep dive on specific cluster
-4. gitnexus_search(query)         → Find code by query
+1. READ gitnexus://repos                          → Discover all indexed repos
+2. READ gitnexus://repo/${projectName}/context     → Get codebase overview (~150 tokens)
+3. READ gitnexus://repo/${projectName}/clusters    → See all functional clusters
+4. gitnexus_search({query: "...", repo: "${projectName}"}) → Find code by query
 \`\`\`
 
 ## Available Resources
 
 | Resource | Purpose |
 |----------|---------|
-| \`gitnexus://context\` | Codebase stats, tools, and resources overview |
-| \`gitnexus://clusters\` | All clusters with symbol counts and cohesion |
-| \`gitnexus://cluster/{name}\` | Cluster members and details |
-| \`gitnexus://processes\` | All execution flows with types |
-| \`gitnexus://process/{name}\` | Full process trace with steps |
-| \`gitnexus://schema\` | Graph schema for Cypher queries |
+| \`gitnexus://repos\` | List all indexed repositories |
+| \`gitnexus://repo/${projectName}/context\` | Codebase stats, tools, and resources overview |
+| \`gitnexus://repo/${projectName}/clusters\` | All clusters with symbol counts and cohesion |
+| \`gitnexus://repo/${projectName}/cluster/{name}\` | Cluster members and details |
+| \`gitnexus://repo/${projectName}/processes\` | All execution flows with types |
+| \`gitnexus://repo/${projectName}/process/{name}\` | Full process trace with steps |
+| \`gitnexus://repo/${projectName}/schema\` | Graph schema for Cypher queries |
 
 ## Available Tools
 
 | Tool | Purpose | When to Use |
 |------|---------|-------------|
+| \`list_repos\` | Discover indexed repos | First step with multiple repos |
 | \`search\` | Semantic + keyword search | Finding code by query |
 | \`overview\` | List clusters & processes | Understanding architecture |
 | \`explore\` | Deep dive on symbol/cluster/process | Detailed investigation |
 | \`impact\` | Blast radius analysis | Before making changes |
 | \`cypher\` | Raw graph queries | Complex analysis |
 
+> **Multi-repo:** When multiple repos are indexed, pass \`repo: "${projectName}"\` to target this project.
+
 ## Workflow Examples
 
 ### Exploring the Codebase
 \`\`\`
-READ gitnexus://context           → Stats and overview
-READ gitnexus://clusters          → Find relevant cluster
-READ gitnexus://cluster/Auth      → Explore Auth cluster
-gitnexus_explore("validateUser", "symbol") → Detailed symbol info
+READ gitnexus://repos                            → Discover repos
+READ gitnexus://repo/${projectName}/context       → Stats and overview
+READ gitnexus://repo/${projectName}/clusters      → Find relevant cluster
+READ gitnexus://repo/${projectName}/cluster/Auth  → Explore Auth cluster
+gitnexus_explore({name: "validateUser", type: "symbol", repo: "${projectName}"})
 \`\`\`
 
 ### Planning a Change
 \`\`\`
-gitnexus_impact("UserService", "upstream") → See what breaks
-READ gitnexus://processes         → Check affected flows
-gitnexus_explore("LoginFlow", "process") → Trace execution
+gitnexus_impact({target: "UserService", direction: "upstream", repo: "${projectName}"})
+READ gitnexus://repo/${projectName}/processes     → Check affected flows
+gitnexus_explore({name: "LoginFlow", type: "process", repo: "${projectName}"})
 \`\`\`
 
 ## Graph Schema

package/dist/cli/analyze.js

@@ -8,9 +8,10 @@ import ora from 'ora';
 import { runPipelineFromRepo } from '../core/ingestion/pipeline.js';
 import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReusedStatement, closeKuzu, createFTSIndex } from '../core/kuzu/kuzu-adapter.js';
 import { runEmbeddingPipeline } from '../core/embeddings/embedding-pipeline.js';
-import { getStoragePaths, saveMeta, loadMeta, addToGitignore } from '../storage/repo-manager.js';
+import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath } from '../storage/repo-manager.js';
 import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
 import { generateAIContextFiles } from './ai-context.js';
+import fs from 'fs/promises';
 export const analyzeCommand = async (inputPath, options) => {
     const spinner = ora('Checking repository...').start();
     // If path provided, use it directly. Otherwise, find git root from cwd.
@@ -83,7 +84,7 @@ export const analyzeCommand = async (inputPath, options) => {
     }
     // Save metadata
     const stats = await getKuzuStats();
-    await saveMeta(storagePath, {
+    const meta = {
         repoPath,
         lastCommit: currentCommit,
         indexedAt: new Date().toISOString(),
@@ -94,7 +95,10 @@ export const analyzeCommand = async (inputPath, options) => {
             communities: pipelineResult.communityResult?.stats.totalCommunities,
             processes: pipelineResult.processResult?.stats.totalProcesses,
         },
-    });
+    };
+    await saveMeta(storagePath, meta);
+    // Register in global registry
+    await registerRepo(repoPath, meta);
     // Add .gitnexus to .gitignore
     await addToGitignore(repoPath);
     // Generate AI context files
@@ -115,4 +119,13 @@ export const analyzeCommand = async (inputPath, options) => {
     if (aiContext.files.length > 0) {
         console.log(`  AI Context: ${aiContext.files.join(', ')}`);
     }
+    // Hint about setup if it hasn't been run
+    try {
+        await fs.access(getGlobalRegistryPath());
+    }
+    catch {
+        // Registry didn't exist before this run — suggest setup
+        console.log('');
+        console.log('  Tip: Run `gitnexus setup` to configure MCP for your editor.');
+    }
 };

package/dist/cli/clean.d.ts

@@ -2,7 +2,9 @@
  * Clean Command
  *
  * Removes the .gitnexus index from the current repository.
+ * Also unregisters it from the global registry.
  */
 export declare const cleanCommand: (options?: {
     force?: boolean;
+    all?: boolean;
 }) => Promise<void>;

package/dist/cli/clean.js

@@ -2,10 +2,40 @@
  * Clean Command
  *
  * Removes the .gitnexus index from the current repository.
+ * Also unregisters it from the global registry.
  */
 import fs from 'fs/promises';
-import { findRepo } from '../storage/repo-manager.js';
+import { findRepo, unregisterRepo, listRegisteredRepos } from '../storage/repo-manager.js';
 export const cleanCommand = async (options) => {
+    // --all flag: clean all indexed repos
+    if (options?.all) {
+        if (!options?.force) {
+            const entries = await listRegisteredRepos();
+            if (entries.length === 0) {
+                console.log('No indexed repositories found.');
+                return;
+            }
+            console.log(`This will delete GitNexus indexes for ${entries.length} repo(s):`);
+            for (const entry of entries) {
+                console.log(`  - ${entry.name} (${entry.path})`);
+            }
+            console.log('\nRun with --force to confirm deletion.');
+            return;
+        }
+        const entries = await listRegisteredRepos();
+        for (const entry of entries) {
+            try {
+                await fs.rm(entry.storagePath, { recursive: true, force: true });
+                await unregisterRepo(entry.path);
+                console.log(`Deleted: ${entry.name} (${entry.storagePath})`);
+            }
+            catch (err) {
+                console.error(`Failed to delete ${entry.name}:`, err);
+            }
+        }
+        return;
+    }
+    // Default: clean current repo
     const cwd = process.cwd();
     const repo = await findRepo(cwd);
     if (!repo) {
@@ -14,14 +44,15 @@ export const cleanCommand = async (options) => {
     }
     const repoName = repo.repoPath.split(/[/\\]/).pop() || repo.repoPath;
     if (!options?.force) {
-        console.log(`⚠️  This will delete the GitNexus index for: ${repoName}`);
+        console.log(`This will delete the GitNexus index for: ${repoName}`);
         console.log(`   Path: ${repo.storagePath}`);
         console.log('\nRun with --force to confirm deletion.');
         return;
     }
     try {
         await fs.rm(repo.storagePath, { recursive: true, force: true });
-        console.log(`🗑️  Deleted: ${repo.storagePath}`);
+        await unregisterRepo(repo.repoPath);
+        console.log(`Deleted: ${repo.storagePath}`);
     }
     catch (err) {
         console.error('Failed to delete:', err);

package/dist/cli/index.js

@@ -6,11 +6,16 @@ import { listCommand } from './list.js';
 import { statusCommand } from './status.js';
 import { mcpCommand } from './mcp.js';
 import { cleanCommand } from './clean.js';
+import { setupCommand } from './setup.js';
 const program = new Command();
 program
     .name('gitnexus')
     .description('GitNexus local CLI and MCP server')
-    .version('1.0.0');
+    .version('1.1.1');
+program
+    .command('setup')
+    .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode')
+    .action(setupCommand);
 program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')
@@ -24,11 +29,11 @@ program
     .action(serveCommand);
 program
     .command('mcp')
-    .description('Start MCP server (stdio)')
+    .description('Start MCP server (stdio) — serves all indexed repos')
     .action(mcpCommand);
 program
     .command('list')
-    .description('List indexed repositories')
+    .description('List all indexed repositories')
     .action(listCommand);
 program
     .command('status')
@@ -38,5 +43,6 @@ program
     .command('clean')
     .description('Delete GitNexus index for current repo')
     .option('-f, --force', 'Skip confirmation prompt')
+    .option('--all', 'Clean all indexed repos')
     .action(cleanCommand);
 program.parse(process.argv);

package/dist/cli/list.d.ts

@@ -1,6 +1,6 @@
 /**
  * List Command
  *
- * Shows info about the indexed repo in the current directory.
+ * Shows all indexed repositories from the global registry.
  */
 export declare const listCommand: () => Promise<void>;

package/dist/cli/list.js

@@ -1,27 +1,30 @@
 /**
  * List Command
  *
- * Shows info about the indexed repo in the current directory.
+ * Shows all indexed repositories from the global registry.
  */
-import { findRepo } from '../storage/repo-manager.js';
+import { listRegisteredRepos } from '../storage/repo-manager.js';
 export const listCommand = async () => {
-    const cwd = process.cwd();
-    const repo = await findRepo(cwd);
-    if (!repo) {
-        console.log('No indexed repository found in this directory.');
-        console.log('Run `gitnexus analyze` to index your codebase.');
+    const entries = await listRegisteredRepos({ validate: true });
+    if (entries.length === 0) {
+        console.log('No indexed repositories found.');
+        console.log('Run `gitnexus analyze` in a git repo to index it.');
         return;
     }
-    const stats = repo.meta.stats || {};
-    const repoName = repo.repoPath.split(/[/\\]/).pop() || repo.repoPath;
-    const indexedDate = new Date(repo.meta.indexedAt).toLocaleString();
-    console.log(`\n📁 ${repoName}`);
-    console.log(`   Path: ${repo.repoPath}`);
-    console.log(`   Indexed: ${indexedDate}`);
-    console.log(`   Stats: ${stats.files ?? 0} files, ${stats.nodes ?? 0} nodes, ${stats.edges ?? 0} edges`);
-    console.log(`   Commit: ${repo.meta.lastCommit?.slice(0, 7) || 'unknown'}`);
-    if (stats.communities)
-        console.log(`   Communities: ${stats.communities}`);
-    if (stats.processes)
-        console.log(`   Processes: ${stats.processes}`);
+    console.log(`\n  Indexed Repositories (${entries.length})\n`);
+    for (const entry of entries) {
+        const indexedDate = new Date(entry.indexedAt).toLocaleString();
+        const stats = entry.stats || {};
+        const commitShort = entry.lastCommit?.slice(0, 7) || 'unknown';
+        console.log(`  ${entry.name}`);
+        console.log(`    Path:    ${entry.path}`);
+        console.log(`    Indexed: ${indexedDate}`);
+        console.log(`    Commit:  ${commitShort}`);
+        console.log(`    Stats:   ${stats.files ?? 0} files, ${stats.nodes ?? 0} symbols, ${stats.edges ?? 0} edges`);
+        if (stats.communities)
+            console.log(`    Clusters:   ${stats.communities}`);
+        if (stats.processes)
+            console.log(`    Processes:  ${stats.processes}`);
+        console.log('');
+    }
 };

package/dist/cli/mcp.d.ts

@@ -1,7 +1,8 @@
 /**
  * MCP Command
  *
- * Starts the MCP server in standalone mode using local .gitnexus/ index.
- * Auto-detects repository by searching for .gitnexus/ folder.
+ * Starts the MCP server in standalone mode.
+ * Loads all indexed repos from the global registry.
+ * No longer depends on cwd — works from any directory.
  */
 export declare const mcpCommand: () => Promise<void>;

package/dist/cli/mcp.js

@@ -1,85 +1,36 @@
 /**
  * MCP Command
  *
- * Starts the MCP server in standalone mode using local .gitnexus/ index.
- * Auto-detects repository by searching for .gitnexus/ folder.
+ * Starts the MCP server in standalone mode.
+ * Loads all indexed repos from the global registry.
+ * No longer depends on cwd — works from any directory.
  */
-import path from 'path';
-import fs from 'fs/promises';
 import { startMCPServer } from '../mcp/server.js';
-import { LocalBackend, findRepo } from '../mcp/local/local-backend.js';
-/**
- * Get candidate paths to search for .gitnexus/ folder
- */
-function getCandidatePaths() {
-    const candidates = [];
-    // 1. Explicit override (highest priority)
-    if (process.env.GITNEXUS_CWD) {
-        candidates.push(process.env.GITNEXUS_CWD);
-    }
-    // 2. Current working directory
-    candidates.push(process.cwd());
-    // 3. VS Code workspace folders (if available via env)
-    if (process.env.VSCODE_WORKSPACE_FOLDER) {
-        candidates.push(process.env.VSCODE_WORKSPACE_FOLDER);
-    }
-    // Deduplicate while preserving order
-    return [...new Set(candidates.map(p => path.resolve(p)))];
-}
-/**
- * Find a git repository root by walking up the directory tree
- */
-async function findGitRoot(startPath) {
-    let current = path.resolve(startPath);
-    const root = path.parse(current).root;
-    while (current !== root) {
-        try {
-            const gitPath = path.join(current, '.git');
-            const stat = await fs.stat(gitPath);
-            if (stat.isDirectory())
-                return current;
-        }
-        catch { }
-        current = path.dirname(current);
-    }
-    return null;
-}
+import { LocalBackend } from '../mcp/local/local-backend.js';
+import { listRegisteredRepos } from '../storage/repo-manager.js';
 export const mcpCommand = async () => {
-    // Try multiple candidate paths to find .gitnexus/
-    const candidates = getCandidatePaths();
-    for (const candidate of candidates) {
-        const repo = await findRepo(candidate);
-        if (repo) {
-            const local = new LocalBackend();
-            await local.init(candidate);
-            console.error(`GitNexus: Found index at ${repo.storagePath}`);
-            // Start MCP server (no watcher daemon - staleness hints guide LLM to call analyze)
-            await startMCPServer(local);
-            return;
-        }
+    // Load all registered repos
+    const entries = await listRegisteredRepos({ validate: true });
+    if (entries.length === 0) {
+        console.error('');
+        console.error('  GitNexus: No indexed repositories found.');
+        console.error('');
+        console.error('  To get started:');
+        console.error('    1. cd into a git repository');
+        console.error('    2. Run: gitnexus analyze');
+        console.error('    3. Restart your editor');
+        console.error('');
+        process.exit(1);
     }
-    // No index found - give helpful error message
-    for (const candidate of candidates) {
-        const gitRoot = await findGitRoot(candidate);
-        if (gitRoot) {
-            console.error('');
-            console.error('╔════════════════════════════════════════════════════╗');
-            console.error('║          GitNexus: Repository Not Indexed          ║');
-            console.error('╠════════════════════════════════════════════════════╣');
-            console.error(`║ Found git repo: ${gitRoot.slice(0, 35).padEnd(35)} ║`);
-            console.error('║                                                    ║');
-            console.error('║ To enable AI code understanding, run:              ║');
-            console.error('║                                                    ║');
-            console.error('║   npx gitnexus analyze                             ║');
-            console.error('║                                                    ║');
-            console.error('║ Then restart your IDE.                             ║');
-            console.error('╚════════════════════════════════════════════════════╝');
-            console.error('');
-            process.exit(1);
-        }
+    // Initialize multi-repo backend from registry
+    const backend = new LocalBackend();
+    const ok = await backend.init();
+    if (!ok) {
+        console.error('GitNexus: Failed to initialize backend from registry.');
+        process.exit(1);
     }
-    // No git repo found
-    console.error('GitNexus: No git repository found.');
-    console.error(`Searched: ${candidates.join(', ')}`);
-    process.exit(1);
+    const repoNames = backend.listRepos().map(r => r.name);
+    console.error(`GitNexus: MCP server starting with ${repoNames.length} repo(s): ${repoNames.join(', ')}`);
+    // Start MCP server (serves all repos)
+    await startMCPServer(backend);
 };

package/dist/cli/setup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Setup Command
+ *
+ * One-time global MCP configuration writer.
+ * Detects installed AI editors and writes the appropriate MCP config
+ * so the GitNexus MCP server is available in all projects.
+ */
+export declare const setupCommand: () => Promise<void>;