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

> Learn to configure AI client integration with Claude Code, Codex, Cursor, and Windsurf. Follow simple steps to set up your development environment for the reverse-skill repository.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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:

```json
{
  "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
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1

```

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

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

```

According to the source documentation in [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```json
{
  "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
bash skills/scripts/refresh-tool-index.sh

```

Trigger routing directly from the Codex CLI prompt:

```bash
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:

```json
{
  "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
bash skills/scripts/refresh-tool-index.sh

```

From Cursor, invoke the router via the built-in **Run Script** UI, selecting [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

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

```

Refresh the tool index on Windows:

```powershell
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:

```powershell

# 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:

```bash

# 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:

```yaml
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) on Unix).
- **Router returns "auth not granted"**: The [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), and [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) (Unix) after installing new tools to regenerate [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md).
- Invoke `skills/scripts/master-route.ps1` or [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) and [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.