🔥 morluto/rea

---

在某款应用中看到一个希望加入自己产品的功能？让你的 Agent 借助 REA 调查它。REA 可以在没有源代码的情况下检查应用，解释功能的实现方式，展示证据，并为你的项目构建相应版本。

REA 将 Agent 连接至用于检查原生二进制、JavaScript 和 Electron 应用、.NET 程序集及网站的工具。你也可以直接通过终端使用同一套工具。分析在本地运行，结果会包含支撑每项结论的证据及其局限性。

安装配置会设置你的 Agent，并将其连接至 Hopper 或 Ghidra。如果你需要分析工具，配置过程可以为你安装 Hopper。

完成配置后，重启 Agent 并提出请求：

理解备忘录应用中的搜索功能如何工作，展示证据，并为我的项目构建一个
类似功能。

将“备忘录”替换为你希望理解的应用，或者先请求概览。

反编译
打开应用，并恢复可读代码、字符串、名称以及其他有关其工作方式的线索。 | 理解
从应用的一部分沿着代码追踪到另一部分，直到 Agent 能够解释某项功能实际如何运作。 | 复现
将 Agent 学到的内容转化为你自己产品中的功能，并适配你的技术栈、界面和需求。
---|---|---

REA 会展示其得出结论的过程。它并不声称能够恢复原始源代码，也不会自动克隆应用。

|
---|---
专为 Agent 构建 | 询问应用的功能，让 Agent 检查应用，而不是靠猜测。
CLI 与 MCP | 从终端或 Agent 运行相同的逆向工程能力。
引导式配置 | 配置 Agent、连接现有分析工具，或在你批准后安装 Hopper。
从洞察到代码 | 理解一项功能后，在同一编码会话中构建自己的版本。
本地优先设计 | 分析在受支持的本地主机上运行。REA 不会将应用上传至托管分析服务。
保留上下文 | 可以调查多个应用，无需针对每个问题从头开始。

使用你的 Agent 配置 REA：

选择哪些受支持的 Agent 应使用 REA，然后在批准前查看准确的路径和变更。已有 REA 注册项默认处于选中状态；新检测到的 Agent 可供选择，但仅检测到它们并不会自动选中。配置会为所选 Agent 添加 MCP 访问权限和 REA 的引导式工作流。Hopper 是单独的可选项，拥有独立的同意流程。配置还可以记录现有的 Ghidra 安装。

配置会在应用变更前展示具体改动，并备份现有配置。请参阅安装与配置，了解要求和配置选项。

通过 Agent（推荐）

完成配置后，重启 Agent，并描述你想理解的应用或功能。Hopper 可以在演示模式下运行；如果它显示首次运行提示，请选择演示模式或输入已有许可证。

REA 支持 Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、Windsurf、Devin、OpenCode、Antigravity、GitHub Copilot CLI、Command Code 和 VS Code。配置期间，已有 REA 注册项默认会被选中；其他检测到的 Agent 在被选中前保持未选状态。其他 Agent 可以使用手动 MCP 配置。

通过 npx 从终端使用

完成配置后，运行：

npx -y rea-agents@latest doctor
npx -y rea-agents@latest analyze /Applications/Notes.app

安装命令行界面：

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

安装程序会将 rea 添加到系统中，并在终端中运行时启动配置流程。它要求已安装 Node.js 和 npm。

或者，使用 npm 安装后再运行配置：

npm install --global rea-agents
rea setup

使用 rea update 更新任一种安装方式。

• macOS 12 或更高版本
• Ubuntu 24.04+、Fedora 41+ 或 64 位 Arch Linux
• Node.js 22.x（>=22.19）、24.x（>=24.11）或 26+
• npm；REA 不要求或安装特定版本的 npm

原生二进制分析需要使用 Hopper 或 Ghidra。Hopper 是拥有独立许可证的软件；其演示版支持分析，但存在由供应商定义的限制。REA 可以使用你已安装的 Ghidra。

