@veewo/gitnexus 1.3.5 → 1.3.7

package/README.md

@@ -22,11 +22,18 @@ 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 --agent <claude|opencode|codex>` once (default global mode), or add `--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` requires an agent selection:
+- `--agent claude`: configure Claude MCP only
+- `--agent opencode`: configure OpenCode MCP only
+- `--agent codex`: configure Codex MCP only
+
+It also supports two scopes:
+- `global` (default): writes MCP to the selected agent's global config + installs global skills
+- `project`: writes MCP to the selected agent's project-local config + installs repo-local skills
 
 ## Team Deployment and Distribution
 
@@ -36,6 +43,7 @@ For small-team rollout (single stable channel only), follow:
 Key links:
 - [npm publish workflow](../.github/workflows/publish.yml)
 - [CLI package config](./package.json)
+- [Agent install + acceptance runbook](../INSTALL-GUIDE.md)
 
 ### Editor Support
 
@@ -82,14 +90,14 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
 
 ### OpenCode
 
-Add to `~/.config/opencode/config.json`:
+Add to `~/.config/opencode/opencode.json`:
 
 ```json
 {
   "mcp": {
     "gitnexus": {
-      "command": "npx",
-      "args": ["-y", "gitnexus@latest", "mcp"]
+      "type": "local",
+      "command": ["npx", "-y", "gitnexus@latest", "mcp"]
     }
   }
 }
@@ -152,12 +160,14 @@ Your AI agent gets these tools automatically:
 ## CLI Commands
 
 ```bash
-gitnexus setup                    # Configure MCP for your editors (one-time)
+gitnexus setup --agent claude                     # Global setup for Claude
+gitnexus setup --agent codex                      # Global setup for Codex
+gitnexus setup --scope project --agent opencode   # Project-local setup for OpenCode
 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)
 gitnexus analyze --scope-prefix Assets/NEON/Code --scope-prefix Packages/com.veewo.*  # Scoped multi-directory indexing
-gitnexus analyze --scope-manifest ./scope.txt --repo-alias neonspark-v1-subset         # Scoped indexing + stable repo alias
+gitnexus analyze --scope-manifest .gitnexus/sync-manifest.txt --repo-alias neonspark-v1-subset  # Scoped indexing + stable repo alias
 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
@@ -212,9 +222,11 @@ 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:
+  - requires `--agent <claude|opencode|codex>`
+  - 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

@@ -59,7 +59,9 @@ program
     .version(resolveCliVersion());
 program
     .command('setup')
-    .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode, Codex')
+    .description('One-time setup: configure MCP for a selected coding agent (claude/opencode/codex)')
+    .option('--scope <scope>', 'Install target: global (default) or project')
+    .option('--agent <agent>', 'Target coding agent: claude, opencode, or codex')
     .action(setupCommand);
 program
     .command('analyze [path]')
@@ -68,7 +70,7 @@ program
     .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
     .option('--extensions <list>', 'Comma-separated file extensions to include (e.g. .cs,.ts)')
     .option('--repo-alias <name>', 'Override indexed repository name with a stable alias')
-    .option('--scope-manifest <path>', 'Manifest file with scope rules (supports comments and * wildcard)')
+    .option('--scope-manifest <path>', 'Manifest file with scope rules (supports comments and * wildcard; recommended: .gitnexus/sync-manifest.txt)')
     .option('--scope-prefix <pathPrefix>', 'Add a scope path prefix rule (repeatable)', collectValues, [])
     .action(analyzeCommand);
 program

package/dist/cli/setup.d.ts

@@ -1,8 +1,13 @@
 /**
  * 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.
+ * One-time MCP configuration writer with explicit agent targeting.
+ * Configures only the selected coding agent's MCP entry
+ * in either global or project scope.
  */
-export declare const setupCommand: () => Promise<void>;
+interface SetupOptions {
+    scope?: string;
+    agent?: string;
+}
+export declare const setupCommand: (options?: SetupOptions) => Promise<void>;
+export {};

package/dist/cli/setup.js

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * One-time MCP configuration writer with explicit agent targeting.
+ * Configures only the selected coding agent's MCP entry
+ * in either global or project scope.
  */
 import fs from 'fs/promises';
 import path from 'path';
@@ -11,10 +11,27 @@ 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".`);
+}
+function resolveSetupAgent(rawAgent) {
+    if (!rawAgent || rawAgent.trim() === '') {
+        throw new Error('Missing --agent. Use one of: claude, opencode, codex.');
+    }
+    if (rawAgent === 'claude' || rawAgent === 'opencode' || rawAgent === 'codex') {
+        return rawAgent;
+    }
+    throw new Error(`Invalid --agent value "${rawAgent}". Use "claude", "opencode", or "codex".`);
+}
 /**
  * The MCP server entry for all editors.
  * On Windows, npx must be invoked via cmd /c since it's a .cmd script.
@@ -31,6 +48,13 @@ function getMcpEntry() {
         args: ['-y', 'gitnexus@latest', 'mcp'],
     };
 }
+function getOpenCodeMcpEntry() {
+    const entry = getMcpEntry();
+    return {
+        type: 'local',
+        command: [entry.command, ...entry.args],
+    };
+}
 /**
  * Merge gitnexus entry into an existing MCP config JSON object.
  * Returns the updated config.
@@ -45,6 +69,20 @@ function mergeMcpConfig(existing) {
     existing.mcpServers.gitnexus = getMcpEntry();
     return existing;
 }
+/**
+ * Merge gitnexus entry into an OpenCode config JSON object.
+ * Returns the updated config.
+ */
+function mergeOpenCodeConfig(existing) {
+    if (!existing || typeof existing !== 'object') {
+        existing = {};
+    }
+    if (!existing.mcp || typeof existing.mcp !== 'object') {
+        existing.mcp = {};
+    }
+    existing.mcp.gitnexus = getOpenCodeMcpEntry();
+    return existing;
+}
 /**
  * Try to read a JSON file, returning null if it doesn't exist or is invalid.
  */
