docs: organize canonical documentation layout (URGENTE)
Group all existing authored guides by domain and ownership, expose complete navigation, and preserve their public routes. Update physical path consumers and release configuration while retaining historical records. Document domain-based specs and ADR slugs without global numbering. Co-Authored-By: Codex <noreply@openai.com>
This commit is contained in:
@@ -0,0 +1,277 @@
|
||||
# CLI and Evidence
|
||||
|
||||
Use the CLI for a direct inspection or a script. It uses the same application
|
||||
workflows and evidence contracts as REA's MCP server. Each CLI invocation is a
|
||||
separate process; save results when you want to use them in a later command.
|
||||
|
||||
## Run a command
|
||||
|
||||
After [installing REA](installation.md), use `rea`. You can also run a command
|
||||
without a global installation:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||||
```
|
||||
|
||||
Use an extracted application directory or an ASAR as the target. Static
|
||||
JavaScript analysis returns the application graph and Evidence directly.
|
||||
Generic `rea analyze PATH` selects this workflow for directories and `.asar`
|
||||
files when neither `--provider` nor `--snapshot` is supplied. See
|
||||
[JavaScript artifact reconstruction](../guides/javascript/javascript-artifact-reconstruction.md)
|
||||
for results, integrity checks and coverage.
|
||||
|
||||
The complete application Evidence can be hundreds of megabytes for a real
|
||||
application. When an agent or a person reads the result, save it to a file and
|
||||
project a summary, a module page or one module from the saved Evidence:
|
||||
|
||||
```bash
|
||||
rea analyze-javascript-application /absolute/path/to/app --json > app-evidence.json
|
||||
jq -c '{source: {kind: "inline", evidence: .}, view: {kind: "summary"}}' app-evidence.json > app-view.json
|
||||
rea inspect-analysis-view app-view.json
|
||||
```
|
||||
|
||||
For example, a 334 MB Obsidian application Evidence file yields a summary view
|
||||
of about 10 KB. Replace the view with
|
||||
`{"kind": "page", "collection": "modules", "offset": 0, "limit": 32}` for a
|
||||
module page. See
|
||||
[JavaScript application workflows](../guides/javascript/javascript-application-workflows.md) for
|
||||
views, feature traces and comparisons that take the same saved Evidence.
|
||||
|
||||
## Managed assemblies (.NET)
|
||||
|
||||
For a .NET PE/CLI assembly, inspect its identity and deployment form before
|
||||
inspecting members. These commands read metadata and Common Intermediate
|
||||
Language (CIL) without loading or executing the assembly and require no native
|
||||
analysis engine:
|
||||
|
||||
```bash
|
||||
rea inspect-managed-artifact /absolute/path/Assembly.dll --json
|
||||
rea inspect-managed-members /absolute/path/Assembly.dll --json
|
||||
rea inspect-managed-members /absolute/path/Assembly.dll --type Example.Parser --json
|
||||
```
|
||||
|
||||
Replace `Example.Parser` with an exact `full_name` from the member inspection,
|
||||
or a declaring type name you already know. Omit `--type` to inspect all members,
|
||||
or repeat it to select several types.
|
||||
Selection limits decoding to the selected types; member references remain an
|
||||
assembly-wide inventory, so the output can still be large.
|
||||
|
||||
Choose the workflow from the artifact's contents rather than its `.exe` or
|
||||
`.dll` extension. The managed parser requires PE/CLI metadata; it does not
|
||||
unpack .NET single-file hosts or decode IL2CPP metadata. NativeAOT method bodies
|
||||
require native analysis. See the [managed-code guide](../guides/managed/managed-code-analysis.md)
|
||||
for supported deployment forms, selection semantics, and coverage limits.
|
||||
|
||||
## SQLite snapshots
|
||||
|
||||
For a local database snapshot, use `rea inspect-sqlite-database PATH --json`.
|
||||
Add `--table NAME --row-limit 20` to read a bounded sample from an ordinary
|
||||
table. This command does not require a native analysis provider. See
|
||||
[SQLite database snapshots](../guides/data/sqlite-databases.md) for database/WAL identity,
|
||||
source-file handling and row-value semantics.
|
||||
|
||||
## Native analysis
|
||||
|
||||
Inspect embedded Go build metadata without installing Go or configuring a
|
||||
disassembler:
|
||||
|
||||
```bash
|
||||
rea inspect-go-binary /absolute/path/to/program --json
|
||||
```
|
||||
|
||||
The shared CLI/MCP workflow reports compiler version, modules, replacements,
|
||||
build settings, original bytes and SHA-256. See [Go binaries](../guides/native/go-binaries.md)
|
||||
for supported containers and absent or malformed metadata.
|
||||
|
||||
Configure [Hopper or Ghidra](installation.md#hopper), or the
|
||||
[IDA adapter](../providers/ida-provider.md), before analyzing a native target. Substitute
|
||||
your target, search text and function name or address in these examples:
|
||||
|
||||
```bash
|
||||
rea analyze /absolute/path/to/program --provider ghidra --json
|
||||
rea search /absolute/path/to/program "search" --provider ghidra --json
|
||||
rea function /absolute/path/to/program main --provider ghidra --json
|
||||
rea decompile /absolute/path/to/program 0x1000 --provider ghidra --json
|
||||
rea xrefs /absolute/path/to/program 0x1000 --provider ghidra --json
|
||||
rea trace /absolute/path/to/program "search" --provider ghidra --json
|
||||
```
|
||||
|
||||
`analyze` and `inspect` share the native overview workflow. `function` returns
|
||||
a function dossier; `decompile` returns pseudocode. For assembly instructions
|
||||
alone, use `rea instructions`. A macOS `.app` bundle can be supplied directly.
|
||||
|
||||
Run `rea --help` or a command's `--help` for arguments and output options.
|
||||
The [generated catalog](../reference/mcp-contracts.md#generated-catalog) lists all CLI commands and MCP
|
||||
tools. Provider-specific target support is described in the
|
||||
[native guide](../guides/native/native-investigation.md), [DOS guide](../providers/ghidra-dos.md),
|
||||
[raw binary guide](../providers/raw-binary.md), and
|
||||
[Windows Ghidra guide](../providers/windows-ghidra-p0.md).
|
||||
|
||||
## Choose a provider
|
||||
|
||||
List the available providers and their supported operations:
|
||||
|
||||
```bash
|
||||
rea providers --json
|
||||
rea capabilities --json
|
||||
```
|
||||
|
||||
These commands describe binary-session providers and auxiliary capabilities.
|
||||
For the complete MCP surface, use the connected server's tool list and the
|
||||
session's advertised availability; individual guides describe prerequisites.
|
||||
|
||||
With automatic selection, REA uses the single available provider that supports
|
||||
the target. When several providers support it, select one explicitly:
|
||||
|
||||
```bash
|
||||
rea analyze /absolute/path/to/program --provider hopper
|
||||
```
|
||||
|
||||
Set `REA_ANALYSIS_PROVIDER` for a standing preference. An explicit `--provider`
|
||||
overrides it. In MCP, pass `provider_id` to `open_binary`:
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "/absolute/path/to/program",
|
||||
"provider_id": "hopper"
|
||||
}
|
||||
```
|
||||
|
||||
The selected provider remains bound to the session until an explicit switch
|
||||
or close. Provider failures are returned with their original reason. For an
|
||||
`ambiguous` selection error, choose from `details.candidate_ids`; for
|
||||
`provider_unavailable`, run `rea doctor --provider ID --json` to diagnose the
|
||||
selected engine. See [task readiness](installation.md#check-readiness-for-your-task)
|
||||
and [provider selection](../reference/mcp-contracts.md#identity-and-discovery).
|
||||
|
||||
The session reports work still in progress through `analysis_activity`.
|
||||
A client timeout can end its wait while the provider continues analyzing.
|
||||
`cleanup_incomplete` identifies resources whose shutdown or removal could not
|
||||
be verified. See [MCP contracts](../reference/mcp-contracts.md) for session lifecycle and
|
||||
[Ghidra first-query deadlines](../reference/mcp-contracts.md#ghidra-first-query-deadlines-and-recovery)
|
||||
for import, client timeouts and recovery.
|
||||
|
||||
## Save and reuse analysis snapshots
|
||||
|
||||
A snapshot retains successful analysis results for later queries. REA reuses
|
||||
an exact result when the target bytes, operation, parameters, provider and
|
||||
settings match. Mutations and cursor-dependent calls are excluded from the
|
||||
cache. Snapshot files are local and use owner-only permissions.
|
||||
|
||||
Dispatching a metadata write invalidates the active session's snapshot cache,
|
||||
even if its reply fails: the provider may already have applied the write.
|
||||
Close and reopen the target before importing or saving another snapshot.
|
||||
|
||||
Snapshots retain eligible target-scoped question histories in full, including
|
||||
mutation Evidence recorded while another target was active. Observations and
|
||||
related questions must still belong to the saved target. If those dependencies
|
||||
cannot be retained, the entire history is excluded instead of reverting the
|
||||
question to an earlier revision or disposition.
|
||||
|
||||
```bash
|
||||
rea analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program.json
|
||||
# Repeat the same query to reuse its saved result.
|
||||
rea analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program.json
|
||||
```
|
||||
|
||||
An exact CLI cache hit is read before starting a provider process.
|
||||
In MCP, `open_binary` accepts `snapshot_path` to import a snapshot atomically
|
||||
for its matching target; an MCP provider may still start before returning a
|
||||
cached result. `close_binary` accepts `snapshot_path` and optional
|
||||
`overwrite: true` to save before releasing provider resources. A failed save
|
||||
leaves the session open so the caller can resolve the output failure.
|
||||
|
||||
The MCP save receipt reports `primitive_entries`, `workflow_entries`, and
|
||||
`evidence_records` separately. Zero primitive bindings can still accompany retained workflow
|
||||
results and Evidence. These are cached observations, not a saved provider
|
||||
database: only eligible exact queries can reuse a result, and new or live
|
||||
queries can still require provider startup. The CLI uses the same snapshot
|
||||
format and preserves these records when loading and updating it.
|
||||
|
||||
## Import, export and compare Evidence
|
||||
|
||||
Evidence records retain artifact identity, source locations, observations,
|
||||
inferences and unresolved findings. Validate an existing bundle, export its
|
||||
canonical form, or compare two supplied bundles:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Exports preserve an existing destination unless `--overwrite` is explicit.
|
||||
For application traces and version comparisons, see
|
||||
[JavaScript application workflows](../guides/javascript/javascript-application-workflows.md).
|
||||
MCP [retained Evidence references](../reference/mcp-contracts.md#retained-application-evidence-inputs)
|
||||
belong to one connection. Separate CLI calls consume full saved records.
|
||||
|
||||
## Import historical source
|
||||
|
||||
Import an older source tree to compare with the current artifact:
|
||||
|
||||
```bash
|
||||
rea import-reference-source /absolute/path/to/source
|
||||
```
|
||||
|
||||
The import records hashes and metadata for the supplied files, separately
|
||||
from observations of the current app. It honors the source tree's `.gitignore`
|
||||
and applies default exclusions for common generated and dependency paths such
|
||||
as `node_modules/`, `dist/`, and `*.log`. Pattern-based exclusions record the
|
||||
matched pattern and whether it came from project, default, caller, or sensitive
|
||||
path policy. Set `REA_REFERENCE_SECRET_PATTERNS_JSON` to a JSON array of ignore
|
||||
patterns when you want to mark selected paths as sensitive; those patterns are
|
||||
reported separately as configured-secret exclusions.
|
||||
|
||||
Re-import saved graphs whose pattern-based exclusions lack `pattern` before
|
||||
using them in source-to-bundle comparisons.
|
||||
|
||||
JavaScript and TypeScript import parsing requires valid UTF-8. Malformed source
|
||||
bytes retain their original hashes and sizes with a decoding diagnostic; REA
|
||||
does not infer module targets from replacement characters.
|
||||
|
||||
Historical-source import requires safe no-follow file opens on Linux or
|
||||
macOS. Native Windows returns `unsupported_host`; use Linux REA inside WSL
|
||||
or another supported host. See
|
||||
[source-to-bundle comparison](../guides/javascript/javascript-application-workflows.md#historical-source-to-bundle-comparison)
|
||||
for mapping identities, inferences and unknowns.
|
||||
|
||||
## Capture runtime behavior
|
||||
|
||||
Choose the guide for the target and intended interaction:
|
||||
|
||||
- [Browser observation](../guides/web/browser-observation.md): inspect a selected page through CDP.
|
||||
- [Browser scenarios](../guides/web/browser-scenario-contract.md): run declared interactions and capture their results.
|
||||
- [Electron observation](../guides/javascript/electron-observation.md): inspect an Electron renderer or capture an application scenario.
|
||||
- [Node/Electron Inspector](../guides/javascript/javascript-runtime-observation.md): record script locations and execution contexts.
|
||||
- [Process capture](../guides/runtime/process-capture.md): run an executable and compare terminal, exit and filesystem observations.
|
||||
|
||||
Runtime requests name the target and actions. Launched targets run with your
|
||||
user permissions; consult the chosen guide for host requirements and effects.
|
||||
|
||||
## Output and exit status
|
||||
|
||||
The default terminal format is TOON. Use `--json` when saving results for a
|
||||
JSON consumer. `--json` is indented on a terminal and compact when piped or
|
||||
redirected, which keeps large results smaller for agents and scripts; pipe
|
||||
through `jq .` for indented files. Output selection and formatting do not change
|
||||
operation status.
|
||||
|
||||
| Status | Meaning |
|
||||
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `0` | The operation completed. Its result may include partial evidence, warnings or unresolved questions. |
|
||||
| `1` | The operation could not complete. Structured output identifies invalid input, permissions, cancellation, timeouts or another failure when available. |
|
||||
| `128 + N` | Signal `N` ended the process, where the shell or runtime preserves the conventional signal-derived status. |
|
||||
|
||||
`setup --dry-run` returns `planned` and exits `0`; a cancelled setup also exits
|
||||
`0`. Setup returns `1` for `needs_confirmation` or `needs_human`.
|
||||
`doctor` returns `1` when required checks in its selected readiness scope fail;
|
||||
unavailable optional providers remain informational for unrelated tasks.
|
||||
|
||||
Enable `pipefail` in a supporting shell so a downstream formatter preserves
|
||||
REA's failure status:
|
||||
|
||||
```bash
|
||||
set -o pipefail
|
||||
rea inspect-artifact ./app.asar --json | jq . > inspection.json
|
||||
```
|
||||
@@ -0,0 +1,269 @@
|
||||
# Client configuration and troubleshooting
|
||||
|
||||
Use this reference when a client's configuration paths, profiles, trust settings,
|
||||
or schema limits affect REA. Start with [installation and setup](installation.md)
|
||||
for the reviewed setup transaction and [client IDs](installation.md#supported-agents).
|
||||
The versioned verification notes below describe their stated runs; live service
|
||||
acceptance is verified only where explicitly recorded.
|
||||
|
||||
## GitHub Copilot CLI
|
||||
|
||||
For GitHub Copilot CLI 1.0.95, `gpt-4.1` model metadata can block ordinary
|
||||
chat with REA's full input-schema profile before sending a model request
|
||||
(`compaction_static_context_blocked`; [#1554](https://github.com/morluto/rea/issues/1554)).
|
||||
For the native offline OpenAI-compatible BYOK adapter, full-profile chat and
|
||||
analysis also passed with a distinct `COPILOT_PROVIDER_MODEL_ID` such as
|
||||
`rea-gpt-4.1`, `COPILOT_PROVIDER_WIRE_MODEL=gpt-4.1`, and that distinct ID selected
|
||||
through `copilot --model rea-gpt-4.1`. The local fixture requested
|
||||
`COPILOT_PROVIDER_MAX_PROMPT_TOKENS=1000000`; configure the limit supported by
|
||||
your backend. This keeps every full schema and the actual wire model intact.
|
||||
It does not establish the effective client budget or fix the built-in-ID path.
|
||||
The existing compact profile passed native chat and analysis with the complete
|
||||
tool inventory on Linux using a loopback model fixture. After setup, add
|
||||
`"REA_MCP_INPUT_SCHEMA_PROFILE": "compact"` to the `env` object of the
|
||||
`mcpServers.rea` entry in Copilot's `mcp-config.json`, preserving its other
|
||||
settings, then restart the client. Compact advertisements can reduce nested
|
||||
schema constraints; REA still validates complete canonical inputs. Full-profile
|
||||
`gpt-5.4` metadata is also verified locally. Live model API acceptance and
|
||||
Windows remain unverified; see [native client verification](../development/testing.md).
|
||||
|
||||
## Claude Code
|
||||
|
||||
Claude Code normally defers MCP tool definitions through tool search. It
|
||||
[turns tool search off](https://code.claude.com/docs/en/mcp#configure-tool-search)
|
||||
when `ANTHROPIC_BASE_URL` points to a non-first-party host, such as DeepSeek's
|
||||
Anthropic-compatible endpoint. It then sends every REA tool's name, description
|
||||
and input schema with every request
|
||||
([#2019](https://github.com/morluto/rea/issues/2019)). On main at 04089d5be,
|
||||
with 172 tools, that payload measured about 496 KB with the default profile and
|
||||
about 290 KB with `compact`. By the o200k and cl100k tokenizers, that is roughly
|
||||
120k and 68k tokens. Compaction cannot remove tool definitions. If they nearly
|
||||
fill the window Claude Code assumes, the context refills after every compaction
|
||||
and Claude Code reports that autocompact is thrashing. To avoid this:
|
||||
|
||||
- Make Claude Code assume the model's actual context window. DeepSeek's Claude
|
||||
Code guide selects `deepseek-flash[1m]`; the `[1m]` suffix makes Claude Code
|
||||
assume a one-million-token window. For other unrecognized model IDs, set
|
||||
`CLAUDE_CODE_MAX_CONTEXT_TOKENS` to the window the provider documents.
|
||||
- If the endpoint forwards `tool_reference` blocks, set `ENABLE_TOOL_SEARCH=true`
|
||||
to restore deferred loading. DeepSeek's Anthropic API guide does not list
|
||||
`tool_reference` among its supported content blocks, so this setting may cause
|
||||
its requests to fail.
|
||||
- To shrink the upfront catalog, add
|
||||
`"REA_MCP_INPUT_SCHEMA_PROFILE": "compact"` to the `env` object of the
|
||||
`mcpServers.rea` entry in `~/.claude.json` (`$CLAUDE_CONFIG_DIR/.claude.json`
|
||||
when that variable is set), then restart Claude Code. Setup keeps this
|
||||
override.
|
||||
|
||||
The sizes above come from REA's own `tools/list`. A live Claude Code session
|
||||
against DeepSeek's API is unverified.
|
||||
|
||||
## Pi
|
||||
|
||||
For [Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/mcp.md),
|
||||
setup writes a `type: "stdio"` entry under `mcpServers.rea` in the user-level
|
||||
`~/.pi/agent/mcp.json` and installs the bundled skill under `~/.agents/skills`.
|
||||
Use `rea setup --client pi --dry-run --json` to inspect the plan, then
|
||||
`rea setup --client pi --yes --json` to approve it. Check the registration with
|
||||
`rea doctor --client pi --json`. Pi reads `mcp.json` as strict JSON, like its
|
||||
own loader: comments, trailing commas, a byte-order mark, or an empty existing
|
||||
file are invalid, and setup reports them instead of rewriting the file. Repair
|
||||
such a file to plain JSON first, then rerun setup.
|
||||
|
||||
Setup follows Pi's `PI_CODING_AGENT_DIR`: unset or empty selects the default;
|
||||
`~` and `~/` expand to the home directory; absolute paths and file URLs select
|
||||
that directory; relative paths stay relative to the command's working directory.
|
||||
On Windows, native paths, `~\`, and Git Bash/MSYS, Cygwin, and WSL drive paths
|
||||
are normalized as Pi does. Run REA and Pi from the same working directory when
|
||||
using a relative override. Pi has no profiles: `OMP_PROFILE`, `PI_PROFILE`,
|
||||
`PI_CONFIG_DIR`, and OMP's `enabledServers`/`disabledServers` lists do not affect
|
||||
Pi registration. Doctor accepts an omitted `type` for stdio but reports a
|
||||
non-stdio type as invalid; `enabled: false` stays disabled.
|
||||
|
||||
REA configures only the user scope. Pi also reads `.pi/mcp.json` in trusted
|
||||
projects; a same-name project entry can replace the user entry or override its
|
||||
enabled state and exposure. Check that file if the user registration is aligned
|
||||
but unavailable in a project. An extension that registers `/mcp` can replace
|
||||
Pi's built-in MCP support and use its own configuration instead. Run `/reload`
|
||||
in an existing Pi session after changing servers outside the session.
|
||||
|
||||
## Qwen Code
|
||||
|
||||
For Qwen Code, setup registers `rea` in the `mcpServers` table of the
|
||||
user-level `~/.qwen/settings.json`, or `$QWEN_HOME/settings.json` when configured.
|
||||
Setup and doctor follow Qwen Code's tilde and working-directory-relative home
|
||||
overrides. Qwen Code also discovers personal skills in `~/.agents/skills`,
|
||||
where setup installs the bundled workflow.
|
||||
|
||||
## Gemini CLI
|
||||
|
||||
Gemini CLI uses `$GEMINI_CLI_HOME/.gemini/settings.json` when that home override
|
||||
is nonempty, including its shared personal skills at
|
||||
`$GEMINI_CLI_HOME/.agents/skills`. Setup and doctor check MCP allow/exclude
|
||||
policies from system defaults, user settings, trusted workspace settings, and
|
||||
system overrides. Workspace trust follows `GEMINI_CLI_TRUST_WORKSPACE`,
|
||||
`GEMINI_RESTRICTED_MODE`, the effective `security.folderTrust.enabled` setting,
|
||||
and the selected `trustedFolders.json` (including
|
||||
`GEMINI_CLI_TRUSTED_FOLDERS_PATH`). Settings in an untrusted workspace do not
|
||||
participate. A workspace or system `mcpServers.rea` replaces the entire user
|
||||
entry; setup stops if the winning definition conflicts with its planned entry.
|
||||
Review those files manually: setup never edits administrator/workspace settings
|
||||
or grants workspace trust. Trust supplied only by a running IDE is outside this
|
||||
standalone CLI check.
|
||||
|
||||
## Codex and Devin
|
||||
|
||||
Codex treats an unset or empty `CODEX_HOME` as `~/.codex`. Devin honors
|
||||
`XDG_CONFIG_HOME` for its `devin/mcp_config.json` on non-Windows systems.
|
||||
|
||||
## OMP
|
||||
|
||||
For OMP, setup writes a `type: "stdio"` entry to the user-level
|
||||
`~/.omp/agent/mcp.json`. It follows `PI_CONFIG_DIR` and
|
||||
`PI_CODING_AGENT_DIR` (relative to the setup working directory), and the profile selected by `OMP_PROFILE` or
|
||||
`PI_PROFILE` (`~/.omp/profiles/<name>/agent/mcp.json`). Setup also removes
|
||||
`rea` from that file's `disabledServers` list, which would otherwise hide the
|
||||
registration. Doctor treats an `enabled: false` entry as active when
|
||||
`enabledServers` lists `rea`, as OMP does, unless `disabledServers` also lists
|
||||
it. Run setup under each profile that should load REA.
|
||||
|
||||
## Hermes
|
||||
|
||||
For Hermes, setup writes a `mcp_servers.rea` entry to `config.yaml`, preserving
|
||||
comments and unrelated settings. It resolves that file from `HERMES_HOME`, else
|
||||
from the platform default Hermes itself uses — `%LOCALAPPDATA%\hermes` on
|
||||
Windows, `~/.hermes` elsewhere — including any `HERMES_DATA_DIR_SUFFIX`. Hermes
|
||||
connects an entry unless `enabled` is false, so setup states `enabled: true`.
|
||||
|
||||
Hermes personal skills install under the active Hermes home's `skills` directory.
|
||||
Setup, doctor and uninstall follow the root's `active_profile` selection, as
|
||||
plain Hermes CLI commands do. An explicit `HERMES_HOME` pointing to
|
||||
`profiles/<name>` selects that named profile directly. An invalid, missing or
|
||||
deleted sticky profile is reported instead of writing into the default home;
|
||||
repair the profile or run `hermes profile use default` before retrying.
|
||||
REA follows `HERMES_HOME` whitespace trimming, environment-variable expansion,
|
||||
and home expansion before resolving that profile. Setup previews the resolved
|
||||
configuration and skill destinations; doctor and uninstall use those same paths.
|
||||
|
||||
## Qoder CLI
|
||||
|
||||
For [Qoder](https://docs.qoder.com/cli/mcp-reference), setup writes
|
||||
`mcpServers.rea` into the user-level `~/.qoder/settings.json` (the
|
||||
`QODER_CONFIG_DIR` override is honored). Entries carry `command`, `args`, and
|
||||
`env`; stdio is the default transport. Qoder CLI discovers personal skills
|
||||
from `~/.qoder/skills` (following `QODER_CONFIG_DIR` when set), so setup
|
||||
installs its skill copy there.
|
||||
|
||||
## Trae
|
||||
|
||||
For [Trae](https://docs.trae.ai/ide/add-mcp-servers), setup writes
|
||||
`mcpServers.rea` into the user-scope `mcp.json` under Trae's VS Code-style
|
||||
user directory (`%APPDATA%\Trae\User` on Windows,
|
||||
`~/Library/Application Support/Trae/User` on macOS, and
|
||||
`~/.config/Trae/User` elsewhere). Entries carry `command`, `args`, and
|
||||
`env`; stdio is the default transport. Trae discovers personal skills from
|
||||
`~/.trae/skills` (`%userprofile%\.trae\skills` on Windows), so setup
|
||||
installs its skill copy there.
|
||||
|
||||
The user-level MCP paths follow the editor's VS Code layout. Trae's official
|
||||
documentation describes the raw JSON editor without specifying those paths;
|
||||
loading this registration in Trae remains unverified.
|
||||
|
||||
## ZCode
|
||||
|
||||
For [ZCode](https://zcode.z.ai/en/docs/mcp-services), setup registers `rea` in the nested `mcp.servers` table of the
|
||||
user-level `~/.zcode/cli/config.json`. Entries carry `command`, `args`, and
|
||||
`env` without a transport discriminator. ZCode discovers personal skills from
|
||||
`~/.zcode/skills` rather than the shared directory, so setup installs its
|
||||
skill copy there.
|
||||
|
||||
ZCode reads the user-scope `~/.agents/mcp.json` fallback only while the native
|
||||
`.zcode` config defines no servers at all, with no merging. When setup writes
|
||||
the first native server into an empty table, it copies the fallback's
|
||||
`mcpServers` entries into the native table so they keep loading, and leaves
|
||||
the fallback file untouched. Existing REA environment overrides are preserved
|
||||
when refreshing its command. A malformed or unreadable fallback file fails setup instead of
|
||||
being silently suppressed; repair or remove it and rerun. ZCode disables a
|
||||
server with `enable: false` on its entry; doctor reports such a registration
|
||||
as stale, and rerunning setup removes the flag to repair it. Native configuration
|
||||
uses strict JSON; setup refuses comments, trailing commas and a BOM rather than
|
||||
writing a registration ZCode cannot load.
|
||||
|
||||
## DeepSeek Harness
|
||||
|
||||
DeepSeek Harness registers MCP clients through a Cordis YAML patch sequence
|
||||
rather than a `mcpServers` object. `rea setup --client dsh` appends (or
|
||||
replaces) the REA entry in the home patch `$DSH_HOME/cordis.patch.yml`
|
||||
(`~/.dsh/cordis.patch.yml` when `DSH_HOME` is unset), preserving unrelated
|
||||
patches and comments. `rea doctor --client dsh` checks that same entry id.
|
||||
`rea uninstall` removes it by scanning supported clients; uninstall takes no
|
||||
`--client` flag. The home patch applies to every Harness profile, so the
|
||||
registration is written once and no per-profile edit is needed. The written
|
||||
entry is:
|
||||
|
||||
```yaml
|
||||
- insert:
|
||||
- id: rea-mcp
|
||||
name: "@deepseek-ai/dsh-mcp-client"
|
||||
config:
|
||||
serverName: rea
|
||||
transport: stdio
|
||||
command: /absolute/path/to/node
|
||||
args: ["/absolute/path/to/rea/scripts/rea.mjs", mcp]
|
||||
```
|
||||
|
||||
Setup preserves caller-owned Cordis expressions and replaces launcher fields
|
||||
with literal values that doctor can verify. It refuses to edit an expression
|
||||
that produces the entire REA config, or a group-targeted REA insertion. Use a
|
||||
literal config and a root-level insertion as shown above.
|
||||
|
||||
For a global npm installation, the launcher is under
|
||||
`$(npm root -g)/rea-agents/scripts/rea.mjs`. Restart Harness after setup; it
|
||||
exposes tools as `mcp__rea__<tool_name>`. Run `rea setup --skill --dry-run`,
|
||||
review the destination, then `rea setup --skill --yes` to install the workflow
|
||||
in `~/.agents/skills` (`$DSH_AGENTS_HOME/skills` when configured); Harness
|
||||
discovers that directory, and its native `skill` tool can load
|
||||
`reverse-engineer-anything`.
|
||||
|
||||
REA's optional [native client verification](../development/testing.md#end-to-end-integration-and-golden-evidence)
|
||||
checks headless chat, skill loading, all tool input schemas and actual analysis
|
||||
using the installed Harness and a local model fixture. This establishes the
|
||||
Harness integration, with live DeepSeek API compatibility remaining unverified.
|
||||
See the [Harness MCP guide](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/mcp/mcp-client/README.md)
|
||||
for its native configuration contract.
|
||||
|
||||
## Other client settings
|
||||
|
||||
For OpenCode, setup writes the V1 `mcp.rea` entry, which OpenCode V1 and V2
|
||||
both load. If the configuration already uses OpenCode V2's native
|
||||
`mcp.servers` table, setup registers REA there instead and replaces any earlier
|
||||
`mcp.rea` entry from REA. Setup honors `OPENCODE_CONFIG_DIR` and
|
||||
`OPENCODE_CONFIG`, preferring the later-loaded JSONC file when both JSON and
|
||||
JSONC exist. The ordinary XDG global configuration still participates when a
|
||||
custom directory is selected. Doctor checks the merged user registration; uninstall removes
|
||||
REA-owned entries from every applicable user file so an older entry cannot
|
||||
become active again. Malformed applicable files block setup before changes.
|
||||
|
||||
Grok Build loads `[mcp_servers.rea]` from `$GROK_HOME/config.toml`, or from
|
||||
`~/.grok/config.toml` when `GROK_HOME` is unset or empty. Setup edits that server
|
||||
table, `[mcp_servers.rea.env]`, and a root `disabled_mcp_servers` entry that
|
||||
names `rea`. It sets `startup_timeout_sec = 30` and leaves every other name
|
||||
in that list. The shared skill installed under `~/.agents/skills` is already
|
||||
on Grok Build's skill path.
|
||||
|
||||
Grok Bot (`grok_bot`) is detected from `~/.grokbot`, or from `SAND_DATA_ROOT`
|
||||
when that value is an absolute path. A relative or empty `SAND_DATA_ROOT`
|
||||
stays on `~/.grokbot`. That directory is not the connector store. Grok Bot
|
||||
keeps connectors in the signed-in account and runs them on its hosted
|
||||
computer. It does not import `mcp.json` from the data directory, and it does
|
||||
not attach a stdio server running on this machine. Setup does not call the
|
||||
account connector API, does not write a registration file, and does not report
|
||||
the data directory as aligned. Ask the Grok Bot chat to add a custom MCP
|
||||
server named `rea` that runs on the Bot's computer:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@<version> mcp
|
||||
```
|
||||
|
||||
Do not put credentials in that command or its arguments. `rea doctor --client grok_bot`
|
||||
reports this manual step. `rea uninstall` does not remove the account connector.
|
||||
@@ -0,0 +1,847 @@
|
||||
# Installation and setup
|
||||
|
||||
Run REA, connect your selected agents, and check the tools needed for your task.
|
||||
Setup previews configuration changes and asks for approval before applying them.
|
||||
|
||||
| Task | Section |
|
||||
| --------------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| Connect an agent | [Start setup](#start-setup), then [review changes](#review-setup-changes) |
|
||||
| Diagnose one task | [Scoped readiness checks](#check-readiness-for-your-task) |
|
||||
| Configure an analysis engine | [Hopper](#hopper), [Ghidra](#ghidra), or the [IDA guide](../providers/ida-provider.md) |
|
||||
| Update or remove REA | [Maintenance](#diagnose-update-and-remove) |
|
||||
| Resolve a client-specific problem | [Client configuration](client-configuration.md) |
|
||||
|
||||
## Start setup
|
||||
|
||||
```bash
|
||||
npx rea-agents setup
|
||||
```
|
||||
|
||||
Choose the agents to configure, review the proposed paths and changes, and
|
||||
approve the plan. npm's package-download approval and REA's setup approval are
|
||||
separate. Setup asks before changing agent configuration or installing Hopper.
|
||||
Restart the agents named in the completion message.
|
||||
|
||||
For the latest published release, use `npx rea-agents@latest setup`.
|
||||
[Package-runner and global-installation options](#package-runners-and-global-installation)
|
||||
cover explicit versions, Bun, runtime requirements, and the curl wrapper.
|
||||
|
||||
## Review setup changes
|
||||
|
||||
`rea setup` first offers the supported agents in a multi-select. Existing REA
|
||||
registrations are selected by default. Newly detected clients remain available
|
||||
but unselected: detection gives setup context, not permission to add a new
|
||||
registration. Clients without a detected configuration can still be selected.
|
||||
Explicit `--client` flags skip this question.
|
||||
|
||||
Setup adds MCP access for selected clients. It installs REA's bundled workflow
|
||||
with those integrations by default; use `--skill=false` to omit it. If no agent
|
||||
is selected, setup offers the workflow separately for CLI use, with No as the
|
||||
default. Hopper is a separate optional choice: setup shows its proposed
|
||||
installation or connection and requires its own explicit approval. It can also
|
||||
save verified paths for an existing Ghidra installation.
|
||||
|
||||
After selection, review the plan's exact paths and changes and approve before
|
||||
REA writes files or installs Hopper. You can cancel at any prompt.
|
||||
|
||||
Before applying changes, REA checks your current configuration. The plan lists:
|
||||
|
||||
- an existing Hopper installation, a verified existing Ghidra installation, or the official Hopper package it proposes to install;
|
||||
- each detected agent configuration path;
|
||||
- each selected REA skill destination;
|
||||
- external software, network origins, integrity evidence, and package-manager
|
||||
commands.
|
||||
|
||||
Malformed or unsafe existing configuration blocks the whole transaction before
|
||||
Hopper installation or any file write. Declining or pressing Ctrl-C makes no
|
||||
changes. Agent configuration writes preserve unrelated entries and comments,
|
||||
create backups, use atomic replacement, and verify their result. Setup and
|
||||
uninstall retain an existing `.rea.backup` rather than replacing the first snapshot.
|
||||
Setup also retains valid environment overrides in REA's existing server entry,
|
||||
such as `REA_MCP_INPUT_SCHEMA_PROFILE` and `REA_MCP_MAX_RESPONSE_BYTES`.
|
||||
Detected provider settings replace only matching environment keys.
|
||||
Setup and doctor report a malformed REA environment map or invalid runtime
|
||||
setting before setup writes files. Repair the named setting in the client
|
||||
configuration; setup does not silently discard the rest of the map.
|
||||
|
||||
After setup, REA reports which agents, analysis tools, and workflow files passed
|
||||
its final checks. Restart any agent named in the completion message, then begin
|
||||
your investigation. Failed steps and diagnostics remain in terminal history.
|
||||
|
||||
Select exact clients in scripts with repeatable `--client` flags. Each explicit
|
||||
client skips interactive selection. Use `--all-detected` only when you intend
|
||||
to configure every detected supported client. `--skill=false` omits the
|
||||
workflow, and `--dry-run` returns a read-only plan with status `planned` and
|
||||
exit code 0:
|
||||
|
||||
```bash
|
||||
rea setup --client codex --client cursor --skill=false --dry-run
|
||||
```
|
||||
|
||||
Prompt UI and progress are written to stderr so stdout remains available for
|
||||
structured results and pipelines. `NO_COLOR=1` disables color. Use
|
||||
`--accessible` for sequential, vertically rendered yes/no prompts. Implicit
|
||||
interactive setup requires stdin, stdout, and stderr to all be terminals; when
|
||||
any stream is redirected, setup stays non-interactive. Declining or cancelling
|
||||
returns status `cancelled` with exit code 0.
|
||||
|
||||
For automation, `rea setup --json` reports the plan and a compact `.doctor`
|
||||
readiness projection without applying it. Use `rea doctor --json` for full
|
||||
health diagnostics and canonical tool catalog details. Pair
|
||||
`--yes` with explicit scope such as `--client codex`, or use
|
||||
`--all-detected` when the broad scope is intended. Without a scope flag,
|
||||
`--yes` is limited to existing REA-owned registrations; it does not select all
|
||||
detected clients. An unapproved actual apply reports `needs_confirmation` and
|
||||
exits 1. Installing missing Hopper non-interactively additionally requires
|
||||
`--install-hopper`:
|
||||
|
||||
```bash
|
||||
rea setup --yes --all-detected --install-hopper --json
|
||||
```
|
||||
|
||||
### Skill destinations
|
||||
|
||||
The bundled skill is installed where each selected client discovers personal
|
||||
skills: Claude Code uses `~/.claude/skills` (or
|
||||
`$CLAUDE_CONFIG_DIR/skills` when configured). Gemini CLI uses `.agents/skills`
|
||||
under its selected home; Antigravity 2.0 uses `~/.gemini/config/skills`.
|
||||
Other integrations, including Qwen Code, use `~/.agents/skills`.
|
||||
A mixed selection plans each distinct destination. Selecting the skill without a client uses the shared
|
||||
directory. Setup leaves existing skill copies in other locations untouched.
|
||||
|
||||
`rea setup --skill-client claude_code --yes --json` refreshes and verifies the
|
||||
selected skill destination independently of MCP registration selection. The
|
||||
final `doctor.scope.skill_clients` records which skill destinations were
|
||||
checked; `doctor.scope.clients` continues to describe required registrations.
|
||||
An unselected shared skill does not affect a client-only refresh.
|
||||
|
||||
`doctor --skill --json` verifies the selected copies against the bundled
|
||||
instructions and references. Consumers should use `identity.skill.state`,
|
||||
`installed_version`, and `installed_tool_count` for skill readiness. The
|
||||
obsolete `installed_catalog_digest` field has been removed; current catalog
|
||||
identity remains available at `identity.catalog`.
|
||||
|
||||
Setup pins package-runner MCP registrations to the exact installed REA version,
|
||||
installs the matching skill and on-demand references in the same plan, and adds
|
||||
`startup_timeout_sec = 30` for Codex and Grok Build.
|
||||
|
||||
## Check readiness for your task
|
||||
|
||||
Run `rea doctor` when you need diagnosis. It reads host prerequisites and agent
|
||||
configuration without changing them. Without options, it audits every detected
|
||||
registration, the installed skill and optional analysis engines; its overall
|
||||
`healthy` value can be false while your chosen workflow works.
|
||||
|
||||
Select the part you want to check:
|
||||
|
||||
| Task | Readiness check |
|
||||
| ----------------------------------- | ------------------------------------------------------------------------ |
|
||||
| Static JavaScript/Electron analysis | Run `rea analyze-javascript-application PATH --json` directly. |
|
||||
| One analysis engine | `rea doctor --provider ghidra --json` (or `hopper`, `ida`) |
|
||||
| One agent registration | `rea doctor --client codex --json` (see [client IDs](#supported-agents)) |
|
||||
| Installed workflow instructions | `rea doctor --skill --json` |
|
||||
|
||||
A scoped report has `scope.mode: "explicit"`. Its `scope_checks` determine
|
||||
`healthy` and the exit status. Other checks appear in `informational_checks`;
|
||||
`environment_healthy` summarizes the full audit. `--target` adds a target check,
|
||||
but the report remains audit-wide unless a scope option is also supplied.
|
||||
|
||||
Follow the remediation for the failed check. If a native target has several
|
||||
available providers, choose one with `--provider` on the CLI or `provider_id`
|
||||
on `open_binary`. A `capability_unavailable` failure carries
|
||||
`details.selection_reason`: `ambiguous` asks you to choose from
|
||||
`details.candidate_ids`, while `provider_unavailable` asks you to repair the
|
||||
selected engine. See [provider selection](cli.md#choose-a-provider).
|
||||
|
||||
## Diagnose, update, and remove
|
||||
|
||||
`rea doctor --json` is strictly read-only. `rea update` updates only the npm or Bun global installation that owns the running CLI. Source checkouts and package-runner copies must be updated through the mechanism that owns them; a fresh package-runner invocation can use `npx rea-agents@latest` or `bunx rea-agents@latest`. `rea uninstall` removes only REA-owned agent registrations and skill files; `--purge-data` additionally removes REA cache and state paths.
|
||||
|
||||
```bash
|
||||
rea update
|
||||
rea uninstall
|
||||
rea uninstall --purge-data
|
||||
```
|
||||
|
||||
Uninstall preserves Hopper, Node.js, Evidence files, captures, unrelated skills
|
||||
and other MCP servers. Purging removes only REA's cache and state under
|
||||
`~/.rea`. A client configuration that is malformed, unreadable, or at an unsafe
|
||||
path stops the operation before anything is removed, and a client that fails
|
||||
while being updated stops the remaining removals. A purge path that is a
|
||||
symbolic link is retained and reported rather than followed. Uninstall checks
|
||||
REA's managed shared and Claude Code personal skill locations. See the
|
||||
[CLI guide](cli.md#output-and-exit-status) for exit statuses.
|
||||
|
||||
### Update the owning installation
|
||||
|
||||
`rea update` installs the exact resolved
|
||||
release into the npm prefix or Bun global directory that owns the running
|
||||
package, then checks the new executable's version before reporting success. It
|
||||
does not reopen onboarding. For npm installations, release lookup and
|
||||
installation both use npm's configured registry. Bun global updates require
|
||||
Bun 1.2.17 or later, which introduced `bun info`. The updater checks `bun --version`
|
||||
first and stops with an instruction to upgrade Bun manually if the version is
|
||||
older or cannot be parsed; it does not upgrade Bun itself.
|
||||
For supported Bun global installations, `bun info` and
|
||||
`bun add --global --ignore-scripts` use Bun's configured registry
|
||||
and run inside the owning Bun global directory (`BUN_INSTALL_GLOBAL_DIR`, else
|
||||
`$BUN_INSTALL/install/global`, else `$XDG_CACHE_HOME/.bun/install/global`,
|
||||
else `~/.bun/install/global`), never in the caller's current project. A Bun
|
||||
global directory without its `package.json` is not treated as an owned
|
||||
installation, because Bun would install into the nearest ancestor project
|
||||
instead.
|
||||
Its maintenance plan selects only existing REA registrations and an already
|
||||
installed REA skill. Run the returned scoped setup command to review and approve
|
||||
those changes, then restart affected agents. The plan is returned in terminal,
|
||||
non-TTY, and JSON modes without applying configuration changes.
|
||||
|
||||
## Released package and main
|
||||
|
||||
Repository main documents its current code and generated catalog. `@latest`
|
||||
selects the npm release, and persistent MCP registrations are pinned to the
|
||||
version that performed setup. Installing newer instructions does not update a
|
||||
running server or its registration.
|
||||
|
||||
The npm release checked on **2026-10-11** was **6.4.0**, published from
|
||||
[`a56f7bb6`](https://github.com/morluto/rea/commit/a56f7bb668ab23fec8d33f7af353ac7ed2fe1895).
|
||||
The actual registry package accepted dry-run setup plans for the 17 client IDs
|
||||
in that release, including Qwen Code, Pi and Hermes. DeepSeek Harness (`dsh`)
|
||||
is on main and is not in npm 6.4.0; `rea setup --client dsh` against `@latest`
|
||||
reports an unsupported client until a release containing it is published.
|
||||
OpenCode's plan selected
|
||||
`OPENCODE_CONFIG_DIR` even when that directory did not yet exist. These checks
|
||||
used an isolated home on macOS with Node 24; they verify planning and argument
|
||||
admission, without writing client configuration or establishing live integration
|
||||
with every client. This resolves the npm 6.3.0 setup gaps tracked in
|
||||
[#1650](https://github.com/morluto/rea/issues/1650).
|
||||
|
||||
Main's catalog describes the current code. A source build or a subsequent
|
||||
release containing changes after this checkpoint is required for newer
|
||||
functionality. Package startup alone does not verify a provider's real
|
||||
platform workflow.
|
||||
|
||||
To check the published version, run `npm view rea-agents dist-tags.latest`.
|
||||
Use the connected server's actual tool list and advertised input schemas for
|
||||
feature selection. The same package version string in a development checkout
|
||||
does not establish that its bytes match the npm tarball. Update a registration
|
||||
through a reviewed, scoped setup plan, then restart/reconnect the agent.
|
||||
|
||||
## Skill-only installation
|
||||
|
||||
```bash
|
||||
npx skills add morluto/rea --skill reverse-engineer-anything
|
||||
```
|
||||
|
||||
This installs agent instructions and bundled references, not REA MCP
|
||||
registration or analysis engines. Follow the skill's
|
||||
[conditional connection guide](https://github.com/morluto/rea/blob/main/.agents/skills/reverse-engineer-anything/SKILL.md#connect-only-when-needed).
|
||||
Working tools can be used immediately. If tools are missing, inspect the current
|
||||
client's registration with `doctor --client codex --json` (substitute its client
|
||||
ID), then plan repairs with `setup --client codex --dry-run --json`. Show and
|
||||
approve the exact changes before applying that scope. An aligned registration
|
||||
with tools absent from the active session needs a restart/reconnection;
|
||||
`doctor` checks files and prerequisites, not the live agent connection.
|
||||
|
||||
Guided setup installs the package's matching skill by default. The skills.sh
|
||||
route can select newer repository instructions, so follow actual server schemas
|
||||
and the release boundary above. Static JavaScript CLI inspection can proceed
|
||||
while MCP is unavailable:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||||
```
|
||||
|
||||
It returns the complete Evidence record directly and requires no native engine.
|
||||
Provider failures in doctor do not prevent unrelated target-free tools. To check
|
||||
readiness for one task instead of auditing every integration, see
|
||||
[Check readiness for your task](#check-readiness-for-your-task).
|
||||
|
||||
## Supported agents
|
||||
|
||||
Setup can configure these clients for REA's local MCP server. Grok Bot uses a manual
|
||||
hosted connector; see [its configuration](client-configuration.md#other-client-settings).
|
||||
|
||||
| Client | `--client` value |
|
||||
| ------------------ | ---------------- |
|
||||
| Claude Code | `claude_code` |
|
||||
| Claude Desktop | `claude_desktop` |
|
||||
| Codex | `codex` |
|
||||
| Cursor | `cursor` |
|
||||
| Gemini CLI | `gemini_cli` |
|
||||
| Windsurf | `windsurf` |
|
||||
| Devin | `devin` |
|
||||
| OpenCode | `opencode` |
|
||||
| Antigravity | `antigravity` |
|
||||
| GitHub Copilot CLI | `copilot_cli` |
|
||||
| Command Code | `commandcode` |
|
||||
| Qwen Code | `qwen_code` |
|
||||
| VS Code | `vscode` |
|
||||
| Grok Build | `grok_build` |
|
||||
| OMP | `omp` |
|
||||
| Pi | `pi` |
|
||||
| Hermes | `hermes` |
|
||||
| Qoder | `qoder` |
|
||||
| Trae | `trae` |
|
||||
| ZCode | `zcode` |
|
||||
| DeepSeek Harness | `dsh` |
|
||||
|
||||
`dsh` is main-only until a release after 6.4.0. The registry check above does
|
||||
not cover it.
|
||||
|
||||
See [client configuration and troubleshooting](client-configuration.md) for
|
||||
configuration paths, profiles, trust policies, and schema-limit workarounds.
|
||||
|
||||
### DeepSeek Harness
|
||||
|
||||
See [the Cordis patch and launcher setup](client-configuration.md#deepseek-harness).
|
||||
|
||||
### Other client settings
|
||||
|
||||
See [OpenCode, Grok Build, and Grok Bot settings](client-configuration.md#other-client-settings).
|
||||
|
||||
## Hopper
|
||||
|
||||
Hopper is separate commercial software with its own license. Its free demo has
|
||||
vendor-defined limits, and a paid license is optional. REA reuses any detected
|
||||
installation and preserves Hopper during uninstall.
|
||||
|
||||
The supported native host baseline is macOS 12+, Ubuntu 24.04+, Fedora 41+,
|
||||
Nobara 44+, 64-bit Arch Linux, CachyOS, or Omarchy. Ghidra and IDA have their own provider-specific
|
||||
host requirements; Windows Ghidra uses the [experimental P0 boundary](../providers/windows-ghidra-p0.md).
|
||||
|
||||
On macOS, approved setup downloads the official DMG, checks its published size
|
||||
and digest, validates the application bundle, and atomically installs it to
|
||||
`~/Applications/Hopper Disassembler.app`. REA then opens Hopper so the
|
||||
operator can choose its demo mode or activate an existing license. Homebrew and
|
||||
administrator access are not used.
|
||||
|
||||
The Hopper launcher action used by REA creates a document from an executable;
|
||||
its supported command-line interface does not attach to an already-open
|
||||
document. While another live REA session owns the same target and loader
|
||||
profile, a second session reports the owning run ID instead of opening a
|
||||
duplicate document. Closing the owning REA session releases this guard; Hopper
|
||||
keeps its document open. A later REA session can therefore open another
|
||||
document for the same target. REA does not currently identify, focus, or reuse
|
||||
that existing GUI document, and the supported launcher exposes no attach or
|
||||
reuse action for it.
|
||||
|
||||
On supported Linux distributions, approved setup verifies Hopper's official
|
||||
`.deb`, `.rpm`, or Arch package before invoking the native package manager.
|
||||
REA runs the supported demo build on a private Xvfb display and selects Hopper's
|
||||
offered demo mode for each analysis session; it does not require the user's
|
||||
desktop display. Unattended package-manager access requires
|
||||
`--yes --install-hopper`. If the host exposes `/tmp/.X11-unix` as an immutable
|
||||
mount, REA first verifies the conflict and then uses an unprivileged user and
|
||||
mount namespace with a private mode-1777 tmpfs over that directory only. The
|
||||
host mount and the rest of `/tmp` remain unchanged; this fallback never invokes
|
||||
`sudo`. `rea doctor --provider hopper --json` reports the selected
|
||||
strategy and both host and effective mount facts.
|
||||
|
||||
The supported Linux demo forwards additional launches into its existing
|
||||
application, even across private displays. REA therefore reserves one Linux
|
||||
Hopper application per user across cooperating REA processes. A competing
|
||||
CLI or MCP session receives the owning session ID before Hopper is launched,
|
||||
for both the same target and a different target. Switch targets through that
|
||||
MCP session, or close it before starting another session. Closing the owner
|
||||
releases the reservation. This does not attach to or claim ownership of
|
||||
manually opened Hopper applications.
|
||||
|
||||
Stale lease recovery is serialized. If an interrupted recovery leaves its
|
||||
reservation directory, the diagnostic identifies that exact path. Stop REA
|
||||
sessions before removing that recovery directory and retrying.
|
||||
|
||||
### Launcher paths and troubleshooting
|
||||
|
||||
On macOS, REA uses
|
||||
`/Applications/Hopper Disassembler.app/Contents/MacOS/hopper` by default.
|
||||
On Linux, it prefers executable `/opt/hopper/bin/Hopper`, then executable
|
||||
`~/.local/share/rea/hopper/bin/Hopper`; if neither exists, the former remains
|
||||
the diagnostic fallback. `HOPPER_LAUNCHER_PATH` overrides those choices:
|
||||
|
||||
```bash
|
||||
export HOPPER_LAUNCHER_PATH=/absolute/path/to/Hopper
|
||||
rea doctor --provider hopper --json
|
||||
```
|
||||
|
||||
Hopper startup allows 120,000 ms for launch, initial analysis, and authenticated
|
||||
bridge readiness. For large targets, set `REA_HOPPER_STARTUP_TIMEOUT_MS` to a
|
||||
decimal integer from 1 to 2,147,483,647 milliseconds in the environment that
|
||||
starts REA. CLI and MCP use the same setting; invalid values fail configuration
|
||||
validation. An MCP client's own request timeout must also allow enough time.
|
||||
|
||||
If macOS denies Apple Events, allow the application that starts REA under
|
||||
**System Settings → Privacy & Security → Automation**, then retry. REA releases
|
||||
the target reservation when the native helper reports its complete authorization
|
||||
rejection and its arguments cannot alter the helper's generated AppleScript.
|
||||
Arguments containing quotes, backslashes, or line breaks remain unchanged but
|
||||
cannot establish that a failed handoff opened no document. Other failed handoffs
|
||||
retain ownership until document closure is confirmed. If a timed-out bridge
|
||||
becomes ready later, `close_binary` connects to that run, authenticates its
|
||||
identity, and requests document shutdown. After a connection drops, the bridge
|
||||
allows 30 seconds for an authenticated cleanup reconnect, then releases Hopper's
|
||||
Python execution thread. Expiry does not establish document closure, so REA
|
||||
retains unconfirmed ownership. Retry close while the bridge remains available.
|
||||
|
||||
If a Linux launcher exists but cannot start, inspect its shared libraries:
|
||||
|
||||
```bash
|
||||
ldd /absolute/path/to/Hopper | grep 'not found'
|
||||
```
|
||||
|
||||
Install the missing packages and rerun the scoped check. Linux demo sessions
|
||||
need Xvfb, Python 3, X11 and XTEST; approved setup installs those dependencies
|
||||
on supported distributions. Add the curl installer's reported executable
|
||||
directory, commonly `~/.local/bin`, to your shell `PATH` if needed.
|
||||
|
||||
REA starts Hopper when needed. On macOS, complete its demo or license prompt in
|
||||
the same user session before the first CLI/MCP operation or unattended job. Open
|
||||
Hopper manually if needed; its launcher can also bring the dialog forward.
|
||||
If startup reports `Cannot launch Hopper! Connection is invalid.` or waits for
|
||||
bridge readiness, check Hopper for a pending demo, license, or loader dialog.
|
||||
Complete the dialog and retry. If REA reports `cleanup_incomplete`, follow the
|
||||
retained-resource guidance below before reopening the target.
|
||||
Hopper serializes analysis requests. Cancelling a wait can leave provider work
|
||||
running, which the session reports. Successful decompilation is cached until
|
||||
a relevant rename or comment changes it.
|
||||
|
||||
Analysis and annotation calls stay bound to the active target's native Hopper
|
||||
document, even when GUI focus changes or other documents have the same display
|
||||
name. Use `open_binary` to change targets. Byte reads stop at a segment boundary
|
||||
and return the readable prefix with `complete: false`. File-offset mapping checks
|
||||
the reverse lookup and original executable bounds; synthetic external-symbol
|
||||
memory has no original file offset. For FAT Mach-O, offsets refer to the original
|
||||
container file. Results retain Hopper's image-relative offset, the observed slice
|
||||
base, and the source executable path.
|
||||
Loader selection reads the Mach-O container header, including FAT files with a
|
||||
single architecture. For FAT64, REA validates the architecture table and selected
|
||||
Mach-O header, prepares a private thin image, and loads it with Hopper's native
|
||||
Mach-O loader. It checks the entire source's SHA-256 while copying the slice;
|
||||
source identity and reported offsets still refer to the original container.
|
||||
An ambiguous architecture subtype requires an explicitly extracted thin image;
|
||||
REA does not guess. Configured loader arguments remain explicit overrides.
|
||||
FAT64 is distinct from the CPU architecture: FAT32 containers can contain 64-bit
|
||||
executable images. This preparation avoids the Raw Binary loader dialog observed
|
||||
with native FAT64 loading on Hopper 6.1.0-demo.
|
||||
The prepared image and its owned document close together, including on MCP exit;
|
||||
if document closure is unconfirmed, REA retains the backing image and reports
|
||||
`cleanup_incomplete` with its path. Ordinary documents retain their existing
|
||||
MCP-exit behavior.
|
||||
Startup deadlines report missing bridge readiness and preserve the launcher
|
||||
outcome; a successful helper exit does not prove that a loader dialog completed.
|
||||
If an owned provider process exits, request failures preserve its observed exit
|
||||
code or signal and bounded output in `details.launcher`. An exit can precede
|
||||
output-stream closure; `output_closed: false` keeps that uncertainty explicit.
|
||||
Later requests retain the known exit instead of reducing it to socket loss.
|
||||
An external GUI's helper exit does not establish that the GUI itself exited.
|
||||
For cursor navigation, string decoding, symbol-name limits, and regex matching,
|
||||
see [Hopper analysis behavior](../guides/native/native-investigation.md#hopper-analysis-behavior).
|
||||
|
||||
Closing or switching a target closes its bound Hopper document, shuts down REA's
|
||||
bridge and removes its temporary socket directory while preserving the Hopper
|
||||
application and unrelated documents. A `cleanup_incomplete`
|
||||
result identifies resources whose cleanup could not be verified.
|
||||
REA retains unresolved cleanup ownership and any confirmed shutdown phases.
|
||||
After addressing the reported failure, retry `close_binary` on the same
|
||||
connection. Unconfirmed document or process cleanup retains the target/application
|
||||
lease and prevents another client from launching against that owned resource.
|
||||
Once document and process closure are confirmed, the lease can be released even
|
||||
if temporary-file cleanup fails. Another client can then launch, but the owning
|
||||
client must finish its retained cleanup before starting again.
|
||||
An unconfirmed external document can be retried while its authenticated bridge
|
||||
remains connected. If that bridge has disconnected, another close cannot confirm
|
||||
the document: inspect and close the reported document in Hopper before ending
|
||||
the owning REA connection.
|
||||
|
||||
### Hopper in CI
|
||||
|
||||
REA's unattended Linux path is validated against Hopper's offered demo mode.
|
||||
A paid license is not required for that path, and REA does not read, install, or
|
||||
automate license credentials. Licensed Hopper installations remain supported,
|
||||
but license activation is an operator-owned prerequisite rather than part of
|
||||
REA setup.
|
||||
|
||||
macOS requires Hopper's first-run UI to be completed in the same user session
|
||||
that will run REA: choose the demo mode or activate an existing license before
|
||||
starting an unattended job. Ephemeral macOS runners therefore need a
|
||||
pre-provisioned user session or a deliberate interactive bootstrap step.
|
||||
|
||||
When Hopper cannot start in CI, run
|
||||
`rea doctor --provider hopper --json` in the failing runner.
|
||||
Structured failures distinguish private-display dependencies, an unsupported
|
||||
demo dialog or build, process-ownership conflicts, and an early lifecycle exit.
|
||||
Apply the reported remediation rather than exposing the runner's desktop,
|
||||
copying license secrets into logs, or killing unrelated Hopper processes.
|
||||
|
||||
## Ghidra
|
||||
|
||||
REA connects to an existing Ghidra installation on Linux x64/arm64, macOS x64/arm64,
|
||||
or experimental Windows x64 P0.
|
||||
It accepts Ghidra 12.1.x and the 64-bit full JDK declared by that installation's
|
||||
`application.java.min` and `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. Each installation must include the native decompiler for the host
|
||||
architecture in `Ghidra/Features/Decompiler/os/<platform>/` or the corresponding
|
||||
`build/os/<platform>/` directory. Linux ARM64 uses `linux_arm_64`; official
|
||||
release archives may require you to build that native component separately.
|
||||
REA checks the executable prerequisite by inspecting the file's own executable
|
||||
header, so a native component built for another platform or architecture is
|
||||
reported as incompatible instead of being admitted from its directory name, and
|
||||
a header that cannot be read or recognized is reported as unknown. REA does not
|
||||
build or install native tools, or change Gatekeeper quarantine settings.
|
||||
|
||||
The adapter exposes 25 read-only operations: thirteen inventory/name/search
|
||||
operations and twelve function-analysis operations. These cover metadata,
|
||||
decompilation, assembly, resolved calls, typed references, xrefs, function
|
||||
dossiers, instructions, recovered data types, measured load mappings, loaded
|
||||
memory bytes, and observed file offsets. Independent load-image attestation
|
||||
supports DOS MZ, explicitly selected COM, and explicit raw-binary imports;
|
||||
PE returns measurements with an unsupported attestation status.
|
||||
On Linux and macOS, `annotate_native_function` also edits a function name and/or
|
||||
entry comments atomically and returns refreshed analysis, and `set_address_name`
|
||||
and `set_addresses_names` name a function entry or any other mapped address
|
||||
(creating or renaming its primary label) with per-address success results. These
|
||||
session metadata edits leave executable bytes unchanged and are discarded on close. GUI controls
|
||||
require Hopper; Windows P0 remains read-only.
|
||||
|
||||
Windows P0 admits native x86 and x86-64 PE applications and DLLs on fixed local NTFS volumes.
|
||||
The npm package bundles native Job Object ownership, protected private runtime
|
||||
DACLs, and handle-based path admission; no separate addon installation is needed.
|
||||
See the [Windows Ghidra P0 guide](../providers/windows-ghidra-p0.md) for verified scope and
|
||||
limitations.
|
||||
|
||||
Extract Ghidra and install the JDK outside REA, then export absolute paths:
|
||||
|
||||
```bash
|
||||
export GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.1.4_PUBLIC
|
||||
export JAVA_HOME=/absolute/path/to/jdk-21 # optional if java/javac are on PATH
|
||||
rea doctor --json
|
||||
rea setup
|
||||
```
|
||||
|
||||
On Windows, configure the existing installation in PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:GHIDRA_INSTALL_DIR = "C:\tools\ghidra_12.1.4_PUBLIC"
|
||||
$env:JAVA_HOME = "C:\Program Files\Java\jdk-21"
|
||||
rea doctor --json
|
||||
rea providers --json
|
||||
```
|
||||
|
||||
`rea setup` can configure supported Windows agents and install the bundled
|
||||
REA skill after approval. Direct registrations use Node to launch REA's entry
|
||||
script; package-runner registrations use the pinned `npx` or `bunx` command. Hopper
|
||||
installation remains unavailable on Windows. Setup never installs Ghidra,
|
||||
Java, or Python. It preserves valid detected Ghidra/JDK settings in agent
|
||||
registrations. See [Windows Ghidra P0](../providers/windows-ghidra-p0.md) for provider diagnostics.
|
||||
|
||||
Doctor validates the platform, architecture, Ghidra 12.1.x application version,
|
||||
`support/analyzeHeadless` or `support/analyzeHeadless.bat`, the installation's
|
||||
Java major range, 64-bit JDK bitness, and the presence of `javac`/`javac.exe`.
|
||||
When Java is found through `PATH`, setup records its observed JDK home so GUI
|
||||
MCP clients do not depend on an incidental shell path. Setup shows every exact
|
||||
environment entry in its plan, writes only after approval, and never downloads,
|
||||
installs, upgrades, or modifies Ghidra or Java.
|
||||
|
||||
Each verified session uses an ephemeral temporary project and isolated
|
||||
home/cache/config/temp paths. REA passes `-readOnly`, `-deleteProject`, uses
|
||||
Ghidra's default analysis settings, and loads its packaged Java
|
||||
bridge via `-scriptPath`; it never opens an existing user project. Linux and
|
||||
macOS use a current-user-only local bridge socket and descriptor. The
|
||||
project remains under the selected temporary directory. If its Unix socket
|
||||
pathname would exceed the host's byte limit, REA allocates a separate owner-only
|
||||
socket directory under `/tmp` and removes it on close, cancellation, or failure.
|
||||
Diagnostics retain the actual endpoint and both owned directories.
|
||||
On Linux and macOS, REA starts the inspected JVM directly using Ghidra's own LaunchSupport
|
||||
configuration. Apple platform shell wrappers hide their environments from
|
||||
ownership inspection, so retaining those wrappers would prevent verified
|
||||
process-group cancellation during startup.
|
||||
If ownership remains unverifiable, it reports the reason and retains the process
|
||||
supervisor and private runtime instead of removing files beneath a live provider.
|
||||
The experimental Windows transport uses authenticated IPv4 loopback with a
|
||||
private native-owned bearer descriptor and Job Object process ownership.
|
||||
|
||||
Operations begin only after default auto-analysis completes. `open_binary`
|
||||
selects and validates the target/provider binding; it does not wait for Ghidra
|
||||
import and auto-analysis. The first Ghidra-backed query starts that work lazily.
|
||||
The provider startup deadline is 330,000 ms by default for import, analysis,
|
||||
bridge, and health readiness. Large binaries can need more: set
|
||||
`REA_GHIDRA_STARTUP_TIMEOUT_MS` to an integer between 1 and 2,147,483,647
|
||||
milliseconds in the server environment. An absent setting uses the default;
|
||||
empty, invalid or out-of-range supplied values fail configuration validation.
|
||||
REA parses the supplied configuration environment and
|
||||
passes the deadline to each provider client; a startup failure is returned by the query that triggered it,
|
||||
without exposing partial analysis. This deadline is separate from MCP transport
|
||||
initialization and the client's deadline for that individual tool call. A client
|
||||
can time out earlier even when Ghidra would complete within its startup deadline.
|
||||
See [Ghidra first-query deadlines and recovery](../reference/mcp-contracts.md#ghidra-first-query-deadlines-and-recovery)
|
||||
for client options and the close/reopen recovery flow.
|
||||
|
||||
One session contains exactly one imported Program; use `provider_id: "ghidra"`, `--provider ghidra`, or
|
||||
`REA_ANALYSIS_PROVIDER=ghidra` when both Hopper and Ghidra support the target.
|
||||
One persistent decompiler is owned by the Program, and a serial queue keeps
|
||||
Ghidra API calls on the owning Program thread without a fixed queue length.
|
||||
Operations run until a result, caller cancellation, or provider shutdown; there
|
||||
is no fixed per-operation or response-size ceiling. Unresolved computed calls
|
||||
remain unknown, reference-kind provenance is preserved, and provider-specific
|
||||
pseudocode is never treated as original source or Hopper-equivalent text.
|
||||
|
||||
### Missing macOS native decompiler
|
||||
|
||||
If `rea doctor --json` reports `native_decompiler` as missing on macOS x64,
|
||||
the extracted Ghidra archive may include the decompiler source without the
|
||||
macOS executable. For Ghidra 12.1.4, you can build it manually with an existing
|
||||
Xcode Command Line Tools installation, `make`, and `bison`:
|
||||
|
||||
```bash
|
||||
cd "$GHIDRA_INSTALL_DIR/Ghidra/Features/Decompiler/src/decompile/cpp"
|
||||
make ghidra_opt
|
||||
decompiler_dir="$GHIDRA_INSTALL_DIR/Ghidra/Features/Decompiler/os/mac_x86_64"
|
||||
mkdir -p "$decompiler_dir"
|
||||
test ! -e "$decompiler_dir/decompile" && test ! -L "$decompiler_dir/decompile" &&
|
||||
install -m 755 ghidra_opt "$decompiler_dir/decompile"
|
||||
rea doctor --json
|
||||
```
|
||||
|
||||
The copy step requires the destination to be absent and preserves an existing
|
||||
decompiler. This recipe is specific to macOS x64: the
|
||||
[Ghidra 12.1.4 Makefile](https://github.com/NationalSecurityAgency/ghidra/blob/Ghidra_12.1.4_build/Ghidra/Features/Decompiler/src/decompile/cpp/Makefile)
|
||||
explicitly selects `-arch x86_64` on Darwin. For other architectures or a Gradle
|
||||
build, follow the matching release's
|
||||
[native component instructions](https://github.com/NationalSecurityAgency/ghidra/blob/Ghidra_12.1.4_build/GhidraDocs/GettingStarted.md#building-native-components).
|
||||
REA accepts the matching executable under either `os/<platform>/` or
|
||||
`build/os/<platform>/`; it does not build the component during setup or diagnosis.
|
||||
|
||||
### Ghidra import language and analysis seeds
|
||||
|
||||
Ghidra detects the language from the executable header. To set it (for example, Borland C++ PE images):
|
||||
|
||||
```bash
|
||||
export REA_GHIDRA_LANGUAGE_ID="x86:LE:32:default"
|
||||
export REA_GHIDRA_COMPILER_SPEC_ID="borlandcpp" # optional; requires a language
|
||||
```
|
||||
|
||||
REA passes `-processor`/`-cspec`, checks both against the installation's `.ldefs`, and records them in the analysis profile. DOS imports reject an override.
|
||||
|
||||
To seed code that auto-analysis cannot reach (computed jumps, pointers in data):
|
||||
|
||||
```bash
|
||||
export REA_GHIDRA_SEED_FILE=/absolute/path/to/seeds.tsv
|
||||
```
|
||||
|
||||
Each line is `address<TAB>kind[<TAB>name]`, where kind is `function`, `code` or `label` (a label needs a name). Addresses are `0x` hex in the default space; `#` lines are comments. A pre-script applies seeds before auto-analysis: functions from the highest address down, then code, then labels. The seed digest is part of the analysis profile, and the session fails if the applied seeds differ. Result limitations report the outcome counts; a seed fails when it overlaps an instruction Ghidra already decoded.
|
||||
|
||||
Label seeds can name mapped uninitialized storage such as `.bss`; function and code seeds require initialized bytes.
|
||||
|
||||
To skip a named Ghidra auto-analyzer (for example, when default auto-analysis
|
||||
stalls in one analyzer on a Swift/Objective-C arm64 Mach-O):
|
||||
|
||||
```bash
|
||||
export REA_GHIDRA_DISABLED_ANALYZERS="Objective-C Message Analyzer"
|
||||
```
|
||||
|
||||
The value is a comma-separated list of exact Ghidra analyzer names. A pre-script
|
||||
disables each name before auto-analysis, the analysis profile records the
|
||||
override in `analyzer_preset` (for example
|
||||
`ghidra-default+disabled:Objective-C Message Analyzer`), and a session fails to
|
||||
open when its committed profile and the setting differ. A name starts with a
|
||||
letter or digit and contains only letters, digits, spaces, periods, underscores,
|
||||
and hyphens; at most 32 names are admitted, each at most 120 characters.
|
||||
Names must identify analyzers registered for the selected program. Unknown names
|
||||
or options that remain enabled abort the headless import before auto-analysis
|
||||
and the bridge, so an unsuccessful override cannot produce a session claiming
|
||||
that the analyzer was disabled. For Windows PE resource analysis, the exact name
|
||||
is `WindowsResourceReference`. Disabling an analyzer skips the facts it would
|
||||
have produced.
|
||||
|
||||
### Ghidra heap and CPU controls
|
||||
|
||||
Set resource controls in the environment that launches the CLI or MCP server,
|
||||
before opening a new Ghidra session. On Linux and macOS, REA chooses the first
|
||||
nonempty setting in this order: `GHIDRA_HEADLESS_MAXMEM`, `GHIDRA_MAXMEM`, then
|
||||
`2G`. The chosen value becomes the JVM's `-Xmx` argument. Use a JVM heap-size
|
||||
value such as `512M` or `2G`; an invalid value causes Java startup to fail.
|
||||
The supported Ghidra 12.1.4 Windows headless script consumes the same settings
|
||||
with the same precedence.
|
||||
|
||||
For a small target on a constrained host:
|
||||
|
||||
```bash
|
||||
export GHIDRA_HEADLESS_MAXMEM=512M
|
||||
```
|
||||
|
||||
In PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:GHIDRA_HEADLESS_MAXMEM = "512M"
|
||||
```
|
||||
|
||||
An MCP client must pass this setting to its REA server process; changing an
|
||||
unrelated terminal's environment does not reconfigure an existing server or
|
||||
JVM. A 512 MiB heap was verified with small native fixtures, but larger targets
|
||||
can require more memory. The Java heap limit does not bound JVM RSS, Node's
|
||||
heap, or total memory used by the process family. The startup deadline controls
|
||||
waiting time independently of these memory settings.
|
||||
|
||||
REA clears `_JAVA_OPTIONS`, `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, and
|
||||
`GHIDRA_JAVA_OPTIONS` inherited from the caller, and owns
|
||||
`GHIDRA_HEADLESS_JAVA_OPTIONS`. Custom flags injected through these variables
|
||||
are not supported configuration. On Windows, REA replaces `JDK_JAVA_OPTIONS`
|
||||
with its own isolated home/temp settings and `-XX:-UsePerfData`; on Linux and
|
||||
macOS it supplies isolated paths directly to Java. Use the supported heap
|
||||
settings above instead of adding a second `-Xmx` through an injection variable.
|
||||
|
||||
The Linux/macOS launch sets `-XX:ParallelGCThreads=2` and
|
||||
`-XX:CICompilerCount=2`; the supported Windows headless script also sets these
|
||||
counts. These constrain particular JVM thread pools, not all analysis threads
|
||||
or CPU usage. REA does not pass Ghidra's `-max-cpu` option or expose a general
|
||||
Ghidra CPU limit. When needed, apply host CPU affinity and scheduling controls
|
||||
to the REA process and verify the resulting JVM's affinity. Select CPUs allowed
|
||||
on the host; do not assume CPU numbers from another machine are valid.
|
||||
|
||||
Verify controls at their consumer after the first Ghidra-backed query starts
|
||||
the JVM: inspect that owned JVM's effective `-Xmx` and GC/compiler flags, CPU
|
||||
affinity, and observed memory use. Do not infer them from the parent shell's
|
||||
environment or the absence of an error. On Linux, `/proc/<jvm-pid>/cmdline`
|
||||
contains the launch arguments and `/proc/<jvm-pid>/status` reports
|
||||
`Cpus_allowed_list` and `VmRSS`. Inspect only the process belonging to this
|
||||
session and retain the resource flags needed for the measurement rather than
|
||||
copying full command lines or environments into reports. Heap and affinity
|
||||
settings affect cost and latency; they are not part of REA's semantic analysis
|
||||
profile identity. See [real-provider testing](../development/testing.md) for bounded
|
||||
verification workflows.
|
||||
|
||||
### Ghidra diagnostics and verification
|
||||
|
||||
Unexpected request failures retain their original internal cause. CLI and MCP
|
||||
errors expose Error names, messages, and available codes under
|
||||
`details.diagnostics.failure_cause`, including bounded nested causes and explicit
|
||||
truncation markers. Darwin ownership-helper compilation failures also retain
|
||||
the compiler outcome, exit code or signal, and bounded stderr; a timed-out
|
||||
compiler remains distinguishable from a compiler that exited with an error.
|
||||
Other rejection values retain their primitive value or an explicit type.
|
||||
Shutdown warnings include the failure
|
||||
kind, message, and diagnostics, while process and temporary-project cleanup
|
||||
continues. These messages redact known bridge authentication tokens and
|
||||
preserve local paths and other analysis context.
|
||||
|
||||
Run `GHIDRA_INSTALL_DIR=... npm run verify:ghidra` from a source checkout to
|
||||
compile and analyze debug and stripped host-native fixtures (ELF on Linux x64/arm64
|
||||
or Mach-O on macOS), plus a native DWARF 4 type-layout object. This lane needs a
|
||||
host C compiler in addition to Ghidra and its JDK.
|
||||
|
||||
Run `GHIDRA_INSTALL_DIR=... npm run verify:ghidra:cross-format` to add AArch64
|
||||
ELF, x86-64 PE, and x86-64 Mach-O fixture coverage. This separate lane needs
|
||||
`clang`, LLD, and `lld-link` on `PATH`; `REA_CLANG` and `REA_LLD_LINK` select
|
||||
alternate command paths. Missing cross-target tooling does not block the
|
||||
host-native Ghidra acceptance lane.
|
||||
|
||||
On a controlled Windows x64 runner, use
|
||||
`npm run verify:ghidra:windows`. The verifier generates a deterministic native
|
||||
PE fixture from source bytes and requires the Windows native authority before
|
||||
opening the provider. The controls are implemented on main; see the
|
||||
[release boundary](#released-package-and-main). The lane verifies all 25 admitted
|
||||
read-only operations, digest identity, and runtime cleanup. The separate
|
||||
`verify:ghidra:windows:package` lane checks the packed CLI/MCP boundary with an
|
||||
ordinary user. It requires the built Windows native bundle and an existing
|
||||
Ghidra/JDK installation; neither is inferred from startup alone.
|
||||
|
||||
## MCP Registry
|
||||
|
||||
REA is published in the official MCP Registry as `io.github.morluto/rea`. Registry
|
||||
clients can discover the server and install the existing public `rea-agents` npm
|
||||
package; the Registry entry does not introduce a second distribution artifact.
|
||||
|
||||
For a client that supports Registry discovery, search for `io.github.morluto/rea`
|
||||
and select the npm package. The published metadata launches the existing stdio
|
||||
server through `npx` with the `mcp` command.
|
||||
|
||||
For a client that requires manual configuration, use:
|
||||
|
||||
<!-- x-release-please-start-version -->
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"rea": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "rea-agents@6.4.0", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<!-- x-release-please-end -->
|
||||
|
||||
Persistent registrations should use one exact package version. `rea setup`
|
||||
writes the same package-runner shape, or `bunx rea-agents@<version> mcp` when
|
||||
setup runs through `bunx`, and pins it to the exact version that performed
|
||||
setup. Run current setup to refresh an older registration, then restart the
|
||||
client.
|
||||
|
||||
## Package runners and global installation
|
||||
|
||||
A package-runner invocation can use a REA version installed in the current project. To
|
||||
request the latest release explicitly, use:
|
||||
|
||||
```bash
|
||||
npx rea-agents@latest setup
|
||||
```
|
||||
|
||||
REA runs the version npm selects. To update older agent registrations, run the
|
||||
latest-version command and review its setup plan. For unattended package
|
||||
downloads, add `--yes` before the package name; this does not approve REA's
|
||||
setup changes.
|
||||
|
||||
For an intentional rollback, make the package request explicit:
|
||||
|
||||
```bash
|
||||
npm exec --yes --package=rea-agents@2.4.0 -- rea setup
|
||||
```
|
||||
|
||||
Setup continues to pin persistent MCP registrations to the exact version that
|
||||
performed setup. Running current setup later migrates unversioned or older
|
||||
managed registrations through the normal reviewed setup transaction.
|
||||
|
||||
With Bun, `bunx rea-agents setup` (or `bunx rea-agents@latest setup`) is the
|
||||
equivalent entry point. Setup run through `npx` registers
|
||||
`npx -y rea-agents@<version> mcp`; setup run through `bunx` or `bun x` registers
|
||||
`bunx rea-agents@<version> mcp`. On Windows, setup wraps either command in
|
||||
`cmd.exe /d /c` so clients can start the runner's command shim. Neither
|
||||
registration points into the runner's temporary package cache.
|
||||
|
||||
REA supports Node.js 22.x (>=22.19), 24.x (>=24.11), and 26+. Node.js 23, 25, and prereleases are unsupported. It uses the npm already paired with that runtime and never upgrades Node.js, npm, or Homebrew.
|
||||
|
||||
When REA runs on Bun, the `rea doctor` `node` check reports the Bun version and
|
||||
the Node.js compatibility version Bun declares, and passes when that
|
||||
compatibility version is in the supported range. Bun does not enforce the V8
|
||||
heap flags REA gives its owned helper processes, so Evidence that reports those
|
||||
limits on Node.js records them as unavailable under Bun. On Windows, the owned
|
||||
Job Object of each JavaScript helper (source analyzer, source-map codec and HAR
|
||||
decoder) instead limits its committed memory to that helper's heap budget plus
|
||||
a 512 MiB reserve for Bun itself, and Evidence reports that limit. This needs
|
||||
the matching bundled Windows native artifact; an artifact without the control
|
||||
refuses to start the helper rather than running it unlimited. CI tests Node.js
|
||||
only.
|
||||
|
||||
Running `npm install rea-agents` without `--global` installs the executable only
|
||||
in the current project's `node_modules/.bin`; it does not make `rea` available
|
||||
on the shell `PATH`. Use the setup command above for the guided setup
|
||||
journey, `npx -y rea-agents@latest` for unattended one-off commands, or install globally
|
||||
with `npm install --global rea-agents` for a shell-visible `rea` command.
|
||||
|
||||
The optional curl wrapper installs only the global npm package:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash
|
||||
```
|
||||
|
||||
It prints the version, runtime, npm command, and destination before installing. When a controlling terminal exists it starts `rea setup`; otherwise it prints the command to run later.
|
||||
|
||||
Pass options with `bash -s --`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh |
|
||||
bash -s -- --dry-run
|
||||
```
|
||||
|
||||
Supported options are `--version <semver>`, `--dry-run`, `--no-setup`, `--no-prompt`, and `--verbose`. Neither `--no-prompt` nor a non-interactive shell grants permission to install external dependencies.
|
||||
@@ -0,0 +1,128 @@
|
||||
# Guided MCP prompts and completion
|
||||
|
||||
REA exposes six provider-neutral investigation workflows through the MCP
|
||||
`prompts` capability. They complement the generated tool catalog; they do not add, remove, or
|
||||
invoke tools by themselves.
|
||||
|
||||
## Prompt inventory
|
||||
|
||||
| Prompt | Purpose |
|
||||
| --------------------------------- | ------------------------------------------------------------------------------------ |
|
||||
| `investigate_feature` | Trace a feature from discovery into relevant function evidence. |
|
||||
| `compare_application_versions` | Compare two shipped artifacts, with optional static and runtime follow-up. |
|
||||
| `verify_reconstruction` | Evaluate a finite reconstruction specification against retained comparison Evidence. |
|
||||
| `trace_crash` | Correlate a crash symptom with static paths and optional process capture evidence. |
|
||||
| `audit_residual_unknowns` | Audit current residual-unknown heads and evidence-qualified resolution. |
|
||||
| `prepare_bounded_process_capture` | Design a bounded controlled process experiment before execution. |
|
||||
|
||||
Every rendered prompt provides optional starting points using current REA tool
|
||||
names. Agents can call tools directly, skip irrelevant suggestions, and inspect
|
||||
provider or target state only when it helps answer the request or a tool
|
||||
requires it. The prompts also ask agents to keep observations, inferences, and
|
||||
unknowns distinct. Requested prompt arguments and completion choices are
|
||||
rendered as untrusted selection data, not instructions or authorization.
|
||||
Tool results include their Evidence inline. Prompts do not require a bundle or
|
||||
resource fetch to read a result; an Evidence ID is only a reference when a
|
||||
prompt argument or tool explicitly accepts one.
|
||||
|
||||
For a JavaScript/Electron application directory, `investigate_feature` points
|
||||
directly to `analyze_javascript_application` with `input_path`; it does not
|
||||
require `open_binary`. When that Evidence, or `inspect_binary_layout` Evidence,
|
||||
is already retained, it suggests `inspect_analysis_view` before tracing a
|
||||
feature seed. The CLI equivalent is `rea analyze <directory>`.
|
||||
`open_binary` and the doctor target check admit files and macOS app bundles.
|
||||
A directory outside that opening route is reported with an available analysis
|
||||
action; this does not establish support for every directory format.
|
||||
|
||||
For target paths in `compare_application_versions`, the prompt suggests
|
||||
opening each target before calling `inspect_artifact`; inspection operates on
|
||||
the active target and returns the graph and findings together inline.
|
||||
|
||||
Use standard MCP discovery and retrieval:
|
||||
|
||||
```json
|
||||
{ "method": "prompts/list", "params": {} }
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "prompts/get",
|
||||
"params": {
|
||||
"name": "investigate_feature",
|
||||
"arguments": {
|
||||
"feature": "offline search",
|
||||
"document": "Notes"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The server advertises `listChanged: true`. Updating a registered guided prompt
|
||||
emits `notifications/prompts/list_changed`, allowing clients to refresh their
|
||||
cached prompt catalog.
|
||||
|
||||
## Session-aware completion
|
||||
|
||||
MCP `completion/complete` completes guided-prompt arguments; it does not define
|
||||
completion for arbitrary tool-call arguments. REA attaches completion to
|
||||
optional prompt arguments that accept a session value. Suggestions provide
|
||||
identifiers only; they do not retrieve or replace the inline Evidence result.
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "completion/complete",
|
||||
"params": {
|
||||
"ref": {
|
||||
"type": "ref/prompt",
|
||||
"name": "investigate_feature"
|
||||
},
|
||||
"argument": {
|
||||
"name": "procedure",
|
||||
"value": "0x10"
|
||||
},
|
||||
"context": {
|
||||
"arguments": {
|
||||
"document": "Notes"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Completion sources are live projections of the current session:
|
||||
|
||||
Document and procedure completion in a binary session reads an already-ready
|
||||
provider; it does not start analysis. A cold provider, a target transition, or
|
||||
unavailable inventory can return no suggestions. Run an analysis query first
|
||||
when you need inventory from a provider that supplies it. An empty completion
|
||||
list does not establish that the target has no procedures.
|
||||
|
||||
| Argument family | Source and filtering |
|
||||
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Document | Current provider `list_documents` result. |
|
||||
| Procedure | The complete `list_procedures` inventory; all procedure addresses and uniquely named procedures are offered. Optional document context is forwarded. |
|
||||
| Provider | `auto` plus sorted deep candidates from the current binary session; target-free completion does not start them. |
|
||||
| Evidence | Evidence IDs retained in the current session ledger, offered only for prompt arguments that accept Evidence references. |
|
||||
| Process capture | IDs for retained Evidence whose operation and validated result identify process capture. |
|
||||
| Artifact manifest | Manifest IDs from schema-valid retained artifact inventories. |
|
||||
| Artifact occurrence | Occurrence IDs present in schema-valid retained artifact inventory pages. |
|
||||
| Residual unknown | Current non-resolved unknown heads only. |
|
||||
|
||||
Suggestions are Unicode-normalized, case-insensitive prefix matches. The server
|
||||
deduplicates them and sorts by code point for deterministic results. Procedure
|
||||
completion derives candidates from the complete inventory, so a name is offered
|
||||
only when it identifies one address in that inventory. Completion returns all
|
||||
matching values; it does not expose paging controls.
|
||||
|
||||
## Lifecycle and safety
|
||||
|
||||
Completion has no cache in REA. Opening or switching a target changes document
|
||||
and procedure suggestions on the next request. Closing the binary clears its
|
||||
Evidence ledger and residual-unknown registry, so identifiers from the closed
|
||||
session are no longer suggested. Provider errors, unsupported operations, and
|
||||
malformed provider output produce an empty completion list rather than an
|
||||
unverified identifier.
|
||||
|
||||
Suggestions are starting points, not tool calls. A tool acts on the target,
|
||||
operation, and lifecycle fields in its own request; selecting a suggestion does
|
||||
not execute it or broaden those fields.
|
||||
Reference in New Issue
Block a user