Windows Ghidra 支持目前仍处于实验阶段，适用于本地 NTFS 上的原生 x86-64 PE 应用。该软件包捆绑了原生 Job Object、私有 DACL 和路径准入控制。有关前提条件和已验证范围，请参阅 Windows Ghidra P0。

如果遇到问题，请运行：

npx -y rea-agents@latest doctor

doctor 会在不作任何修改的情况下检查主机、依赖项、分析工具和 Agent 配置。使用 --json 可获取结构化诊断结果。

Linux 安装与故障排除

在 macOS 上，经你批准后，配置过程可以在 ~/Applications 中安装 Hopper。它会验证官方下载内容，且不需要 Homebrew 或管理员权限。

在受支持的 Linux 发行版上，配置过程可以通过系统包管理器安装 Hopper 及其演示会话依赖项。你可能会看到系统授权提示。演示会话使用私有虚拟显示器，不会影响你的桌面。有关下载验证和平台详细信息，请参阅 Hopper 安装。

Linux 的默认启动器为 /opt/hopper/bin/Hopper。如果 Hopper 安装在其他位置：

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

如果 doctor 报告缺少分析引擎，但文件实际存在，请使用以下命令检查共享库解析：

ldd /opt/hopper/bin/Hopper | grep 'not found'

安装缺失的软件包后重新运行 rea setup。Linux 演示模式需要 Xvfb、Python 3、X11 和 XTEST；经批准的配置会安装这些依赖项。如果你使用 curl 安装程序，请在需要时将 ~/.local/bin 添加到 shell 的 PATH 中。

REA 默认将 macOS 上的 HOPPER_LAUNCHER_PATH 设置为 /Applications/Hopper Disassembler.app/Contents/MacOS/hopper，将 Linux 上的该变量设置为 /opt/hopper/bin/Hopper。显式配置始终具有更高优先级。

已经在使用 Ghidra？REA 可以在 Linux x64 或 macOS x64/arm64 上将它连接至你的 Agent。它需要 Ghidra 12.1.4 和 64 位 JDK 21。在 macOS 上，你的 Ghidra 安装还必须包含适用于当前架构的原生反编译器。

设置安装路径，然后运行配置：

export GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.1.4_PUBLIC
export JAVA_HOME=/absolute/path/to/jdk-21 # 当 java 和 javac 可从 PATH 解析时可选
rea doctor --json
rea setup
rea providers --json

配置会检查安装，并在获得批准后将路径保存到所选 Agent 的配置中。Ghidra 和 Java 必须已安装；REA 不会下载或修改它们。

该适配器提供清单、函数、内存和加载镜像检查功能，以及 Linux 和 macOS 上的原子化函数注释编辑。annotate_native_function 会编辑会话数据库中的名称和入口注释，并返回更新后的函数档案；可执行字节保持不变。Ghidra 不会通过 REA 提供 GUI 控制。

打开 Ghidra 目标时会选择其提供程序；第一次分析查询会启动导入和自动分析。该查询的耗时可能超过客户端默认请求截止时间。有关 SDK 示例和取消恢复，请参阅首次查询截止时间与恢复。

REA 会分析目标的临时副本，并在会话关闭时删除临时项目。结果会说明 Ghidra 观察到的内容以及无法解析的内容。反编译生成的是伪代码，而非原始源代码。

Ghidra 还可通过显式的 16 位 x86 实模式配置文件导入 DOS MZ 可执行文件。函数结果包含完整的已观察函数体范围，可区分归属字节与外围范围。有关地址、打包和验证边界，请参阅 DOS 分析指南。

Windows Ghidra P0 对本地 NTFS 上只读原生 x86-64 PE 边界使用捆绑的原生控制；请参阅 Windows Ghidra P0 指南。有关配置细节、覆盖范围和真实提供程序验证，请参阅 Ghidra 安装、提供程序评估和测试。

如要仅移除 REA 拥有的 MCP 注册项及受管理的技能：

rea uninstall
rea uninstall --purge-data # 还会仅移除 ~/.rea/cache 和 ~/.rea/state