@@ -76,6 +114,53 @@ async function dirExists(dirPath) {
         return false;
     }
 }
+/**
+ * Check if a regular file exists.
+ */
+async function fileExists(filePath) {
+    try {
+        const stat = await fs.stat(filePath);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Escape a value for TOML string literals.
+ */
+function toTomlString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function buildCodexMcpTable() {
+    const entry = getMcpEntry();
+    return [
+        '[mcp_servers.gitnexus]',
+        `command = ${toTomlString(entry.command)}`,
+        `args = [${entry.args.map(toTomlString).join(', ')}]`,
+    ].join('\n');
+}
+function mergeCodexConfig(existingRaw) {
+    const table = buildCodexMcpTable();
+    const normalized = existingRaw.replace(/\r\n/g, '\n');
+    const tablePattern = /\[mcp_servers\.gitnexus\][\s\S]*?(?=\n\[[^\]]+\]|\s*$)/m;
+    if (tablePattern.test(normalized)) {
+        return normalized.replace(tablePattern, table).trimEnd() + '\n';
+    }
+    const trimmed = normalized.trimEnd();
+    if (trimmed.length === 0)
+        return `${table}\n`;
+    return `${trimmed}\n\n${table}\n`;
+}
+async function resolveOpenCodeConfigPath(opencodeDir) {
+    const preferredPath = path.join(opencodeDir, 'opencode.json');
+    const legacyPath = path.join(opencodeDir, 'config.json');
+    if (await fileExists(preferredPath))
+        return preferredPath;
+    if (await fileExists(legacyPath))
+        return legacyPath;
+    return preferredPath;
+}
 // ─── Editor-specific setup ─────────────────────────────────────────
 async function setupCursor(result) {
     const cursorDir = path.join(os.homedir(), '.cursor');
@@ -125,6 +210,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.
@@ -184,15 +281,12 @@ async function setupOpenCode(result) {
         result.skipped.push('OpenCode (not installed)');
         return;
     }
-    const configPath = path.join(opencodeDir, 'config.json');
+    const configPath = await resolveOpenCodeConfigPath(opencodeDir);
     try {
         const existing = await readJsonFile(configPath);
-        const config = existing || {};
-        if (!config.mcp)
-            config.mcp = {};
-        config.mcp.gitnexus = getMcpEntry();
+        const config = mergeOpenCodeConfig(existing);
         await writeJsonFile(configPath, config);
-        result.configured.push('OpenCode');
+        result.configured.push(`OpenCode (${path.basename(configPath)})`);
     }
     catch (err) {
         result.errors.push(`OpenCode: ${err.message}`);
@@ -212,6 +306,60 @@ 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 setupProjectCodex(repoRoot, result) {
+    const codexConfigPath = path.join(repoRoot, '.codex', 'config.toml');
+    try {
+        let existingRaw = '';
+        try {
+            existingRaw = await fs.readFile(codexConfigPath, 'utf-8');
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                throw err;
+        }
+        const merged = mergeCodexConfig(existingRaw);
+        await fs.mkdir(path.dirname(codexConfigPath), { recursive: true });
+        await fs.writeFile(codexConfigPath, merged, 'utf-8');
+        result.configured.push(`Project Codex MCP (${path.relative(repoRoot, codexConfigPath)})`);
+    }
+    catch (err) {
+        result.errors.push(`Project Codex MCP: ${err.message}`);
+    }
+}
+async function setupProjectOpenCode(repoRoot, result) {
+    const opencodePath = path.join(repoRoot, 'opencode.json');
+    try {
+        const existing = await readJsonFile(opencodePath);
+        const merged = mergeOpenCodeConfig(existing);
+        await writeJsonFile(opencodePath, merged);
+        result.configured.push(`Project OpenCode MCP (${path.relative(repoRoot, opencodePath)})`);
+    }
+    catch (err) {
+        result.errors.push(`Project OpenCode 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 +421,22 @@ 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;
+    let agent;
+    try {
+        scope = resolveSetupScope(options.scope);
+        agent = resolveSetupAgent(options.agent);
+    }
+    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 +445,41 @@ 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') {
+        // Configure only the selected agent MCP
+        if (agent === 'claude') {
+            await setupClaudeCode(result);
+            // Claude-only hooks should only be installed when Claude is selected.
+            await installClaudeCodeHooks(result);
+        }
+        else if (agent === 'opencode') {
+            await setupOpenCode(result);
+        }
+        else if (agent === 'codex') {
+            await setupCodex(result);
+        }
+        // Install shared global skills once
+        await installGlobalAgentSkills(result);
+    }
+    else {
+        const repoRoot = getGitRoot(process.cwd());
+        if (!repoRoot) {
+            console.log('  --scope project requires running inside a git repository\n');
+            process.exitCode = 1;
+            return;
+        }
+        if (agent === 'claude') {
+            await setupProjectMcp(repoRoot, result);
+        }
+        else if (agent === 'codex') {
+            await setupProjectCodex(repoRoot, result);
+        }
+        else if (agent === 'opencode') {
+            await setupProjectOpenCode(repoRoot, result);
+        }
+        await installProjectAgentSkills(repoRoot, result);
+    }
+    await saveSetupScope(scope, result);
     // Print results
     if (result.configured.length > 0) {
         console.log('  Configured:');
@@ -318,6 +503,8 @@ export const setupCommand = async () => {
     }
     console.log('');
     console.log('  Summary:');
+    console.log(`    Scope: ${scope}`);
+    console.log(`    Agent: ${agent}`);
     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

@@ -10,20 +10,63 @@ const execFileAsync = promisify(execFile);
 const here = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(here, '..', '..');
 const cliPath = path.join(packageRoot, 'dist', 'cli', 'index.js');
-test('setup installs global skills under ~/.agents/skills/gitnexus', async () => {
+async function runSetup(args, env, cwd = packageRoot) {
+    return execFileAsync(process.execPath, [cliPath, 'setup', ...args], { cwd, env });
+}
+test('setup requires --agent', async () => {
+    const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
+    try {
+        try {
+            await runSetup([], {
+                ...process.env,
+                HOME: fakeHome,
+                USERPROFILE: fakeHome,
+            });
+            assert.fail('expected setup without --agent to fail');
+        }
+        catch (err) {
+            assert.equal(typeof err?.stdout, 'string');
+            assert.match(err.stdout, /Missing --agent/);
+        }
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+    }
+});
+test('setup rejects invalid --agent', async () => {
     const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
     try {
-        await execFileAsync(process.execPath, [cliPath, 'setup'], {
-            cwd: packageRoot,
-            env: {
+        try {
+            await runSetup(['--agent', 'cursor'], {
                 ...process.env,
                 HOME: fakeHome,
                 USERPROFILE: fakeHome,
-            },
+            });
+            assert.fail('expected setup with invalid --agent to fail');
+        }
+        catch (err) {
+            assert.equal(typeof err?.stdout, 'string');
+            assert.match(err.stdout, /Invalid --agent value/);
+        }
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+    }
+});
+test('setup installs global skills under ~/.agents/skills/gitnexus', async () => {
+    const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
+    try {
+        await runSetup(['--agent', 'claude'], {
+            ...process.env,
+            HOME: fakeHome,
+            USERPROFILE: fakeHome,
         });
         const skillPath = path.join(fakeHome, '.agents', 'skills', 'gitnexus', 'gitnexus-exploring', 'SKILL.md');
+        const configPath = path.join(fakeHome, '.gitnexus', 'config.json');
         await fs.access(skillPath);
-        assert.ok(true);
+        const configRaw = await fs.readFile(configPath, 'utf-8');
+        const config = JSON.parse(configRaw);
+        assert.equal(config.setupScope, 'global');
     }
     finally {
         await fs.rm(fakeHome, { recursive: true, force: true });
@@ -59,14 +102,11 @@ process.exit(0);
         else {
             await fs.writeFile(codexShimPath, `#!/usr/bin/env node\n${shimLogic}`, { mode: 0o755 });
         }
-        await execFileAsync(process.execPath, [cliPath, 'setup'], {
-            cwd: packageRoot,
-            env: {
-                ...process.env,
-                HOME: fakeHome,
-                USERPROFILE: fakeHome,
-                PATH: `${fakeBin}${path.delimiter}${process.env.PATH || ''}`,
-            },
+        await runSetup(['--agent', 'codex'], {
+            ...process.env,
+            HOME: fakeHome,
+            USERPROFILE: fakeHome,
+            PATH: `${fakeBin}${path.delimiter}${process.env.PATH || ''}`,
         });
         const outputPath = path.join(fakeHome, '.codex', 'gitnexus-mcp-add.json');
         const raw = await fs.readFile(outputPath, 'utf-8');
@@ -80,3 +120,149 @@ process.exit(0);
         await fs.rm(fakeBin, { recursive: true, force: true });
     }
 });
+test('setup configures OpenCode MCP in ~/.config/opencode/opencode.json', async () => {
+    const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
+    try {
+        const opencodeDir = path.join(fakeHome, '.config', 'opencode');
+        await fs.mkdir(opencodeDir, { recursive: true });
+        await runSetup(['--agent', 'opencode'], {
+            ...process.env,
+            HOME: fakeHome,
+            USERPROFILE: fakeHome,
+        });
+        const opencodeConfigPath = path.join(opencodeDir, 'opencode.json');
+        const opencodeRaw = await fs.readFile(opencodeConfigPath, 'utf-8');
+        const opencodeConfig = JSON.parse(opencodeRaw);
+        assert.equal(opencodeConfig.mcp?.gitnexus?.type, 'local');
+        assert.deepEqual(opencodeConfig.mcp?.gitnexus?.command, ['npx', '-y', 'gitnexus@latest', 'mcp']);
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+    }
+});
+test('setup keeps using legacy ~/.config/opencode/config.json when it already exists', async () => {
+    const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
+    try {
+        const opencodeDir = path.join(fakeHome, '.config', 'opencode');
+        const legacyConfigPath = path.join(opencodeDir, 'config.json');
+        const preferredConfigPath = path.join(opencodeDir, 'opencode.json');
+        await fs.mkdir(opencodeDir, { recursive: true });
+        await fs.writeFile(legacyConfigPath, JSON.stringify({ existing: true }, null, 2), 'utf-8');
+        await runSetup(['--agent', 'opencode'], {
+            ...process.env,
+            HOME: fakeHome,
+            USERPROFILE: fakeHome,
+        });
+        const legacyRaw = await fs.readFile(legacyConfigPath, 'utf-8');
+        const legacyConfig = JSON.parse(legacyRaw);
+        assert.equal(legacyConfig.existing, true);
+        assert.equal(legacyConfig.mcp?.gitnexus?.type, 'local');
+        assert.deepEqual(legacyConfig.mcp?.gitnexus?.command, ['npx', '-y', 'gitnexus@latest', 'mcp']);
+        await assert.rejects(fs.access(preferredConfigPath));
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+    }
+});
+test('setup --agent opencode does not install Claude hooks', async () => {
+    const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
+    try {
+        const opencodeDir = path.join(fakeHome, '.config', 'opencode');
+        const claudeDir = path.join(fakeHome, '.claude');
+        const claudeSettingsPath = path.join(claudeDir, 'settings.json');
+        const claudeHookPath = path.join(claudeDir, 'hooks', 'gitnexus', 'gitnexus-hook.cjs');
+        await fs.mkdir(opencodeDir, { recursive: true });
+        await fs.mkdir(claudeDir, { recursive: true });
+        await runSetup(['--agent', 'opencode'], {
+            ...process.env,
+            HOME: fakeHome,
+            USERPROFILE: fakeHome,
+        });
+        await assert.rejects(fs.access(claudeSettingsPath));
+        await assert.rejects(fs.access(claudeHookPath));
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+    }
+});
+test('setup --scope project --agent claude writes only .mcp.json', 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 });
+        await runSetup(['--scope', 'project', '--agent', 'claude'], {
+            ...process.env,
+            HOME: fakeHome,
+            USERPROFILE: fakeHome,
+        }, fakeRepo);
+        const projectMcpPath = path.join(fakeRepo, '.mcp.json');
+        const codexConfigPath = path.join(fakeRepo, '.codex', 'config.toml');
+        const opencodeConfigPath = path.join(fakeRepo, 'opencode.json');
+        const projectMcpRaw = await fs.readFile(projectMcpPath, 'utf-8');
+        const projectMcp = JSON.parse(projectMcpRaw);
+        assert.equal(projectMcp.mcpServers?.gitnexus?.command, 'npx');
+        await assert.rejects(fs.access(codexConfigPath));
+        await assert.rejects(fs.access(opencodeConfigPath));
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+        await fs.rm(fakeRepo, { recursive: true, force: true });
+    }
+});
+test('setup --scope project --agent codex writes only .codex/config.toml', 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 });
+        await runSetup(['--scope', 'project', '--agent', 'codex'], {
+            ...process.env,
+            HOME: fakeHome,
+            USERPROFILE: fakeHome,
+        }, fakeRepo);
+        const projectMcpPath = path.join(fakeRepo, '.mcp.json');
+        const codexConfigPath = path.join(fakeRepo, '.codex', 'config.toml');
+        const opencodeConfigPath = path.join(fakeRepo, 'opencode.json');
+        const codexConfigRaw = await fs.readFile(codexConfigPath, 'utf-8');
+        assert.match(codexConfigRaw, /\[mcp_servers\.gitnexus\]/);
+        assert.match(codexConfigRaw, /command = "npx"/);
+        await assert.rejects(fs.access(projectMcpPath));
+        await assert.rejects(fs.access(opencodeConfigPath));
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+        await fs.rm(fakeRepo, { recursive: true, force: true });
+    }
+});
+test('setup --scope project --agent opencode writes only opencode.json', 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 });
+        await runSetup(['--scope', 'project', '--agent', 'opencode'], {
+            ...process.env,
+            HOME: fakeHome,
+            USERPROFILE: fakeHome,
+        }, fakeRepo);
+        const projectMcpPath = path.join(fakeRepo, '.mcp.json');
+        const codexConfigPath = path.join(fakeRepo, '.codex', 'config.toml');
+        const opencodeConfigPath = path.join(fakeRepo, 'opencode.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 opencodeRaw = await fs.readFile(opencodeConfigPath, 'utf-8');
+        const opencodeConfig = JSON.parse(opencodeRaw);
+        const configRaw = await fs.readFile(configPath, 'utf-8');
+        const config = JSON.parse(configRaw);
+        assert.equal(opencodeConfig.mcp?.gitnexus?.type, 'local');
+        assert.deepEqual(opencodeConfig.mcp?.gitnexus?.command, ['npx', '-y', 'gitnexus@latest', 'mcp']);
+        await assert.rejects(fs.access(projectMcpPath));
+        await assert.rejects(fs.access(codexConfigPath));
+        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.7",
   "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",