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.

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+, or 64-bit Arch Linux
• 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 Java, with no emulator or APK execution. See Android analysis for setup, CLI/MCP operations, coverage and public test fixtures.

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.

The normal Linux launcher is /opt/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 /opt/hopper/bin/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 defaults HOPPER_LAUNCHER_PATH to /Applications/Hopper Disassembler.app/Contents/MacOS/hopper on macOS and /opt/hopper/bin/Hopper on Linux. Explicit 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 requires Ghidra 12.1.4 and a 64-bit 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

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.

What agents can do

• Investigate a feature you like and build a version tailored to your own product.
• Explain how a feature works when its source code is unavailable.
• Reconstruct an app's authentication, storage, update, or networking flow.
• Recover enough structure to document an undocumented format or interface.
• Trace a suspicious behavior from a string or symbol to the code that implements it.
• Turn recovered behavior into product features, tests, migration notes, ports, or interoperable replacements.
• Analyze Swift and Objective-C metadata without manually untangling every mangled symbol.
• Leave names, comments, and bookmarks in Hopper so human and agent analysis reinforce each other.

See native investigation for keyed archives, instruction/call/type primitives, typed dispatch metadata, value traces and native desktop observation.

Tool catalog for investigation

| Tool family | Count | Examples | | ------------------------- | ----: | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Native inspection | 41 | functions, pseudocode, assembly, strings, symbols, calls, references, annotations, byte reads, and file offsets | | Investigation workflows | 14 | app overviews, function dossiers, native APIs and dispatch, batch decompilation, feature traces, call paths, call graphs, Swift and Objective-C discovery | | Native macOS utilities | 7 | Mach-O metadata, code signatures, plists, architectures, and Swift demangling without launching Hopper | | Artifact graph | 5 | directory and package inventories, compiled Interface Builder files, Apple asset catalogs, and extraction | | Managed PE/CLI | 7 | .NET identity, metadata, CIL instructions, native dependencies, reconstruction imports, and build comparisons | | Firmware | 2 | Linux firmware region inspection and explicit extraction | | Android APK | 5 | package and manifest declarations, class search, member inventories, method decompilation, and incoming static references | | Browser observation | 9 | page structure, network metadata, scripts, source maps, WebMCP discovery, screenshots, and capture comparisons | | Electron analysis | 5 | renderer observation, static app mapping, and static/runtime reconciliation | | JavaScript runtime | 2 | Node/Electron Inspector target discovery, script locations, and execution-context events | | Application workflows | 7 | cross-layer feature traces, build comparisons, historical source mapping, static return-shape comparison, and reconstruction checks | | Workspace and observation | 21 | sessions, evidence bundles, navigation context, process/artifact/function comparisons, and open-question tracking |

The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness records direct behavioral captures.

Current status

REA supports native application, JavaScript, Electron, .NET, and browser investigation on macOS and Linux. Individual tools have platform and runtime prerequisites. rea capabilities and `r