卸载会保留 Hopper、Node.js、Evidence 文件、捕获内容、无关技能和其他 MCP 服务器。它会拒绝格式错误的客户端配置，且绝不会跟随 purge-data 符号链接。

如果你想要……	使用方法
让 Agent 调查一个应用并构建功能	运行配置，重启 Agent，然后描述任务
从终端检查或反编译应用的一部分	rea analyze 或 rea decompile
验证、规范化或比较 Evidence 包	rea evidence-import、rea evidence-export 或 rea compare
在不执行的情况下映射本地 JavaScript/Electron 应用	rea analyze PATH 或 rea analyze-javascript-application
复用不可变的分析结果而不重新启动提供程序	向深度分析命令传入 --snapshot /path/to/analysis.json
将源代码作为历史参考导入	rea import-reference-source
捕获或比较受控的进程行为	rea capture-process 或 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

分析 JavaScript 应用目录或 ASAR，而不执行它：

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

对于目录或 .asar，当既未提供 --provider 也未提供 --snapshot 时，通用 rea analyze 会自动选择静态 JavaScript 应用提供程序。两种路径都会内联返回分析结果及其 Evidence 上下文。

将较旧的源代码树作为参考导入。REA 会将其与当前应用的观察结果分开保存：

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

导入操作会读取命令提供的路径。文件名不会导致自动省略；文件将以哈希和元数据形式表示。如需排除特定路径，请将 REA_REFERENCE_SECRET_PATTERNS_JSON 设置为一个包含忽略模式的 JSON 字符串数组。除非明确指定 --overwrite，否则导出绝不会替换已有文件。

使用快照保存成功的分析结果，并在后续运行中复用。REA 仅在目标字节、操作、参数、分析工具和设置均匹配时复用结果。它不会缓存变更或依赖光标位置的调用。快照文件保留在本地，并使用仅所有者可访问的权限。

rea analyze /absolute/path/to/app --snapshot /absolute/path/to/analysis/app.json
# 相同的精确查询可以由该快照回答。
rea analyze /absolute/path/to/app --snapshot /absolute/path/to/analysis/app.json

精确的 CLI 缓存证据读取会在任何提供程序进程启动前执行。在 MCP 会话中，向 open_binary 传入 snapshot_path，可在打开其匹配目标时原子化导入快照；MCP 提供程序仍可能在返回缓存调用结果前启动。向 close_binary 传入 snapshot_path，并在需要时传入 overwrite: true，即可在释放 Hopper 资源前原子化保存。如果保存失败，REA 会刻意保持会话打开。

一条提示，完成完整调查

逆向工程备忘录应用。找出离线搜索的工作方式，解释它，
并使用 TypeScript 和 SQLite 为我的项目构建一个版本。

REA 为 Agent 提供从这一请求到可运行代码的清晰路径：

步骤	Agent 的操作	REA 工具
1	打开并识别二进制文件	open_binary、binary_overview
2	查找可能与离线搜索相关的线索	search_strings、search_procedures、list_names
3	将这些线索连接到可执行代码	find_xrefs_to_name、xrefs、procedure_callers
4	重建相关控制流	get_call_graph、procedure_callees、procedure_info
5	反编译相关例程	procedure_pseudo_code、procedure_assembly、batch_decompile
6	在你的项目中构建功能	适配你的技术栈、产品和需求的代码

REA 负责第 1 至第 5 步中的应用分析。Agent 在第 6 步使用其常规文件编辑和测试工具，根据从应用中学到的信息完成工作。

• 调查你喜欢的一项功能，并构建适配自己产品的版本。
• 在源代码不可用时，解释一项功能如何工作。
• 重建应用的身份验证、存储、更新或网络流程。
• 恢复足够的结构，以记录未文档化的格式或接口。
• 从字符串或符号追踪可疑行为，直至实现它的代码。
• 将恢复出的行为转化为产品功能、测试、迁移说明、移植版本或可互操作替代品。
• 分析 Swift 和 Objective-C 元数据，无需手动解开每一个重整符号。
• 在 Hopper 中留下名称、注释和书签，让人工与 Agent 分析相互增强。

