morluto/rea

---

See a feature in an app that you want in your own product? Ask your agent to investigate it with REA. It can inspect the app without its source code, explain how the feature works, show the evidence, and build a version for your project.

REA connects your agent to tools for inspecting native binaries, JavaScript and Electron apps, .NET assemblies, and websites. You can also use the same tools from your terminal. Analysis runs locally, and results include the evidence and limitations behind each conclusion.

Setup registers REA with your agent and installs matching workflow instructions. Native analysis can use an existing Hopper or Ghidra installation; setup can optionally install Hopper with approval. Static JavaScript analysis needs neither engine.

Quick start

Run setup (recommended)

Set up REA with your agent:

npx rea-agents setup

Choose which supported agents should use REA, then review the exact paths and changes before approving. Existing REA registrations are selected by default; newly detected agents are available to select, but detection alone does not select them. Setup adds MCP access and REA's guided workflow for selected agents. Hopper is a separate optional choice with its own consent. Setup can also record an existing Ghidra installation.

Setup shows its changes before applying them and backs up existing configuration. See Installation and setup for requirements and setup options.

AI Coding Assistants (optional)

Add the skill to your AI coding assistant for richer context:

npx skills add morluto/rea --skill reverse-engineer-anything

The skill provides REA's investigation workflow. Run setup above to connect REA to your agent and configure analysis tools. Setup already installs a version-matched skill by default; this command installs the repository version.

With an agent (recommended)

After setup, restart your agent and describe the app or feature you want to understand. Hopper can run in demo mode; if it shows a first-run prompt, choose the demo or enter an existing license.

REA supports Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, Devin, OpenCode, Antigravity, GitHub Copilot CLI, Command Code, and VS Code. Existing REA registrations are selected by default during setup; other detected agents remain unselected until chosen. Other agents can use the manual MCP configuration.

First result from the terminal

For your extracted JavaScript/Electron application tree or ASAR, run:

npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json

Replace the path with your target (for example, "D:/apps/example" on Windows). This returns inline Evidence, recovered graph, limitations, and unknowns without MCP setup, Hopper, Ghidra, or executing the application. For a native app, configure its engine first, then use analyze with that app's path. Run doctor when you need diagnosis; it is not a prerequisite for each analysis.

Check readiness for the task at hand

rea doctor without options is an audit of the whole integration. It checks every detected agent registration, the installed skill, and every optional analysis engine, so it can report healthy: false while your current task works. Choose a readiness scope for the work you are doing:

| Task | Readiness check | | ----------------------------------- | -------------------------------------------------------------------------------------------- | | Static JavaScript/Electron analysis | None. Run analyze-javascript-application directly. | | Troubleshoot one analysis engine | rea doctor --provider ghidra --json (or hopper, ida) | | Check one agent's MCP registration | rea doctor --client codex --json (see client IDs) | | Check the installed skill | rea doctor --skill --json |

A scoped report has scope.mode: "explicit". Only scope_checks determine healthy and the exit status. Everything else is listed in informational_checks; you don't need to fix it for this task. For example, a missing engine you are not using needs no repair. environment_healthy still summarizes the full audit. --target adds a target check, but without a scope option the report remains audit-wide.

When more than one installed engine supports a native target, REA does not pick one: opening the target fails with code: "capability_unavailable", details.selection_reason: "ambiguous", and the providers in details.candidate_ids. Choose one once: pass --provider on the CLI or provider_id on open_binary, or set REA_ANALYSIS_PROVIDER as a standing preference. An explicit selector overrides the environment variable. The session keeps that choice and never falls back to another engine. Recovery depends on details.selection_reason. For ambiguous, choose one of the candidates. For provider_unavailable, the engine you selected needs repair, so run rea doctor --provider --json and follow its remediation. Neither reason means you have to install every engine. See Choosing a deep-analysis provider.

Install the rea command

Install the command-line interface:

curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash

The installer adds rea to your system and starts setup when run in a terminal. It requires Node.js and npm to be installed already.

Alternatively, install with npm, then run setup:

npm install --global rea-agents
rea setup

Update either installation with rea update.

Requirements

Static JavaScript inspection requires the Node/npm runtime only. Host and external-tool prerequisites depend on the selected workflow; the native provider guides describe their supported platforms.

• macOS 12 or newer
• Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, or CachyOS
• Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+
• npm; REA does not require or install a particular npm version

Deep native binary analysis requires Hopper, Ghidra, or IDA Pro. Hopper is separate software with its own license; its demo supports analysis with vendor-defined limits. Ghidra and IDA are bring-your-own providers.

Firmware region inspection and explicit extraction use caller-supplied Binwalk and Unblob on Linux. See Firmware analysis for setup, provenance, resource limits and native handoff.

Static APK analysis uses a separately supplied headless JADX JAR and a full JDK, with no emulator or APK execution. See Android analysis for setup, CLI/MCP operations, coverage and public test fixtures. Authenticated IPA and macOS .app, ZIP, or DMG inventory Evidence can be projected into bundle anatomy, such as XPC services, app extensions, login items, privileged helpers, and launchd plists, with Apple application analysis.

Repository main and npm 4.1.0 include experimental Windows x64 Ghidra support for native x86-64 PE applications on local NTFS, with bundled Job Object, private-DACL, and path-admission controls. Check the release boundary before expecting this from an older npm package. See Windows Ghidra P0 for prerequisites and verified scope.

If something is not working, run:

npx -y rea-agents@latest doctor

doctor checks your host, dependencies, analysis tools, and agent configuration without changing them. Use --json for structured diagnostics.

Linux installation and troubleshooting

On macOS, setup can install Hopper in ~/Applications after approval. It verifies the official download and does not need Homebrew or administrator privileges.

On supported Linux distributions, setup can install Hopper and its demo-session dependencies through your system package manager. You may see a system authorization prompt. Demo sessions use a private virtual display, leaving your desktop alone. See Hopper installation for download verification and platform details.

REA prefers an executable /opt/hopper/bin/Hopper on Linux. If it is unavailable, REA automatically checks ~/.local/share/rea/hopper/bin/Hopper. If Hopper was installed elsewhere:

export HOPPER_LAUNCHER_PATH=/absolute/path/to/Hopper
rea doctor --json

If doctor reports a missing analysis engine even though the file exists, inspect shared-library resolution with:

ldd /absolute/path/to/Hopper | grep 'not found'

Install the missing packages and rerun rea setup. The Linux demo needs Xvfb, Python 3, X11, and XTEST; approved setup installs these dependencies. If you use the curl installer, add ~/.local/bin to your shell PATH when needed.

REA uses /Applications/Hopper Disassembler.app/Contents/MacOS/hopper by default on macOS. On Linux it prefers executable /opt/hopper/bin/Hopper, then executable ~/.local/share/rea/hopper/bin/Hopper, and keeps /opt/hopper/bin/Hopper as the diagnostic fallback if neither exists. Explicit HOPPER_LAUNCHER_PATH configuration always takes precedence.

Ghidra analysis provider

Already use Ghidra? REA can connect it to your agent on Linux x64 or macOS x64/arm64. It accepts Ghidra 12.1.x and the 64-bit full JDK that installation declares (application.java.min through application.java.max). Current 12.1 releases require JDK 21 or newer and set no maximum. The bridge is verified with Ghidra 12.1.4 and JDK 21. On macOS, your Ghidra installation must also include the native decompiler for your architecture.

Set the installation paths, then run setup:

export GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.1.4_PUBLIC
export JAVA_HOME=/absolute/path/to/jdk-21 # optional when java and javac resolve from PATH
rea doctor --json
rea setup
rea providers --json

Setup checks the installations and saves their paths in your selected agents' configuration after approval. Ghidra and Java must already be installed; REA does not download or change them.

