How to Configure AI Client Integration with Claude Code, Codex, Cursor, and Windsurf

To configure AI client integration with Claude Code, Codex CLI, Cursor, and Windsurf in the reverse-skill repository, create a client-specific MCP configuration file pointing to the repository root, execute the platform-specific tool-index refresh script, and invoke the master routing script to dispatch tasks.

The reverse-skill repository implements a deliberately client-neutral architecture for AI-assisted security research. Because all routing logic resides in shared files rather than editor-specific plugins, you can configure any supported AI client by establishing a standardized integration contract that points the client at the central routing matrix and tool inventory.

Core Architecture and Shared Components

The integration relies on four critical files that every AI client must access. These files enforce a consistent "read-only → auth → ACT" lifecycle regardless of which editor you use.

• RULES.md: Located at the repository root, this file serves as the single source of truth for routing behavior and authentication gates. Every client must read this file first to determine when to stop acting and hand off to the router.
• skills/config/routing.json: This JSON matrix maps task hints to concrete skill modules. All four clients reference this identical file; no client-specific routing code exists.
• skills/tool-index.md: An auto-generated inventory of locally detected MCP servers, scripts, and binaries. Clients must refresh this index once per platform before invoking tools.
• skills/scripts/master-route.ps1 (Windows) and skills/scripts/master-route.sh (Unix): The primary entry points that read the routing matrix and dispatch appropriate skills.

Claude Code Configuration

Claude Code expects its configuration in ~/.claude/mcp.json.

Create the configuration file with the following JSON structure, replacing <REPO_ROOT> with the absolute path to your cloned repository:

{
  "repoRoot": "<REPO_ROOT>",
  "rulesPath": "RULES.md",
  "routingPath": "skills/config/routing.json",
  "toolIndexPath": "skills/tool-index.md"
}

After creating the file, refresh the tool index for your platform. On Windows, execute:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1

To route a task, invoke the primary router with the task hint:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 "<task hint>"

According to the source documentation in README_AI.md (lines 5-9 and 344-379), this configuration establishes the minimal viable contract for Claude Code integration.

Codex CLI Configuration

Codex CLI follows the same layout as Claude Code but stores settings in ~/.codex/settings.local.json.

Create the file with this structure:

{
  "repoRoot": "<REPO_ROOT>",
  "rulesFile": "RULES.md",
  "routingFile": "skills/config/routing.json",
  "toolIndex": "skills/tool-index.md"
}

Refresh the tool index on Linux or macOS:

bash skills/scripts/refresh-tool-index.sh

Trigger routing directly from the Codex CLI prompt:

codex run skills/scripts/master-route.sh "<task hint>"

Cursor Configuration

Cursor treats the repository as an AI Plugin and expects configuration in ~/.cursor/ai-plugin.json.

Create the file with the following structure:

{
  "mcp": {
    "repoRoot": "<REPO_ROOT>",
    "rules": "RULES.md",
    "routing": "skills/config/routing.json",
    "toolIndex": "skills/tool-index.md"
  }
}

Rebuild the tool index using the Unix script:

bash skills/scripts/refresh-tool-index.sh

From Cursor, invoke the router via the built-in Run Script UI, selecting master-route.sh and supplying the task hint as an argument.

Windsurf Configuration

Windsurf uses YAML-based configuration stored in ~/.windsurf/config.yaml.

Create the file with this structure:

mcp:
  repoRoot: "<REPO_ROOT>"
  rules: "RULES.md"
  routing: "skills/config/routing.json"
  toolIndex: "skills/tool-index.md"

Refresh the tool index on Windows:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1

Execute the router from Windsurf's Command Palette:

Run: skills/scripts/master-route.ps1 "<task hint>"

Practical Setup Examples

Windows Setup for Claude Code

This PowerShell example automates the complete setup for Claude Code on Windows:

# Configure paths

$repo = "C:\Users\you\reverse-skill"

# Create config directory and file

New-Item -Path "$env:USERPROFILE\.claude" -ItemType Directory -Force
@{
  repoRoot      = $repo
  rulesPath    = "RULES.md"
  routingPath  = "skills/config/routing.json"
  toolIndexPath= "skills/tool-index.md"
} | ConvertTo-Json -Depth 4 | Set-Content "$env:USERPROFILE\.claude\mcp.json"

# Refresh tool index

powershell -NoProfile -ExecutionPolicy Bypass -File "$repo\skills\scripts\refresh-tool-index.ps1"

# Example: Route a pentest task

