@veewo/gitnexus 1.3.5 → 1.3.6

package/README.md

@@ -22,11 +22,13 @@ AI coding tools don't understand your codebase structure. They edit a function w
 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.
+That's it. This indexes the codebase, updates `AGENTS.md` / `CLAUDE.md` context files, and (when using project scope) installs repo-local agent skills.
 
-To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
+To configure MCP + skills, run `npx gitnexus setup` once (default global mode), or use `npx gitnexus setup --scope project` for project-local mode.
 
-`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
+`gitnexus setup` supports two scopes:
+- `global` (default): configures global editor MCP + installs global skills
+- `project`: writes repo-local `.mcp.json` + installs repo-local skills
 
 ## Team Deployment and Distribution
 
@@ -152,7 +154,8 @@ Your AI agent gets these tools automatically:
 ## CLI Commands
 
 ```bash
-gitnexus setup                    # Configure MCP for your editors (one-time)
+gitnexus setup                    # Default: global MCP + global skills
+gitnexus setup --scope project    # Project-local MCP + project-local skills
 gitnexus analyze [path]           # Index a repository (or update stale index)
 gitnexus analyze --force          # Force full re-index
 gitnexus analyze --embeddings     # Enable semantic embeddings (off by default)
@@ -212,9 +215,10 @@ GitNexus ships with skill files that teach AI agents how to use the tools effect
 
 Installation rules:
 
-- `gitnexus analyze` installs repo-local skills to `.agents/skills/gitnexus/` and updates `AGENTS.md` / `CLAUDE.md`.
-- `gitnexus setup` installs global skills to `~/.agents/skills/gitnexus/`.
-- If needed, create editor-specific symlinks yourself (for example map `.claude/skills/gitnexus` to `~/.agents/skills/gitnexus`).
+- `gitnexus setup` controls skill scope:
+  - default `global`: installs to `~/.agents/skills/gitnexus/`
+  - `--scope project`: installs to `.agents/skills/gitnexus/` in current repo
+- `gitnexus analyze` always updates `AGENTS.md` / `CLAUDE.md`; skill install follows configured setup scope.
 
 ## Requirements
 

package/dist/cli/ai-context.d.ts

@@ -5,6 +5,7 @@
  * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, etc.
  * CLAUDE.md is for Claude Code which only reads that file.
  */
