gitnexus setup

One-time configuration for MCP integration with AI editors

The setup command automatically detects installed AI editors and configures MCP integration so they can access the GitNexus knowledge graph.

Usage

gitnexus setup

This is a one-time global command. You only need to run it once after installing GitNexus.

What It Does

The setup command:

1. Detects installed editors (Cursor, Claude Code, OpenCode, Windsurf)
2. Writes MCP configuration to each editor’s global config file
3. Installs agent skills for editors that support them
4. Registers Claude Code hooks for automatic context enrichment

Supported Editors

Editor	MCP	Skills	Hooks	Config Location
Claude Code	✅	✅	✅	~/.claude/settings.json
Cursor	✅	✅	—	~/.cursor/mcp.json
OpenCode	✅	✅	—	~/.config/opencode/config.json
Windsurf	✅	—	—	Manual setup required

Output

  GitNexus Setup
  ==============

  Configured:
    + Cursor
    + Claude Code (MCP manual step printed)
    + OpenCode
    + Claude Code skills (6 skills → ~/.claude/skills/)
    + Claude Code hooks (PreToolUse)
    + Cursor skills (6 skills → ~/.cursor/skills/)
    + OpenCode skills (6 skills → ~/.config/opencode/skill/)

  Skipped:
    - Windsurf (not installed)

  Summary:
    MCP configured for: Cursor, Claude Code, OpenCode
    Skills installed to: Claude Code skills, Cursor skills, OpenCode skills

  Next steps:
    1. cd into any git repo
    2. Run: gitnexus analyze
    3. Open the repo in your editor — MCP is ready!

MCP Configuration

The setup command writes the following MCP entry to each editor’s config:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

On Windows:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "gitnexus@latest", "mcp"]
}

Claude Code Special Setup

For Claude Code, you need to run an additional command after gitnexus setup:

claude mcp add gitnexus -- npx -y gitnexus mcp

This is printed during setup.

Skills Installation

The following agent skills are installed:

• gitnexus-exploring — Navigate unfamiliar code using the knowledge graph
• gitnexus-debugging — Trace bugs through call chains
• gitnexus-impact-analysis — Analyze blast radius before changes
• gitnexus-refactoring — Plan safe refactors using dependency mapping
• gitnexus-guide — Quick reference for all tools and workflows
• gitnexus-cli — CLI command reference

Skill Locations

Editor	Location
Claude Code	~/.claude/skills/gitnexus-*/
Cursor	~/.cursor/skills/gitnexus-*/
OpenCode	~/.config/opencode/skill/gitnexus-*/

Hooks Installation (Claude Code Only)

GitNexus registers a PreToolUse hook that automatically enriches grep/glob/bash calls with knowledge graph context.

Hook location: ~/.claude/hooks/gitnexus/gitnexus-hook.cjs

Configuration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Grep|Glob|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/gitnexus/gitnexus-hook.cjs",
            "timeout": 8000,
            "statusMessage": "Enriching with GitNexus graph context..."
          }
        ]
      }
    ]
  }
}

SessionStart hooks are disabled on Windows due to a Claude Code bug (#23576). Session context is delivered via CLAUDE.md instead.

Manual Configuration

If you prefer not to use gitnexus setup, you can configure manually:

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Claude Code

claude mcp add gitnexus -- npx -y gitnexus@latest mcp

OpenCode

Edit ~/.config/opencode/config.json:

{
  "mcp": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Windsurf

Add to ~/.windsurf/mcp.json (global) or project-specific config. Refer to Windsurf’s MCP documentation.

Verification

After running setup:

1. Index a repository:

   cd my-project
   npx gitnexus analyze
   

2. Open in your editor

3. Check MCP connection:

   • Claude Code: Should auto-connect on startup
   • Cursor: Check MCP status in settings
   • OpenCode: Check MCP panel

4. Test a tool:

   Use the query tool to search for "authentication"
   

Troubleshooting

Editor Not Detected

The setup command looks for these directories:

• Cursor: ~/.cursor/
• Claude Code: ~/.claude/
• OpenCode: ~/.config/opencode/

If your editor is installed but not detected, configure manually.

MCP Connection Fails

Ensure npx is available:

npx --version

Restart your editor after running setup.

Skills Not Appearing

Check skill installation:

ls ~/.claude/skills/  # Claude Code
ls ~/.cursor/skills/  # Cursor

Reindex your repository to generate per-repo skills:

gitnexus analyze

Next Steps

Index Repository

Run analyze to index your first repo

MCP Integration

Learn about MCP tools and workflows