有关带键归档、指令/调用/类型原语、类型化分派元数据、值追踪和原生桌面观察，请参阅原生调查。

工具目录

---

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 configures your agent and connects it to Hopper or Ghidra. If you need an analysis tool, setup can install Hopper for you.

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.

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.

|
---|---
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.

Set up REA with your agent:

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.

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.

From the terminal with npx

After setup, run:

npx -y rea-agents@latest doctor
npx -y rea-agents@latest analyze /Applications/Notes.app

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.

• 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

Native binary analysis requires Hopper or Ghidra. Hopper is separate software with its own license; its demo supports analysis with vendor-defined limits. REA can use Ghidra that you have already installed.

Windows Ghidra support is experimental for native x86-64 PE applications on local NTFS. The package bundles native Job Object, private-DACL, and path-admission controls. 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.

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.

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.

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.

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.

• 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
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.

REA supports native application, JavaScript, Electron, .NET, and browser investigation on macOS and Linux. Individual tools have platform and runtime prerequisites; use rea capabilities to check what is available on your host.

• Native binaries: Open Mach-O, ELF, PE, and Mac .app targets through Hopper or Ghidra. Inspect functions, strings, assembly, decompilation, calls, and references. Hopper also accepts .hop databases and supports annotations.
• Packages and resources: Inspect directories, ZIP, APK, IPA, ASAR, plists, compiled Interface Builder files, and Apple asset catalogs. Artifact requests name the input and requested extraction or traversal directly; macOS DMG traversal also requires the host's native mounting support.
• JavaScript and Electron: Map modules, imports, source maps, routes, IPC channels, storage, and native add-ons without running the app. Compare builds and trace a feature across the recovered graph. Dynamic and ambiguous relationships remain unresolved. See JavaScript application workflows.
• Websites: Inspect a selected page in an existing Chrome-family browser. Capture page structure, network metadata, script evidence, and screenshots requested by the call. Passive observation does not navigate or execute page JavaScript. See browser observation.
• Electron and Node runtime observation: Inspect selected Electron pages or attach to a Node/Electron V8 Inspector target. Inspector observation records script locations and execution-context events; it does not infer imports, IPC activity, or which modules executed. See runtime observation.
• .NET assemblies: Inspect metadata and CIL instructions, compare builds, and check declared native dependencies without loading or running the assembly. Imported decompiler output is labeled as analyst inference. See managed-code analysis.
• Controlled behavior capture: Run process, browser, or Electron scenarios with the target, actions, and lifecycle declared in each request, then compare the resulting evidence. Missing observations cannot establish that two runs behaved the same way.
• Evidence and comparison: Save results with artifact identity, provider, locations, confidence, and limitations. Export or import bundles, compare artifacts and functions, and connect static findings to runtime observations without claiming causality from correlation.
• Open questions: Track unresolved findings, contradictions, and follow-up probes. Reconstruction checks report pass, fail, or unknown rather than treating missing evidence as a pass.
• Guided workflows: Start six MCP investigation workflows with suggestions based on your current session.

Windows Ghidra P0 supports the read-only native x86-64 PE boundary on local NTFS. Hopper-only features, such as GUI controls and annotations, are not available through Ghidra.

Website observation with CDP

REA can inspect an already-running Chrome-family browser through a literal loopback CDP endpoint. Each request names the endpoint and target; an optional origin filter can narrow discovery:

rea list-browser-targets http://127.0.0.1:9222 --json
rea inspect-web-page http://127.0.0.1:9222 TARGET_ID --json

The eight passive browser tools work through both CLI and MCP. They inspect the selected page without navigating, clicking, or evaluating its JavaScript. Credentials, cookies, authorization headers, and raw payload values are not retained. A request selects whether to include script sources, accessibility text, screenshots, or console and payload summaries. REA cannot observe activity that happened before it attached. See browser observation for browser startup, capture options, and limits.

Controlled browser scenarios