+type SkillScope = 'project' | 'global';
 interface RepoStats {
     files?: number;
     nodes?: number;
@@ -16,7 +17,9 @@ interface RepoStats {
 /**
  * Generate AI context files after indexing
  */
-export declare function generateAIContextFiles(repoPath: string, _storagePath: string, projectName: string, stats: RepoStats): Promise<{
+export declare function generateAIContextFiles(repoPath: string, _storagePath: string, projectName: string, stats: RepoStats, options?: {
+    skillScope?: SkillScope;
+}): Promise<{
     files: string[];
 }>;
 export {};

package/dist/cli/ai-context.js

@@ -23,7 +23,10 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
  * - One-line quick start (read context resource) gives agents an entry point
  * - Tools/Resources sections are labeled "Reference" — agents treat them as lookup, not workflow
  */
-function generateGitNexusContent(projectName, stats) {
+function generateGitNexusContent(projectName, stats, skillScope) {
+    const skillRoot = skillScope === 'global'
+        ? '~/.agents/skills/gitnexus'
+        : '.agents/skills/gitnexus';
     return `${GITNEXUS_START_MARKER}
 # GitNexus MCP
 
@@ -41,12 +44,12 @@ This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} s
 
 | Task | Read this skill file |
 |------|---------------------|
-| Understand architecture / "How does X work?" | \`.agents/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
-| Blast radius / "What breaks if I change X?" | \`.agents/skills/gitnexus/gitnexus-impact-analysis/SKILL.md\` |
-| Trace bugs / "Why is X failing?" | \`.agents/skills/gitnexus/gitnexus-debugging/SKILL.md\` |
-| Rename / extract / split / refactor | \`.agents/skills/gitnexus/gitnexus-refactoring/SKILL.md\` |
-| Tools, resources, schema reference | \`.agents/skills/gitnexus/gitnexus-guide/SKILL.md\` |
-| Index, status, clean, wiki CLI commands | \`.agents/skills/gitnexus/gitnexus-cli/SKILL.md\` |
+| Understand architecture / "How does X work?" | \`${skillRoot}/gitnexus-exploring/SKILL.md\` |
+| Blast radius / "What breaks if I change X?" | \`${skillRoot}/gitnexus-impact-analysis/SKILL.md\` |
+| Trace bugs / "Why is X failing?" | \`${skillRoot}/gitnexus-debugging/SKILL.md\` |
+| Rename / extract / split / refactor | \`${skillRoot}/gitnexus-refactoring/SKILL.md\` |
+| Tools, resources, schema reference | \`${skillRoot}/gitnexus-guide/SKILL.md\` |
+| Index, status, clean, wiki CLI commands | \`${skillRoot}/gitnexus-cli/SKILL.md\` |
 
 ${GITNEXUS_END_MARKER}`;
 }
@@ -164,8 +167,9 @@ Use GitNexus tools to accomplish this task.
 /**
  * Generate AI context files after indexing
  */
-export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats) {
-    const content = generateGitNexusContent(projectName, stats);
+export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats, options) {
+    const skillScope = options?.skillScope === 'global' ? 'global' : 'project';
+    const content = generateGitNexusContent(projectName, stats, skillScope);
     const createdFiles = [];
     // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Codex, Cline, etc.)
     const agentsPath = path.join(repoPath, 'AGENTS.md');
@@ -175,10 +179,12 @@ export async function generateAIContextFiles(repoPath, _storagePath, projectName
     const claudePath = path.join(repoPath, 'CLAUDE.md');
     const claudeResult = await upsertGitNexusSection(claudePath, content);
     createdFiles.push(`CLAUDE.md (${claudeResult})`);
-    // Install skills to .agents/skills/gitnexus/
-    const installedSkills = await installSkills(repoPath);
-    if (installedSkills.length > 0) {
-        createdFiles.push(`.agents/skills/gitnexus/ (${installedSkills.length} skills)`);
+    // Install repo-local skills only when project scope is selected.
+    if (skillScope === 'project') {
+        const installedSkills = await installSkills(repoPath);
+        if (installedSkills.length > 0) {
+            createdFiles.push(`.agents/skills/gitnexus/ (${installedSkills.length} skills)`);
+        }
     }
     return { files: createdFiles };
 }

package/dist/cli/ai-context.test.js

@@ -11,7 +11,7 @@ test('generateAIContextFiles installs repo skills under .agents/skills/gitnexus'
             nodes: 1,
             edges: 2,
             processes: 3,
-        });
+        }, { skillScope: 'project' });
         const agentsPath = path.join(repoPath, 'AGENTS.md');
         const claudePath = path.join(repoPath, 'CLAUDE.md');
         const skillPath = path.join(repoPath, '.agents', 'skills', 'gitnexus', 'gitnexus-exploring', 'SKILL.md');
@@ -28,3 +28,25 @@ test('generateAIContextFiles installs repo skills under .agents/skills/gitnexus'
         await fs.rm(repoPath, { recursive: true, force: true });
     }
 });
+test('generateAIContextFiles with global scope skips repo skill install', async () => {
+    const repoPath = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ai-context-global-'));
+    try {
+        const result = await generateAIContextFiles(repoPath, '', 'demo-repo', {
+            nodes: 1,
+            edges: 2,
+            processes: 3,
+        }, { skillScope: 'global' });
+        const agentsPath = path.join(repoPath, 'AGENTS.md');
+        const claudePath = path.join(repoPath, 'CLAUDE.md');
+        const localSkillsDir = path.join(repoPath, '.agents', 'skills', 'gitnexus');
+        const agentsContent = await fs.readFile(agentsPath, 'utf-8');
+        const claudeContent = await fs.readFile(claudePath, 'utf-8');
+        assert.match(agentsContent, /~\/\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
+        assert.match(claudeContent, /~\/\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
+        assert.ok(!result.files.some((entry) => entry.includes('.agents/skills/gitnexus/')), 'did not expect repo-local skills in generated file summary');
+        await assert.rejects(fs.access(localSkillsDir));
+    }
+    finally {
+        await fs.rm(repoPath, { recursive: true, force: true });
+    }
+});

package/dist/cli/analyze.js

@@ -13,7 +13,7 @@ import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReuse
 // loaded when embeddings are not requested. This avoids crashes on Node
 // versions whose ABI is not yet supported by the native binary (#89).
 // disposeEmbedder intentionally not called — ONNX Runtime segfaults on cleanup (see #38)
-import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath } from '../storage/repo-manager.js';
+import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath, loadCLIConfig } from '../storage/repo-manager.js';
 import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
 import { generateAIContextFiles } from './ai-context.js';
 import fs from 'fs/promises';