The adapter exposes inventory, function, memory and load-image inspection, plus atomic function annotation edits on Linux and macOS. annotate_native_function edits names and entry comments in the session database and returns a refreshed function dossier; executable bytes stay unchanged. Ghidra does not provide GUI controls through REA.

Opening a Ghidra target selects its provider; the first analysis query starts import and auto-analysis. That query can take longer than a client's default request deadline. See first-query deadlines and recovery for an SDK example and cancellation recovery.

REA analyzes a temporary copy of the target and removes the temporary project when the session closes. Results identify what Ghidra observed and what it could not resolve. Decompilation produces pseudocode rather than the original source.

Ghidra also imports DOS MZ executables with an explicit 16-bit x86 real-mode profile. Function results include complete observed body ranges, distinguishing owned bytes from the enclosing span. See the DOS analysis guide for addresses, packing, and verification boundaries. See optional NativeAOT metadata recovery for the pinned headless adapter, supported layout and existing native-tool workflow.

Windows Ghidra P0 uses bundled native controls for its read-only native x86-64 PE boundary on local NTFS; see the Windows Ghidra P0 guide. See Ghidra installation, provider evaluation, and testing for configuration details, coverage, and real-provider verification.

To remove only REA-owned MCP registrations and the managed skill:

rea uninstall
rea uninstall --purge-data # also removes only ~/.rea/cache and ~/.rea/state

Uninstall preserves Hopper, Node.js, Evidence files, captures, unrelated skills, and other MCP servers. It refuses malformed client configuration and never follows purge-data symlinks.

IDA Pro analysis provider

Already have mrexodia/ida-pro-mcp working? REA can reuse its MCP registration for read-only analysis of the current GUI target, or use its database supervisor to open and analyze a supplied binary headlessly.

export REA_IDA_MCP_CONFIG=/absolute/path/to/ida-mcp.json
rea function /absolute/path/to/program main --provider ida --json

The registration selects attached (default, legacy 1.4 tools) or headless (modern database supervisor). Setup can preserve this file reference in your selected agent's REA registration. REA adapts existing analysis contracts and manages its own headless database; it leaves an attached GUI database open and never saves it. Results stay live because external IDA database changes are not immutable snapshots.

See the IDA provider guide for upstream installation links, exact configuration examples, Windows-native headless operation, lifecycle cleanup, and coverage. The initial real workflows cover a Windows GUI and Windows x64 headless IDA 9.3; other engine/platform combinations remain unverified. Use a package version that includes this adapter; repository main can lead the npm release.

CLI or agent?

| If you want to… | Use | | ---------------------------------------------------------------- | ------------------------------------------------------------------- | | Ask an agent to investigate an app and build a feature | Run setup, restart your agent, then describe the task | | Inspect or decompile one part of an app from the Terminal | rea analyze or rea decompile | | Validate, canonicalize, or compare Evidence bundles | rea evidence-import, rea evidence-export, or rea compare | | Map a local JavaScript/Electron application without executing it | rea analyze PATH or rea analyze-javascript-application | | Reuse immutable analysis results without relaunching a provider | Pass --snapshot /path/to/analysis.json to a deep-analysis command | | Import source as historical reference | rea import-reference-source | | Capture or compare controlled process behavior | rea capture-process or rea compare-process-captures |

rea evidence-import /absolute/path/to/evidence/bundle.json
rea evidence-export /absolute/path/to/evidence/bundle.json /absolute/path/to/evidence/canonical.json
rea compare /absolute/path/to/evidence/left.json /absolute/path/to/evidence/right.json

Analyze a JavaScript application directory or ASAR without executing it:

rea analyze /absolute/path/to/releases/app.asar --json
rea analyze-javascript-application /absolute/path/to/releases/app.asar --json

For a directory or .asar, generic rea analyze automatically selects the static JavaScript application provider when neither --provider nor --snapshot is supplied. Both routes return the analysis and its Evidence context inline.