capture_browser_scenario runs a caller-declared sequence of browser actions through Playwright. Unlike passive observation, it can interact with the page. Each step records evidence such as screenshots, page structure, navigation, and network activity. Missing or truncated observations cannot establish that two runs behaved the same way.

rea capture-browser-scenario ./scenario.json --json

Launch mode owns a temporary browser profile and removes it after terminating the launched browser. Connect mode accepts one exact loopback CDP target and disconnects without closing the external browser. The request supplies the selected executable or endpoint, actions, and any origin or environment selections needed by the scenario. Scenario JSON contains secret references and environment-variable names, never secret values. See the browser scenario contract.

Node and Electron V8 Inspector observation

Node and Electron runtime observation attaches to an existing Inspector target named in the request:

rea list-javascript-runtime-targets http://127.0.0.1:9229 --json
rea observe-javascript-runtime http://127.0.0.1:9229 TARGET_ID \
  --runtime-kind node --json

REA records script locations and execution-context events without evaluating code or setting breakpoints. These observations do not establish import relationships, event activity, IPC, process identity, or Electron roles. See Node and Electron runtime observation for the exact coverage.

Exact package, tool-family, provider, setup-client, schema, and CLI facts are generated from source in docs/product-catalog.json. PR CI verifies this catalog, narrative documentation, and generated schemas.

The current status section describes shipped capabilities. These are the next areas of work.

1. Keep documentation accurate: update the generated catalog and documentation checks when tools, providers, setup options, or versions change.

2. Test more native binaries: expand architecture and indirect-call coverage across Hopper and Ghidra.

3. Connect more application layers: add static extractors and runtime observations to feature traces.

4. Extend .NET analysis: improve comparisons of obfuscated assemblies and connect managed findings to verified native analysis. See the managed-code guide.

5. Compare more runtime behavior: expand process, protocol, filesystem, reconnect, and version-comparison coverage.

6. Expand browser and Electron interaction: add scenario actions beyond the current click and wait operations.

7. Observe native apps at runtime: explore LLDB, Frida, system logs, and native API tracing.

8. Evaluate more tools and targets: assess IDA/Hex-Rays, Binary Ninja, Rizin, LIEF, Windows-native tools, mobile apps, and firmware.

Setup already lets you choose agent integration and Hopper installation. Support for installing additional analysis tools is future work, described in the installation roadmap.

See provider evaluation for coverage and remaining requirements, and the native investigation guide for UI, dispatch, and value-flow analysis.

Using REA with other agents

Setup offers supported agent integrations for selection. Existing REA registrations are selected by default; newly detected agents remain unselected until chosen. Any agent that supports local MCP servers can use the configuration below.

{
  "mcpServers": {
    "rea": {
      "command": "npx",
      "args": ["-y", "rea-agents@4.0.1", "mcp"]
    }
  }
}

Persistent registrations should use one exact package version. rea setup maintains that pin, updates the bundled skill at the same time, and gives Codex a 30-second startup allowance for a cold package-runner start. rea update installs an exact release and verifies the new executable. It returns an unapplied maintenance plan for existing REA integrations, with a scoped setup command to review and approve their changes. Restart affected agents afterward.

MCP clients that support prompts can also discover six ordered investigation workflows through prompts/list. Their optional identifier arguments use the current session for bounded completion/complete suggestions; see Guided MCP prompts and completion.

flowchart LR
    Agent["Agent"] --> REA["REA<br/>CLI + MCP"]
    Terminal --> REA
    REA --> Session["Target-bound session router"]
    Session --> Registry["Deep-provider registry<br/>deterministic selection"]
    Registry --> Hopper["Hopper provider"]
    Registry --> Ghidra["Ghidra provider<br/>inventory + function analysis + annotations"]
    Hopper --> Runtime["Owned provider runtime<br/>deadline + bounded diagnostics + cleanup"]
    Ghidra --> Runtime
    Session --> Native["Native macOS provider"]
    Session --> Artifact["Artifact graph provider"]
    REA --> Browser["Browser CDP provider"]
    REA --> Process["Process capture provider"]
    Runtime --> Target["Target software"]
    Process --> Target
    Native --> Target
    Artifact --> Target