powershell -NoProfile -ExecutionPolicy Bypass -File "$repo\skills\scripts\master-route.ps1" "pentest-web-xss"

macOS/Linux Setup for Codex CLI

This bash script automates setup for Codex CLI on Unix systems:

# Define repository path

REPO=$HOME/reverse-skill

# Create config directory and file

mkdir -p $HOME/.codex
cat > $HOME/.codex/settings.local.json <<EOF
{
  "repoRoot": "$REPO",
  "rulesFile": "RULES.md",
  "routingFile": "skills/config/routing.json",
  "toolIndex": "skills/tool-index.md"
}
EOF

# Refresh tool index

bash $REPO/skills/scripts/refresh-tool-index.sh

# Invoke router for Android reversing task

codex run $REPO/skills/scripts/master-route.sh "android-reversing"

Windsurf YAML Configuration

For Windsurf on any platform, ensure your ~/.windsurf/config.yaml contains:

mcp:
  repoRoot: "/home/you/reverse-skill"
  rules: "RULES.md"
  routing: "skills/config/routing.json"
  toolIndex: "skills/tool-index.md"

Troubleshooting Common Integration Issues

When configuring AI client integration with Claude Code, Codex, Cursor, and Windsurf, you may encounter these specific failures:

• Client cannot find tool-index.md: This occurs when refresh-tool-index has not been executed after adding new tools. Remedy this by re-running the appropriate platform script (refresh-tool-index.ps1 on Windows or refresh-tool-index.sh on Unix).
• Router returns "auth not granted": The RULES.md file requires a case initialization step before any ACT operations. Run skills/scripts/case-init.ps1 (or the .sh variant) to generate work/<case>/scope.md before invoking the router.
• AI client "does nothing": The client's MCP configuration likely points to the wrong repository root. Verify that the absolute path in the client-specific config file matches your actual clone location.

All behaviors are enforced by RULES.md, which mandates the read-only → auth → ACT lifecycle for every supported client.

Summary

• The reverse-skill repository uses a client-neutral architecture where RULES.md, skills/config/routing.json, and skills/tool-index.md provide the single source of truth for all AI clients.
• Claude Code uses ~/.claude/mcp.json, Codex CLI uses ~/.codex/settings.local.json, Cursor uses ~/.cursor/ai-plugin.json, and Windsurf uses ~/.windsurf/config.yaml.
• Every configuration must specify the absolute repoRoot and paths to the rules, routing, and tool index files.
• Run skills/scripts/refresh-tool-index.ps1 (Windows) or skills/scripts/refresh-tool-index.sh (Unix) after installing new tools to regenerate skills/tool-index.md.
• Invoke skills/scripts/master-route.ps1 or skills/scripts/master-route.sh with a task hint to dispatch work to the appropriate skill module.
• The integration contract requires no client-specific code in the core router; each editor simply loads the shared configuration and executes the standard routing scripts.

Frequently Asked Questions

What makes the reverse-skill repository "client-neutral"?

The repository stores all routing logic, test suites, and tool orchestration under skills/ without dependencies on specific AI editor APIs. According to the source code in AGENTS.md and README_AI.md, each client loads the repository through a thin adapter layer consisting solely of a configuration file that points to shared resources like RULES.md and routing.json. This design ensures that Claude Code, Codex CLI, Cursor, and Windsurf all consume identical routing logic.

Why must I run the refresh-tool-index script before using the client?

The skills/tool-index.md file is an auto-generated inventory of locally detected MCP servers, scripts, and binaries specific to your platform. The skills/scripts/refresh-tool-index.* scripts scan the environment and rebuild this index. If you skip this step, the master routing script cannot locate available tools, resulting in "tool not found" errors when dispatching tasks.

Can I use the same repository clone for multiple AI clients simultaneously?

Yes. Because the integration contract only requires a client-specific configuration file pointing to the repository root, you can configure Claude Code, Codex CLI, Cursor, and Windsurf to reference the same reverse-skill clone concurrently. Each client will read the same RULES.md and routing.json files, ensuring consistent behavior across editors while maintaining separate configuration namespaces in their respective home directories.

What is the "read-only → auth → ACT" lifecycle mentioned in RULES.md?

This lifecycle enforces safety and authorization checks before executing destructive operations. The router first operates in read-only mode to analyze the task, then requires explicit authorization via skills/scripts/case-init.ps1 (which creates work/<case>/scope.md), and only then permits ACT operations that modify systems or execute tools. This pattern applies universally across all supported AI clients as implemented in the repository's core routing logic.

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