# How to Set Up reverse-skill on macOS: Complete Installation Guide > Install reverse-skill on macOS with our complete guide. Run bootstrap-reverse.sh via Homebrew, refresh the tool index, and optionally register MCP hosts for AI clients. - Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill) - Tags: how-to-guide - Published: 2026-08-22 --- **To set up reverse-skill on macOS, run the [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh) script to install the security toolset via Homebrew, refresh the local tool index with [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md) specifies standard Unix utilities, language runtimes, and common reverse-engineering tools. ```bash # 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: ```bash 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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. ```bash # 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: ```bash # 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) writes to [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) and [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md), which the router consults to determine if a capability is ready for invocation. ```bash /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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md): ```bash 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: ```bash /bin/bash skills/scripts/bootstrap-reverse.sh apk-reverse --mcp-host=claude ``` ## Summary - The **bootstrap script** ([`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh)** generates the tool index that powers the routing decisions. - **Routing rules** are defined in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and consulted by the master route scripts. - All platform-specific setup logic is documented in [`docs/platforms/macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) script generates [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) and [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) to update the capability snapshot so the router recognizes the new additions.