Set up the toolchain

Skill re-setup. Install and check the reverse-engineering toolchain (Ghidra, JDK 21, Python with Unicorn/pefile/capstone, objdump, Node for REA, Zig for the sample) and register the REA MCP server for the agent. Use at the start of a project, when a tool is missing or fails to start, or when REA tools do not appear in the session.

Copy this prompt into your coding agent. Replace the part in angle brackets.

In my GameFrame project, use the re-setup skill for <the task>.
Read the skill first and follow its steps in order.
Report the evidence it asks for, with its label: observed, measured, inferred or unknown.

1. Check, then install

scripts/setup.sh              # a table: ok / MISSING for each tool, with a hint
scripts/setup.sh --install    # installs what is missing (Homebrew on macOS, apt on Debian/Ubuntu)
                              # and creates .venv with requirements.txt

./gameframe doctor runs the same check, and passes options on (./gameframe doctor --install). ./gameframe run NAME ARGS then runs any Python tool with the .venv.

The script writes .env with GHIDRA_INSTALL_DIR and JAVA_HOME once both are found. Every script and .mcp.json read these, so set them there if your installs are elsewhere.

Sizes (tell the user before installing on their machine if they have not approved it): Ghidra about 500 MB, JDK 21 about 300 MB, the Python packages about 40 MB, Zig about 200 MB (only for building the sample game).

On Linux, Ghidra is not packaged: download the release zip from https://github.com/NationalSecurityAgency/ghidra/releases, unzip it, and put its folder in GHIDRA_INSTALL_DIR. On Windows, use WSL2 and follow the Linux steps.

On Linux, in a container or in a cloud agent's workspace, read docs/working/environments.md as well. In each new shell, source scripts/env.sh loads .env and puts gameframe and the .venv Python on PATH.

2. Prove it works

tests/run.sh            # ~20 s: builds the sample game, runs every tool against it
tests/run.sh --ghidra   # + a real Ghidra export (~1 min)

All checks must pass. A failure names the tool and shows its output.

3. REA (the reverse-engineering MCP server)

REA ("Reverse Engineer Anything", https://github.com/morluto/rea, npm package rea-agents) gives the agent tools to open binaries, archives, Android packages, .NET assemblies, browser pages and Electron apps, decompile through Ghidra, and keep every result as cited Evidence. See re-rea for when to use it.

• Claude Code: this repository has a project .mcp.json that starts REA with npx -y rea-agents@6.4.0 mcp, passing GHIDRA_INSTALL_DIR and JAVA_HOME. Claude Code asks once to approve project MCP servers; after that the mcp__rea__* tools appear.
• Other agents (Codex, Cursor, Gemini CLI, Windsurf...): use REA's own setup, which writes the client's MCP configuration and installs REA's skill:

  scripts/setup.sh --rea                          # dry run: shows the plan for Claude Code
  REA_CLIENT=codex scripts/setup.sh --rea         # the plan for another client
  npx -y rea-agents@6.4.0 setup --client codex --yes   # apply, after the user agrees

• REA's own skill (reverse-engineer-anything) explains every tool. Install it with REA's setup, or from its repository.

REA lists the hosts it supports. On others (for example Debian 13) its doctor warns, but the MCP connection, Ghidra-backed tools and the sample checks have worked. Try REA on the sample game before relying on it.

Ghidra analysis of a large binary can take minutes, longer than many clients wait for one tool call. Raise the client's tool timeout for REA (in Codex, tool_timeout_sec in the server's entry).

If REA tools do not appear: restart the agent (MCP servers start with the session), then check npx -y rea-agents@6.4.0 doctor --client claude_code --json. A tool that reports provider_unavailable usually means Ghidra or Java is not where .env says.

4. DOS games: DOSBox-X and its debugger

• DOSBox-X: scripts/setup.sh --install (on macOS the formula, brew install --formula dosbox-x; the cask is disabled for failing Gatekeeper). Homebrew's build has the heavy debugger; brew install --HEAD --formula dosbox-x adds the newest commands (STEPIN). Check: scripts/dosbox-run.sh on the DOS sample prints exit code 23 (tests/run.sh does this).
• The debugger control channel needs DOSBox-X 2026.10 or later, built with the debugger. dosbox-run.sh --mcp, tools/dos/dbx_control.py and the dosbox MCP server all use it. Distribution packages are often older (Debian 13 ships a 2025 build). scripts/setup.sh then shows a dosbox-x debugger OLD row, --mcp stops with a message, and the debugger test is skipped. Build a current one on Linux (ask the user first: it is a download and a long build):

  sudo apt install libtool autogen autoconf automake libncurses-dev gcc g++ make nasm \
    libsdl2-dev libsdl2-net-dev libpcap-dev libslirp-dev fluidsynth libfluidsynth-dev \
    libavformat-dev libavcodec-dev libavcodec-extra libswscale-dev libfreetype-dev \
    libxkbfile-dev libxrandr-dev
  git clone --depth 1 https://github.com/joncampbell123/dosbox-x.git
  cd dosbox-x && ./build-debug-sdl2      # SDL2 with the heavy debugger

  The package list follows DOSBox-X's BUILD.md; the debugger needs libncurses-dev. Use the repository's build script. It passes the compiler flags the code needs; a plain ./configure && make with a newer compiler can stop on a warning treated as an error. Put the result on PATH (or sudo make install) and run scripts/setup.sh again.
• The debugger MCP server for agents (ask the user first: it is a download and a build): cargo install --git https://github.com/caiiiycuk/dosbox-x-mcp-server --tag v0.1.2 --locked. .mcp.json registers it as dosbox (set DOSBOX_X_MCP_SERVER to its path if it is not on PATH). Restart the agent session so the tools load, ask dosbox_mcp_port, then run scripts/dosbox-run.sh --mcp PORT ....

Common problems

• dosbox-x not found after brew install --HEAD: run brew link dosbox-x.
• dbx_control or the dosbox MCP server times out waiting for DOSBox-X: check that scripts/setup.sh shows no OLD row. An older DOSBox-X ignores mcp_server and never connects.

Symptom	Cause and fix
Ghidra not found	Set GHIDRA_INSTALL_DIR in .env to the folder that contains support/analyzeHeadless
Ghidra exits with UnsupportedClassVersionError	Wrong Java: set JAVA_HOME to a JDK 21
Ghidra runs out of memory on a large game	MAXMEM=16G scripts/ghidra-export.sh ...
Unable to lock project	Another headless job uses the same Ghidra project: wait, or pass --project
pip install unicorn fails to build	Use a Python version that has a Unicorn wheel (3.10 to 3.13 are safest): PYTHON=python3.12
The sample game does not build	Install Zig (brew install zig, or https://ziglang.org/download)

Working in a git worktree

A worktree has no target/, analysis/ or .venv. Symlink them from the main checkout and add them to $(git rev-parse --git-common-dir)/info/exclude (a symlink is not matched by a /target/ rule in .gitignore).