How to read this manual

This manual explains rea, the rea-agents package at version 6.7.0, with the Ghidra 12.1.4 provider. It follows one question from a file you compiled to an Evidence record you can check. The question is what a function does, and how the tool knows.

Who this manual is for

You write C, Python, or JavaScript, and you use a coding agent such as Claude, Cursor, Codex, OpenClaw, Hermes, or any agent that reads SKILL.md. You have never read machine code with a decompiler, and you want to check what an agent tells you about a compiled program.

After the last part, you can:

• Read the file header, sections, symbols, and relocations of a compiled program, and map an address to a file offset.
• Run rea with the Ghidra provider on a program you built, and read its Evidence record: confidence, authority, limitations, and unknowns.
• Find a function, read its assembly and pseudocode, follow its references, and say where the decompiler output is incomplete.
• Prove a rebuilt function equal to the original by running both over an input grid and by comparing bytes after masking relocations.
• Drive rea from an agent over MCP, and keep an evidence ledger that separates what was observed from what was inferred.

Five lessons go deeper than rea does. The ELF lesson builds a file reader. The disassembly lesson builds a decoder and a control-flow graph. The lifting lesson builds a lifter. The evidence lesson builds a ledger, and the proof lesson proves a rebuild equal. This manual stays with rea and Ghidra.

How it was made

The manual pins rea-agents 6.7.0, published 2026-10-18, at the tag rea-agents-6.7.0, which is commit 27dc42d10249f0410904a75c0997842eb03b931c. It pins Ghidra 12.1.4 PUBLIC, built 2026-Sep-21, and OpenJDK 21.0.12.1. The facts were verified on 2026-10-18. Release 6.7.0 also holds the changes of 6.6.0, which was tagged but not published to npm. The WebAssembly provider, the Go provider, the raw-binary format, and DISCLAIMER.md came in 6.5.0. This manual describes 6.7.0 only, and every capture was recorded again for it.

Facts come from seven sources, ranked by authority. When two of them disagree, the higher one wins and the text says so.

Quotes from the rea README, DISCLAIMER.md, and documentation were checked against the pages at tag rea-agents-6.7.0. Quotes from statutes, specifications, and papers come from the official texts. No source file is copied into this repository.

The capture kit

The capture kit drives the real rea command line and its MCP server with the Ghidra provider. It writes what they return to its output folder, and it uses the Python standard library only. python3 capture/run.py records everything. python3 capture/run.py --check records again into a temporary directory and compares with the recorded set after masking the values that change on every run.

The subject needs Ghidra, a JDK, and Node, so the kit cannot run in the repository CI. Where rea 6.7.0, Ghidra 12.1.4, or JDK 21 is absent, --check prints skipped with the reason and exits 0. Every captured file was recorded on one machine:

The kit records every one-shot command in 00-commands.txt, each with its exit status and time. It records one MCP session of 25 exchanges in 10-mcp-*.json, and two Evidence bundles. A full run takes about 125 s, and each one-shot command that needs Ghidra takes 7 to 9 s. Two runs on the recording host produced identical records (the capture). Every fixture is a program written for this manual, and 00-fixtures.txt lists their hashes.

Conventions

rea names the 6.7.0 command line in every command. The kit started it from the npx cache as node .../node_modules/rea-agents/scripts/rea.mjs, and rea mcp names the MCP server of the same package.

$CAPTURE stands for the capture directory, $OUT for capture/out/, $WORK for the kit's work directory, and $HOME for the home directory. Values that change on every run appear as tokens such as <hash> and <ts>. Addresses are lowercase 0x hexadecimal, as rea prints them. _percent_change with a leading _ is the Mach-O symbol, and percent_change is the C name and the ELF symbol.

Each section records its sources in the manual source, where the audit checks every quote and number. The sections do not show them. The sources reference lists them. A listing copies lines from a capture file unchanged, and a … marks a cut that the note explains.

Figures animate on the web, where a Replay button runs the steps again, and print and reduced motion show the final frame.

A first run

You need rea 6.7.0, Ghidra 12.1.4, and a JDK 21 on PATH or in JAVA_HOME. After the install, nothing in this run uses the network. Export the two paths, then ask the doctor:

export GHIDRA_INSTALL_DIR=/opt/homebrew/Cellar/ghidra/12.1.4/libexec
export JAVA_HOME=/opt/homebrew/opt/openjdk@21
rea doctor --provider ghidra --format json

On the capture Mac the report starts like this:

{
  "healthy": true,
  "environment_healthy": false,
  "scope": {
    "mode": "explicit",
    "clients": [],
    "providers": [
      "ghidra"
    ],
    "skill": false,
    "target": null
  },
…

Then build the fixture. Copy capture/fixtures/ledger.c and ledger-main.c into a scratch directory and compile them:

clang -O1 -o ledger-arm64-O1 ledger.c ledger-main.c
rea function ledger-arm64-O1 _percent_change --provider ghidra --format json

Another clang gives other bytes, and with them another SHA-256 and another evidence_id, so your record will differ from the capture in those fields. The capture recorded its run like this:

$ rea function fixtures/ledger-arm64-O1 _percent_change --provider ghidra --format json
[exit 0] (… s) -> 06-function-percent-change.json

Open capture/out/06-function-percent-change.json next to your own output. Section 1.2 reads it field by field.

How the parts are ordered

Part 1 puts rea on one page. Part 2 covers the right to analyze and the install. Parts 3 to 5 take one investigation apart: the file itself, the Ghidra provider, and the Evidence record. Part 6 covers JavaScript and WebAssembly. Part 7 proves a rebuild equal outside rea. Part 8 drives rea from an agent, and the Reference holds the lookup tables:

Colour in figures

Each hue keeps one meaning in every figure:

Figure 0.1 teaches the eight arrow styles with exchanges from the recorded MCP session.

The model call in row 9 belongs to the agent, which Part 8 draws with its own lifeline.