How to Set Up reverse-skill on macOS: Complete Installation Guide

To set up reverse-skill on macOS, run the bootstrap-reverse.sh script to install the security toolset via Homebrew, refresh the local tool index with refresh-tool-index.sh, and optionally register MCP hosts for AI clients like Claude or Codex.

reverse-skill is a platform-neutral security-skill router that discovers appropriate tooling for reverse-engineering and penetration-testing tasks. Setting it up on macOS involves executing a generic bootstrap system that prepares your environment using Homebrew, pipx, and npm, leaving your AI client configurations untouched unless you explicitly request MCP host registration.

Prerequisites and Baseline Setup

Before running the router, install Homebrew and the baseline security toolkit. The setup guide in docs/platforms/macos.md specifies standard Unix utilities, language runtimes, and common reverse-engineering tools.

# Install Homebrew (skip if already present)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install baseline security toolset

brew install git curl wget jq unzip gnu-tar python node openjdk \
    jadx apktool android-platform-tools radare2 graphviz plantuml \
    nmap sqlmap ffuf hashcat binwalk

You also need pipx to manage Python-based security tools in isolated environments:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Run the Bootstrap Script

The entry point for macOS is skills/scripts/bootstrap-reverse.sh, which adapts the generic routing layer to the host OS. This script installs and prepares supported capabilities without writing client-specific configuration files.

# Basic bootstrap for specific tools

/bin/bash skills/scripts/bootstrap-reverse.sh \
    jadx apktool frida radare2 ghidra burpsuite-mcp

To simultaneously register MCP servers for AI clients, append the --mcp-host flag:

# Register both Claude and Codex MCP hosts during setup

/bin/bash skills/scripts/bootstrap-reverse.sh \
    jadx apktool frida radare2 ghidra burpsuite-mcp \
    --mcp-host=both

Refresh the Tool Index

After bootstrapping, generate the tool index to create a snapshot of available capabilities. The script skills/scripts/refresh-tool-index.sh writes to skills/tool-index.json and skills/tool-index.md, which the router consults to determine if a capability is ready for invocation.

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

Understanding the Core Architecture

Several components work together to enable the routing functionality:

• skills/config/routing.json – The single source of truth for routing rules (R0-R44) that the router consults.
• skills/scripts/master-route.ps1 – The primary fast-track entry point used by AI clients to invoke routing logic.
• Tool Index – A lightweight JSON/MD snapshot generated by the refresh script, enabling the router to detect locally available tools.
• MCP Bridge – Optional JSON configuration files (e.g., ~/.claude/mcp.json, ~/.codex/config.toml) created only when you specify --mcp-host during bootstrap.

Verify the Installation

Validate your environment using the checklist from docs/platforms/macos.md:

java -version
python3 --version
node -v
npx -y @jshookmcp/jshook@0.3.4 --help
bash skills/scripts/refresh-tool-index.sh

To run a specific skill immediately after setup:

/bin/bash skills/scripts/bootstrap-reverse.sh apk-reverse --mcp-host=claude

Summary

• The bootstrap script (skills/scripts/bootstrap-reverse.sh) is the macOS entry point that installs tools via Homebrew, pipx, and npm.
• The system remains client-neutral unless you explicitly pass --mcp-host to register Claude, Codex, or other AI client configurations.
• skills/scripts/refresh-tool-index.sh generates the tool index that powers the routing decisions.
• Routing rules are defined in skills/config/routing.json and consulted by the master route scripts.
• All platform-specific setup logic is documented in docs/platforms/macos.md, which includes the complete tool matrix and validation checklist.

Frequently Asked Questions

Does reverse-skill modify existing AI client configurations?

No. The bootstrap script does not write any client-specific configuration files unless you explicitly request an MCP host using flags like --mcp-host=claude or --mcp-host=codex. By default, the setup remains entirely client-neutral.

Can I install reverse-skill without Homebrew?

Homebrew is the recommended and supported method for macOS according to the source code. The bootstrap script relies on Homebrew formulas to install baseline dependencies like git, curl, python, and security tools such as jadx and radare2. Manual installation of these dependencies would be required to bypass Homebrew.

What is the purpose of the tool index?

The tool index acts as a capability registry. The refresh-tool-index.sh script generates skills/tool-index.json and skills/tool-index.md to record which tools are actually installed and available locally. The router consults this index before invoking a skill to ensure the required binary or runtime is present.

How do I add new reverse-engineering tools after initial setup?

Re-run the bootstrap script with the new tool names. The bootstrap-reverse.sh script is idempotent for existing tools and will install only the missing capabilities. After adding tools, execute skills/scripts/refresh-tool-index.sh to update the capability snapshot so the router recognizes the new additions.

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