Loading

The CLI and MCP server use the same application workflows and evidence contracts. A provider declares which capabilities it supports and the side effects those capabilities may have. Terminal commands are short-lived; an MCP session can retain an active target and evidence ledger for the session.

The agent workflow above is the easiest way to use REA. For a one-off overview from the Terminal:

npx -y rea-agents@latest analyze /Applications/Notes.app
npx -y rea-agents@latest inspect /Applications/Notes.app
npx -y rea-agents@latest search /Applications/Notes.app "offline"
npx -y rea-agents@latest function /Applications/Notes.app 0x1000
npx -y rea-agents@latest xrefs /Applications/Notes.app 0x1000
npx -y rea-agents@latest trace /Applications/Notes.app "offline"
npx -y rea-agents@latest compare /absolute/path/to/left-evidence.json /absolute/path/to/right-evidence.json
npx -y rea-agents@latest capabilities
npx -y rea-agents@latest providers

Run npx -y rea-agents@latest --help for direct decompilation, bounded search and other options. analyze and inspect share the same overview workflow; function, xrefs, and trace return the same Evidence envelopes as MCP.

Or install the rea command globally:

npm install --global rea-agents
rea --help
rea update
rea mcp

REA accepts a Mac .app folder directly. If an agent cannot find an app by name, tell it where the app is installed.

Choosing a deep-analysis provider

Choose which analysis tool to use from the CLI:

rea providers --json
rea analyze /absolute/path/to/program --provider hopper
REA_ANALYSIS_PROVIDER=hopper rea decompile /absolute/path/to/program 0x1000

For MCP, pass the optional selector on open_binary:

{
  "path": "/absolute/path/to/program",
  "provider_id": "hopper"
}

Use --provider, or provider_id in MCP, to choose Hopper or Ghidra for a target. This choice overrides REA_ANALYSIS_PROVIDER.

With auto, REA selects the only available tool that supports the target. If both are available, specify one before opening the target. The session keeps that choice until you explicitly switch or close it; a failure never silently switches tools. Artifact-only analysis can work without a native analysis tool.

Run rea providers and rea capabilities to check availability and supported operations. Ghidra supports inspection and atomic function annotation edits on Linux and macOS. Its database edits are discarded on close; GUI controls require Hopper. Windows Ghidra P0 supports read-only analysis of native x86-64 PE applications on local NTFS with bundled native controls.

The session also reports active work and cleanup status. If a caller times out, the analysis tool may still be busy; analysis_activity reports that state. A cleanup_incomplete result identifies resources whose shutdown or removal could not be verified. See provider selection and analysis profiles for session, cache, and process-tracking details.

Status	Meaning
0	The operation completed. Results may still include warnings, partial evidence, or unresolved questions.
1	The operation could not complete, for example because of invalid input, host permission denial, cancellation, or timeout. Structured output reports the reason when available.
128 + N	The process ended from signal N, where the shell or runtime preserves the conventional signal-derived status.

setup --dry-run returns status planned and exits 0. A setup result with status cancelled also exits 0. setup returns 1 for needs_confirmation or needs_human because configuration is not ready; rerun it after approval or remediation. doctor returns 1 when required checks for its readiness scope are unhealthy. Unavailable optional provider prerequisites remain visible as informational diagnostics and do not block setup or unrelated providers. Output format, full envelopes, filters, and token controls never change the operation status.

When REA feeds a shell pipeline, enable pipefail so a downstream formatter cannot hide its failure:

set -o pipefail
rea inspect-artifact ./app.asar --json | jq . > inspection.json

REA starts Hopper when an operation needs it. On macOS, Hopper may bring its window or a dialog to the foreground even though REA requests background startup. Demo or license prompts may need your attention.

Hopper handles one analysis request at a time. Cancelling your wait does not stop work already running inside Hopper; the session reports whether it is still busy. Successful decompilation results are cached until a relevant rename or comment change.