@@ -312,6 +312,8 @@ export const analyzeCommand = async (inputPath, options) => {
         communities: pipelineResult.communityResult?.stats.totalCommunities,
         clusters: aggregatedClusterCount,
         processes: pipelineResult.processResult?.stats.totalProcesses,
+    }, {
+        skillScope: ((await loadCLIConfig()).setupScope === 'global') ? 'global' : 'project',
     });
     await closeKuzu();
     // Note: we intentionally do NOT call disposeEmbedder() here.

package/dist/cli/index.js

@@ -60,6 +60,7 @@ program
 program
     .command('setup')
     .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode, Codex')
+    .option('--scope <scope>', 'Install target: global (default) or project')
     .action(setupCommand);
 program
     .command('analyze [path]')

package/dist/cli/setup.d.ts

@@ -5,4 +5,8 @@
  * 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>;
+interface SetupOptions {
+    scope?: string;
+}
+export declare const setupCommand: (options?: SetupOptions) => Promise<void>;
+export {};

package/dist/cli/setup.js

@@ -11,10 +11,18 @@ import os from 'os';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'url';
-import { getGlobalDir } from '../storage/repo-manager.js';
+import { getGlobalDir, loadCLIConfig, saveCLIConfig } from '../storage/repo-manager.js';
+import { getGitRoot } from '../storage/git.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
+function resolveSetupScope(rawScope) {
+    if (!rawScope || rawScope.trim() === '')
+        return 'global';
+    if (rawScope === 'global' || rawScope === 'project')
+        return rawScope;
+    throw new Error(`Invalid --scope value "${rawScope}". Use "global" or "project".`);
+}
 /**
  * The MCP server entry for all editors.
  * On Windows, npx must be invoked via cmd /c since it's a .cmd script.
@@ -125,6 +133,18 @@ async function installGlobalAgentSkills(result) {
         result.errors.push(`Global agent skills: ${err.message}`);
     }
 }
+async function installProjectAgentSkills(repoRoot, result) {
+    const skillsDir = path.join(repoRoot, '.agents', 'skills', 'gitnexus');
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`Project agent skills (${installed.length} skills → ${path.relative(repoRoot, skillsDir)}/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`Project agent skills: ${err.message}`);
+    }
+}
 /**
  * Install GitNexus hooks to ~/.claude/settings.json for Claude Code.
  * Merges hook config without overwriting existing hooks.
@@ -212,6 +232,28 @@ async function setupCodex(result) {
         result.errors.push(`Codex: ${err.message}`);
     }
 }
+async function setupProjectMcp(repoRoot, result) {
+    const mcpPath = path.join(repoRoot, '.mcp.json');
+    try {
+        const existing = await readJsonFile(mcpPath);
+        const updated = mergeMcpConfig(existing);
+        await writeJsonFile(mcpPath, updated);
+        result.configured.push(`Project MCP (${path.relative(repoRoot, mcpPath)})`);
+    }
+    catch (err) {
+        result.errors.push(`Project MCP: ${err.message}`);
+    }
+}
+async function saveSetupScope(scope, result) {
+    try {
+        const existing = await loadCLIConfig();
+        await saveCLIConfig({ ...existing, setupScope: scope });
+        result.configured.push(`Default setup scope (${scope})`);
+    }
+    catch (err) {
+        result.errors.push(`Persist setup scope: ${err.message}`);
+    }
+}
 // ─── Skill Installation ───────────────────────────────────────────
 const SKILL_NAMES = ['gitnexus-exploring', 'gitnexus-debugging', 'gitnexus-impact-analysis', 'gitnexus-refactoring', 'gitnexus-guide', 'gitnexus-cli'];
 /**
@@ -273,11 +315,20 @@ async function copyDirRecursive(src, dest) {
     }
 }
 // ─── Main command ──────────────────────────────────────────────────
-export const setupCommand = async () => {
+export const setupCommand = async (options = {}) => {
     console.log('');
     console.log('  GitNexus Setup');
     console.log('  ==============');
     console.log('');
+    let scope;
+    try {
+        scope = resolveSetupScope(options.scope);
+    }
+    catch (err) {
+        console.log(`  ${err?.message || String(err)}\n`);
+        process.exitCode = 1;
+        return;
+    }
     // Ensure global directory exists
     const globalDir = getGlobalDir();
     await fs.mkdir(globalDir, { recursive: true });
@@ -286,15 +337,28 @@ export const setupCommand = async () => {
         skipped: [],
         errors: [],
     };
-    // Detect and configure each editor's MCP
-    await setupCursor(result);
-    await setupClaudeCode(result);
-    await setupOpenCode(result);
-    await setupCodex(result);
-    // Install shared global skills once
-    await installGlobalAgentSkills(result);
-    // Optional Claude-specific hooks
-    await installClaudeCodeHooks(result);
+    if (scope === 'global') {
+        // Detect and configure each editor's MCP
+        await setupCursor(result);
+        await setupClaudeCode(result);
+        await setupOpenCode(result);
+        await setupCodex(result);
+        // Install shared global skills once
+        await installGlobalAgentSkills(result);
+        // Optional Claude-specific hooks
+        await installClaudeCodeHooks(result);
+    }
+    else {
+        const repoRoot = getGitRoot(process.cwd());
+        if (!repoRoot) {
+            console.log('  --scope project requires running inside a git repository\n');
+            process.exitCode = 1;
+            return;
+        }
+        await setupProjectMcp(repoRoot, result);
+        await installProjectAgentSkills(repoRoot, result);
+    }
+    await saveSetupScope(scope, result);
     // Print results
     if (result.configured.length > 0) {
         console.log('  Configured:');
@@ -318,6 +382,7 @@ export const setupCommand = async () => {
     }
     console.log('');
     console.log('  Summary:');
+    console.log(`    Scope: ${scope}`);
     console.log(`    MCP configured for: ${result.configured.filter(c => !c.includes('skills')).join(', ') || 'none'}`);
     console.log(`    Skills installed to: ${result.configured.filter(c => c.includes('skills')).length > 0 ? result.configured.filter(c => c.includes('skills')).join(', ') : 'none'}`);
     console.log('');

package/dist/cli/setup.test.js

@@ -22,7 +22,11 @@ test('setup installs global skills under ~/.agents/skills/gitnexus', async () =>
             },
         });
         const skillPath = path.join(fakeHome, '.agents', 'skills', 'gitnexus', 'gitnexus-exploring', 'SKILL.md');
+        const configPath = path.join(fakeHome, '.gitnexus', 'config.json');
         await fs.access(skillPath);
+        const configRaw = await fs.readFile(configPath, 'utf-8');
+        const config = JSON.parse(configRaw);
+        assert.equal(config.setupScope, 'global');
         assert.ok(true);
     }
     finally {
@@ -80,3 +84,41 @@ process.exit(0);
         await fs.rm(fakeBin, { recursive: true, force: true });
     }
 });
+test('setup with --scope project writes local MCP and repo-local skills only', async () => {
+    const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
+    const fakeRepo = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-repo-'));
+    try {
+        await execFileAsync('git', ['init'], {
+            cwd: fakeRepo,
+            env: {
+                ...process.env,
+                HOME: fakeHome,
+                USERPROFILE: fakeHome,
+            },
+        });
+        await execFileAsync(process.execPath, [cliPath, 'setup', '--scope', 'project'], {
+            cwd: fakeRepo,
+            env: {
+                ...process.env,
+                HOME: fakeHome,
+                USERPROFILE: fakeHome,
+            },
+        });
+        const projectMcpPath = path.join(fakeRepo, '.mcp.json');
+        const localSkillPath = path.join(fakeRepo, '.agents', 'skills', 'gitnexus', 'gitnexus-exploring', 'SKILL.md');
+        const globalSkillPath = path.join(fakeHome, '.agents', 'skills', 'gitnexus', 'gitnexus-exploring', 'SKILL.md');
+        const configPath = path.join(fakeHome, '.gitnexus', 'config.json');
+        const projectMcpRaw = await fs.readFile(projectMcpPath, 'utf-8');
+        const projectMcp = JSON.parse(projectMcpRaw);
+        const configRaw = await fs.readFile(configPath, 'utf-8');
+        const config = JSON.parse(configRaw);
+        assert.equal(projectMcp.mcpServers?.gitnexus?.command, 'npx');
+        await fs.access(localSkillPath);
+        await assert.rejects(fs.access(globalSkillPath));
+        assert.equal(config.setupScope, 'project');
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+        await fs.rm(fakeRepo, { recursive: true, force: true });
+    }
+});

package/dist/storage/repo-manager.d.ts

@@ -110,6 +110,7 @@ export interface CLIConfig {
     apiKey?: string;
     model?: string;
     baseUrl?: string;
+    setupScope?: 'global' | 'project';
 }
 /**
  * Get the path to the global CLI config file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veewo/gitnexus",
-  "version": "1.3.5",
+  "version": "1.3.6",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",