Import an older source tree as a reference. REA keeps it separate from observations of the current app:

rea import-reference-source /absolute/path/to/source

Historical-source import requires safe no-follow file opens and currently runs on Linux and macOS. Native Windows reports unsupported_host; run the import with Linux REA in WSL or on another supported host. Changing permissions or reinstalling REA does not enable this Windows workflow.

Imports read the path supplied to the command. File names do not cause automatic omissions; files are represented by hashes and metadata. To exclude selected paths, set REA_REFERENCE_SECRET_PATTERNS_JSON to a JSON string array of ignore patterns. Exports never replace an existing file unless --overwrite is explicit.

Use a snapshot to save successful analysis results and reuse them on later runs. REA reuses a result only when the target bytes, operation, parameters, analysis tool, and settings match. It does not cache changes or cursor-dependent calls. Snapshot files stay local and use owner-only permissions.

rea analyze /absolute/path/to/app --snapshot /absolute/path/to/analysis/app.json
The same exact query can be answered from that snapshot.
rea analyze /absolute/path/to/app --snapshot /absolute/path/to/analysis/app.json

Exact CLI cached-evidence reads happen before any provider process starts. In MCP sessions, pass snapshot_path to open_binary to import a snapshot atomically while opening its matching target; MCP providers may still start before a cached call result is returned. Pass snapshot_path and, when required, overwrite: true to close_binary to save atomically before Hopper resources are released. If the save fails, REA deliberately leaves the session open.

Just ask your agent

After setup, restart your agent and ask:

Understand how search works in the Notes app, show me the evidence, and build a
similar feature for my project.

Replace Notes with the app you want to understand, or ask for an overview first.

The investigation model

Decompile Open an app and recover readable code, strings, names, and other clues about how it works.

Understand Follow the code from one part of the app to another until the agent can explain how a feature actually works.

Recreate Turn what the agent learned into a feature for your own product, adapted to your stack, interface, and requirements.

REA shows how it reached its conclusions. It does not claim to recover original source code or automatically clone an application.

Why REA

| | | | ------------------------ | ----------------------------------------------------------------------------------------------------- | | Built for agents | Ask what an app does and let your agent inspect it instead of guessing. | | CLI and MCP | Run the same reverse-engineering capabilities from your terminal or agent. | | Guided setup | Configure your agent, connect an existing analysis tool, or install Hopper with your approval. | | From insight to code | Understand a feature, then build your own version in the same coding session. | | Local by design | Analysis runs on your supported local host. REA does not upload the app to a hosted analysis service. | | Keeps context | Investigate several apps without starting over for every question. |

One prompt, a full investigation

Reverse engineer the Notes app. Find how offline search works, explain it,
and build a version for my project using TypeScript and SQLite.

REA gives the agent a clear path from that request to working code:

| Step | What the agent does | REA tools | | ---: | --------------------------------------- | ---------------------------------------------------------------- | | 1 | Opens and identifies the binary | open_binary, binary_overview | | 2 | Finds likely offline-search clues | search_strings, search_procedures, list_names | | 3 | Connects those clues to executable code | find_xrefs_to_name, xrefs, procedure_callers | | 4 | Reconstructs the relevant control flow | get_call_graph, procedure_callees, procedure_info | | 5 | Decompiles the relevant routines | procedure_pseudo_code, procedure_assembly, batch_decompile | | 6 | Builds the feature in your project | code adapted to your stack, product, and requirements |

REA handles the app analysis in steps 1 through 5. The agent performs step 6 with its normal file-editing and test tools, using what it learned about the app.

Showcase

DX-Ball: game reconstruction (in progress)

DX-Ball follows the journey from a classic Windows game's executable to maintainable C. Using REA's Ghidra provider, the project traces functions, game state and dependencies, then checks reconstructed behavior with original-x86 differential tests and pinned-compiler replay.

A sound-pan investigation turns incomplete pseudocode into a C implementat