Use rea instructions when you only need assembly instructions for a function. It avoids decompilation and a whole-program inventory.

Closing a session shuts down REA's bridge and removes its temporary socket directory while preserving a Hopper application you may be using. If cleanup cannot be verified, close_binary reports cleanup_incomplete and the affected resources.

Process capture runs the exact executable and scenario declared in the request, with the requested working directory and environment. Filesystem observation paths select what to snapshot. The process runs with your user permissions; Process Capture records behavior and is not a security sandbox.

Capture a scenario or compare two saved Process Capture Evidence records:

rea capture-process ./scenario.json > authority.json
rea capture-process ./reconstruction.json > reconstruction.json
rea compare-process-captures authority.json reconstruction.json

The comparison reports each observed dimension separately and identifies the first terminal, interaction, exit, filesystem, or process divergence. See Process Capture for scenario fields, limits, and evidence boundaries.

REA installs a prebuilt PTY backend for supported macOS, Linux, and Windows architectures. If the capability check reports that the backend is unavailable, reinstall REA for the current platform and architecture.

ASAR inventory verifies Electron integrity metadata for both archive entries and .asar.unpacked companion files. Integrity failures identify the logical path, declared and calculated SHA-256 values, and whether the entry was unpacked; REA does not silently accept the mismatched artifact. If a supplied ASAR declares unpacked companion bytes that are absent from the local artifact set, REA keeps that occurrence as unavailable and continues analyzing the embedded JavaScript instead of treating the missing native/resource bytes as verified or absent.

Analysis runs locally. REA communicates with Hopper and Ghidra through authenticated private local sockets. Your agent or model provider has its own data policy.

Runtime requests act on the declared target and lifecycle. Analysis tools and launched targets run with your user permissions, and native UI capture still depends on macOS Accessibility and Screen Recording access. Static JavaScript analysis does not execute extracted modules; use direct browser, Electron, or process capture when runtime behavior is needed.

Windows Ghidra P0 automatically uses native Job Objects, protected private-runtime DACLs, and handle-based admission. Its experimental scope is native x86-64 PE applications on local NTFS. Report vulnerabilities through the private process in SECURITY.md.

Does Hopper need to be running before I start REA?

No. REA starts Hopper when an operation needs it. An already-running Hopper application is also supported.

Why did Hopper appear in front of my other windows?

Hopper's launcher internally activates the application. REA requests background startup, but macOS and Hopper may still bring a window or dialog forward. See Current Hopper provider.

Does REA include Hopper?

No. Setup can install Hopper for you, but Hopper remains separate software with its own license. REA supplies the CLI, MCP server, and workflows that make it usable by agents.

Does REA install or include Ghidra or Java?

No. REA connects to an existing Ghidra installation. Run setup after providing the Ghidra and Java paths shown in the Ghidra section.

Does REA upload the app?

REA has no hosted analysis service. Current providers analyze artifacts and capture behavior locally. Your agent or model provider may have its own data policy, so review that separately.

Can REA recover the original source code?

No decompiler can guarantee the original source. REA gives an agent pseudocode, assembly, symbols, strings, metadata, and relationships that it can use to explain or compatibly recreate observed behavior.

Which agents can use REA?

Any agent that can run a local MCP server can use the manual configuration. Setup offers the supported integrations listed in Installation and setup; existing REA registrations are selected by default, and other detected agents require selection.

See CONTRIBUTING.md for development setup and contribution checks, and docs/testing.md for test scopes and real-tool verification. npm run docs:check checks committed generated documents; npm run docs:generate regenerates them.

npm run verify:agent evaluates native, JavaScript, managed, and browser investigation tasks through a real local Codex CLI. Its report covers tool selection, repeated calls, token use, completion quality, and handling of permissions and unknowns.

npm run evidence:generate regenerates the managed conformance manifest and Evidence completion ledger from live verification results. npm run evidence:check reruns verification and checks for drift. Unsupported claims remain explicit and do not count as passes. See testing for verification commands and process-cleanup checks.

npm · Issues · Security · Contributing · Hopper · Ghidra

MIT