With your agent
+Connect your coding agent
Run setup to connect REA to your coding agent. Client choices include Claude Code, Codex, Cursor, Gemini CLI, Windsurf and other @@ -118,19 +118,14 @@ involved, with the source locations for your findings.
-- Replace the path with your local target. Read the findings, then - ask a narrower follow-up about a function or connection you want - to understand. -
+Replace the path with your local target.
From the terminal
+Use the CLI
- You can start with a JavaScript or Electron application folder or - ASAR archive. This path uses Node.js and npm and reads the app - without running it. + Analyze a JavaScript or Electron application folder or ASAR + archive without running the app:
"D:/apps/example" works here.
- The result includes the application's identity, recovered module - relationships and evidence locations. It also records - relationships that remain unresolved. Use those findings to choose - where to investigate next. + The result identifies the app, shows connections between modules + and gives their source locations. Connections REA cannot resolve + are marked in the result.
If you'd like a permanent
- REA connects your agent to a local analysis provider. Choose the
- tool you already use, configure its connection, then ask about
- your executable or library.
+ Native binaries need a local analysis tool. Choose and configure
+ one below, then give REA your executable or library.
- Use an existing Ghidra 12.1.x installation and a 64-bit JDK
- 21 or newer on Linux x64 or macOS x64/arm64. Set the paths
- before running setup:
-
+ Use an existing Ghidra 12.1.x installation and a 64-bit
+ JDK 21 or newer on Linux x64 or macOS x64/arm64. Set the
+ paths before running setup:
+
- Replace both paths with your existing installations. Setup
- checks them and records valid settings for your selected
- client. On macOS, use a Ghidra package with the native
- decompiler matching your host architecture.
-
- Connect Hopper on macOS or Linux. Run the setup command
- above; it detects an existing installation or offers an
- installation plan for your approval.
-
- On macOS, complete Hopper's first-run choice of demo mode or
- license activation before an unattended analysis.
-
- The verified IDA setups use Windows, with an existing MCP
- registration for an attached GUI or a headless database.
- Linux and macOS headless analysis remains unverified.
-
- Keep the upstream server's working
+ Replace both paths with your existing installations.
+ Setup checks them and records valid settings for your
+ selected client. On macOS, use a Ghidra package with the
+ native decompiler matching your host architecture.
+
+ Connect Hopper on macOS or Linux. Run the setup command
+ above; it detects an existing installation or offers an
+ installation plan for your approval.
+
+ On macOS, complete Hopper's first-run choice of demo mode
+ or license activation before an unattended analysis.
+
+ The verified IDA setups use Windows, with an existing MCP
+ registration for an attached GUI or a headless database.
+ Linux and macOS headless analysis remains unverified.
+
+ Keep the upstream server's working
- The attached profile uses upstream legacy 1.4.0 tools with
- the original binary already open in IDA. The headless
- profile uses the upstream database-supervisor API and a
- registration with
- Give REA the original executable path, with
-
+ The attached profile uses upstream legacy 1.4.0 tools
+ with the original binary already open in IDA. The
+ headless profile uses the upstream database-supervisor
+ API and a registration with
+
+ Give REA the original executable path, with
+
For an existing Ghidra setup, inspect a function with:
Replace
+ Each CLI command imports and analyzes the binary, then closes
+ its session. Your agent's MCP queries reuse the imported binary
+ while that session is open.
+
Follow a native analysis example
to see how the function result leads to a recovered calculation.
@@ -327,8 +332,8 @@ npx rea-agents@latest setup
- Restart or reconnect the client after setup. To check its
- registration, use a client-scoped report; for Codex:
+ Restart or reconnect the client after setup. Check its REA
+ connection with
- We want to see which request the click makes, then use the script
- to understand how the response becomes a file.
- One action, captured while it happens From the click to the CSV download
- Start a Chrome-family browser with a dedicated profile and a local
- debugging port. On Linux, for this site's local preview:
+ Open the hosted Notes example with a separate browser profile and
+ a local debugging port. On Linux:
Use your installed browser's executable path on macOS or Windows.
- The page URL should point to your local preview or
- the hosted Notes example.
+ You can replace the page URL with another page you want to
+ inspect.
REA connects to this existing browser. You keep control of the
@@ -225,7 +220,7 @@
+ The hosted example's request path includes the site's
+
- Follow an example from the first prompt to the evidence. Then use the
- same approach with your own app.
+ Analyze a native function, an Electron export or a browser request.
+ Each guide includes a prompt, code and results.
For a larger packaged app, follow
Notion's clipboard bridge.
@@ -96,12 +98,8 @@
First investigation
- Each guide starts with a plain-language question and follows a
- concrete example. If you haven't connected REA yet, setup takes
- you through the client and provider choices.
- Connect your coding agent or use REA from the terminal.
- Use a CSV export to see how REA connects JavaScript files, exposed
- APIs and Electron process boundaries.
+ Follow a button click from the page API, through Electron IPC, to the
+ CSV file writer.
A feature across two processes
+ The CSV export across Electron processes
+
Connect your agent to REA
and give it the app directory or ASAR file:
@@ -140,7 +142,7 @@
- Replace the path with the folder you unzipped. Look for
-
For your own app, use the same command with its directory or ASAR
@@ -278,7 +280,7 @@
Follow
- Use DX-Ball’s sound panning to see how an agent moves from a binary to
- an explanation and a checked C function.
+ Inspect the original instructions, identify the input and constants,
+ then check the recovered C.
In DX-Ball, a brick hit supplies a horizontal screen position. The
- sound code turns it into a left/right panning value. We want to
- recover that calculation from the executable.
+ sound code turns it into a left/right panning value.
The starting function,
- You can start with a feature name. Your agent uses REA to locate
- relevant functions, then follows the evidence with more focused
- queries.
-
@@ -112,12 +112,6 @@
game continues with ball and paddle physics, power-up handling and
Windows integration.
- The analysis starts from the DX-Ball 1.07 executable. REA returns
- function code, instructions, callers and state references. These
- findings guide the C implementation; execution of the original x86
- functions and compiler replay check the result.
-
- REA exposes these operations through CLI and MCP, with target
- identity and Evidence IDs in the results. The agent can follow up
- on a caller or data address directly, then use the findings to
- write maintained C.
-
@@ -523,10 +511,8 @@
- The input, caller context and constant values returned through REA
- guided the maintained C implementation. The project then checked
- it against the original x86 function and the pinned compiler. For
- this function, both checks pass.
+ The recovered function passes two checks: its return values match
+ the original, and its compiled bytes match the executable.
- Start with a question about a real application. See what REA finds,
- follow the code, and understand how the pieces fit together.
+ Game reconstruction and Electron analysis, with examples from DX-Ball,
+ Notion and TH04.
Native · Reconstruction
Recover a sound-pan calculation from a 1996 Windows game. REA's
instructions, caller references and numeric constants lead to a
@@ -61,7 +61,7 @@
Electron · Feature tracing
Trace a page-facing API through Notion's packaged JavaScript.
Follow its IPC wrappers to the system clipboard, then see how a
@@ -79,7 +79,7 @@
PC-98 DOS · Reconstruction
Inspect the original 16-bit angle helper with REA. Match its
multiply, divide and coordinate operations to readable C++, then
@@ -96,12 +96,12 @@
The guides walk through a native calculation, an Electron export and a
browser request. Each starts with a prompt and a concrete target.
Case study · Electron
- A familiar action leads through several files. Follow Notion's
- clipboard API from the page, through Electron, to the system
- clipboard.
+ Trace a clipboard call from Notion's page API, through the preload and
+ main process, to Electron's clipboard writer.
- The cached web editor adds a small detail to programmatic copies.
- It sends text and HTML through
- One copy, two representations HTML links to saved block data
- On paste, the reader looks for the marker and checks it against
- the saved copy. A matching ID reconnects the text to its richer
- representation. This explains why the HTML carries more than
- visible content.
+ On paste, Notion looks for the HTML ID and checks it against the
+ saved copy. Matching IDs restore the block data.
- Web assets cached on July 13, 2026. The desktop-package bridge
- above and this web-side format are separate pieces of the
- investigation.
-
- The same investigation also recovered Notion's Markdown
- processing. A small table makes the internal format easy to see:
- its rows and cells become data that the block renderer can use.
-
- A table through Notion's Markdown parser
-
- Finding that transformation required separating the ordinary
- paste/import path from the structured Markdown and AI/chat
- parsers. Each has its own entry point and intermediate format.
+ Clipboard format recorded from web assets cached on July 13, 2026.
- Start with one feature and follow the code that crosses a process
- boundary. A named API, a literal channel and its receiver are
- useful places to begin.
-
+ Notion parses Markdown into block data. This example shows how a
+ table becomes header and data rows.
+
+ A table through Notion's Markdown parser
+
@@ -436,6 +415,12 @@ mimeTypes:
matching receiver are connected by reading their wrapper
implementations in the package.
+ The Markdown example uses parser module
- The project already has a reviewed boundary for
-
- The TH04 project checks this compiler-sensitive C++ with its
- pinned Turbo C++ 4.0J toolchain. Recorded checks cover the
- complete bullet-add source owner containing this helper.
+ The TH04 project's recorded checks compile the bullet-generation
+ code, including this helper, with its pinned Turbo C++ 4.0J
+ toolchain.
- The rebuilt code matches the complete original target extent.
- The comparison also checks the MAP contribution and
- overlapping relocation.
+ The compiled bullet-generation code matches a 2,139-byte
+ section of the original executable.
- Two isolated compiler runs produce the same matching result.
- The recorded input hashes match the maintained bullet source
- shown here.
+ Two separate builds produce the same matching bytes. The
+ recorded input hashes match the maintained source shown here.
+ Compiler checks cover the complete bullet-add code section,
+ including this helper. They also compare its MAP contribution
+ and overlapping relocation.
+
REA verified the static DOS load image at load segment
rea command in your shell:
@@ -183,116 +177,121 @@
Working with native binaries
+ Set up native analysis
Ghidra
- Connect your Ghidra installation
- export GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.1.4_PUBLIC
+ Choose a tool: Ghidra, Hopper or IDA
+ Ghidra
+ Connect your Ghidra installation
+
- export GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.1.4_PUBLIC
export JAVA_HOME=/absolute/path/to/jdk-21
npx -y rea-agents@latest doctor --provider ghidra --json
npx rea-agents@latest setupHopper
- IDA
- Connect an existing IDA MCP registration
- command,
- args and optional env in a JSON
- file. An existing mcpServers object with an
- ida-pro-mcp entry is also accepted. Point REA
- at that file before setup:
- $env:REA_IDA_MCP_CONFIG = "C:/analysis/ida-mcp.json"
+ Hopper
+ IDA
+
+ Connect an existing IDA MCP registration
+
+ command,
+ args and optional env in a
+ JSON file. An existing mcpServers object
+ with an ida-pro-mcp entry is also accepted.
+ Point REA at that file before setup:
+
- $env:REA_IDA_MCP_CONFIG = "C:/analysis/ida-mcp.json"
$env:REA_ANALYSIS_PROVIDER = "ida"
npx -y rea-agents@latest doctor --provider ida --json
npx rea-agents@latest setup"mode": "headless"; real
- verification covers an IDA 9.3 Windows x64 supervisor.
- Doctor checks the registration without starting IDA.
- --provider ida in a CLI query. For an agent,
- include REA_IDA_MCP_CONFIG in the REA
- registration's environment and select IDA when opening the
- binary.
- "mode": "headless"; real verification
+ covers an IDA 9.3 Windows x64 supervisor. Doctor checks
+ the registration without starting IDA.
+ --provider ida in a CLI query. For an
+ agent, include REA_IDA_MCP_CONFIG in the
+ REA registration's environment and select IDA when
+ opening the binary.
+ rea function /absolute/path/to/program main \
+ npx -y rea-agents@latest function /absolute/path/to/program main \
--provider ghidra --jsonmain with the function name or address you
- want to inspect. Each CLI invocation imports and analyzes the
- target in its own session. Your agent's MCP queries reuse the
- imported binary while that session is open.
+ want to inspect.
How native analysis sessions work
+ Getting help
If your agent doesn't see REA
doctor; for Codex:
notes.json, formats the two notes as CSV, and starts
a download.
-
Open an observable browser
+ Open Chrome with remote debugging
+ https://morluto.github.io/rea/examples/notes-web/
google-chrome \
--remote-debugging-port=9222 \
--user-data-dir=/tmp/rea-notes-browser \
- http://127.0.0.1:4173/examples/notes-web/Read the result, then follow the code
+ Read the request and export script
/rea/ prefix.
+ Start with
+
an example.REA guides.
Connect your agent, then ask.
- Set up REA
+ Follow a feature
+
across the app.Trace an Electron
CSV export.
Give your agent one feature
+ Ask about the CSV export
Connect the pieces
+ Trace the export code
The page calls a small API
normalized_result.summary.ipc and the source
- locations in normalized_result.graph. The example has
- one channel and one paired invocation.
+ Replace the path with the folder you unzipped. You should find one
+ IPC channel and one matching handler in
+ normalized_result.summary.ipc. Source locations are
+ in normalized_result.graph.
Ask the next question
+ Inspect the CSV writer
notes:export to its handler. Which inputs
diff --git a/website/public/guides/native/index.html b/website/public/guides/native/index.html
index 48237b101c..bbb1ece47b 100644
--- a/website/public/guides/native/index.html
+++ b/website/public/guides/native/index.html
@@ -34,10 +34,10 @@
Recover a calculation.
+
Follow the evidence.Recover DX-Ball's
sound-pan calculation.
A position becomes a sound
+ Calculate left/right sound panning
0x00406400, has a short
@@ -138,14 +137,9 @@
Example prompt. Give your agent the path to your local DX-Ball
1.07 executable.
Follow what REA returns
+ Read the REA results
Read the input
From REA's findings to C
Checking the recovered function
Follow the
+
investigation.REA case studies.
Rebuilding DX-Ball
+ DX-Ball's sound-pan calculation
Following a copy through Notion
+ How Notion copies text and HTML
Understanding TH04's bullet patterns
+ How TH04 aims a ring of bullets
Try a smaller example first.
+ Step-by-step guides
Following a copy
+
through Notion.How Notion copies
text and HTML.
How does a copied block keep its structure?
electronApi.clipboard.write, while keeping Notion's
- private block data in a local virtual clipboard. An ID in the HTML
- connects the two.
+ Notion's web editor sends text and HTML through
+ electronApi.clipboard.write. It keeps the block data
+ locally and puts an ID in the copied HTML to connect them.
id: <copy-id>
mimeTypes:
@@ -327,76 +323,59 @@ mimeTypes:
>
From Markdown to structured blocks
-
- | A | B |
-| - | - |
-| 1 | 2 |
- table · headerRow: true
- table_row
- cells: ["A"], ["B"]
- table_row
- cells: ["1"], ["2"]422457. Both page and chat filters preserve this
- table. The tree shows the recorded rows and cell text.
- Try another question
- More examples and sources
+ Another example: Markdown tables
+
+ | A | B |
+| - | - |
+| 1 | 2 |
+ table · headerRow: true
+ table_row
+ cells: ["A"], ["B"]
+ table_row
+ cells: ["1"], ["2"]Another path: the offline SQLite connection
422457.
+ Saved module tests show that both page and chat filters preserve
+ this table. The paste/import, structured Markdown and AI/chat
+ parsers have separate entry points and intermediate formats.
+
What REA returns
bullet_velocity_and_angle_set(). Inspecting that
- original function through REA returns its instructions, pseudocode
- and references together. Here are three parts of the result that
- explain the pattern.
+ We inspect bullet_velocity_and_angle_set(), the
+ function that sets each bullet's velocity and angle. REA returns
+ its instructions, pseudocode and references. Three parts of that
+ result explain the pattern.
Checking the maintained source
2,139 matching bytes
Two clean builds
0x1000. Its addresses describe that analysis image.
diff --git a/website/style-guide.md b/website/style-guide.md
new file mode 100644
index 0000000000..f7154a56b7
--- /dev/null
+++ b/website/style-guide.md
@@ -0,0 +1,199 @@
+# REA website writing and design guide
+
+> A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation.
+>
+> — N0zoM1z0
+
+For REA, that means a concrete question, a figure that explains the process,
+evidence the reader can inspect, and a useful next step. A clean, refined
+appearance comes from precise wording, readable figures, consistent typography
+and deliberate spacing.
+
+Use this guide for new pages and revisions. Start from an existing page and
+reuse `public/assets/styles.css` and `public/assets/main.js`. Local preview and
+publication commands are in [README.md](README.md).
+
+## What a reader should understand
+
+A reader scanning for five seconds should see the subject and the result. After
+ten seconds, the main figure should explain the sequence. After fifteen seconds,
+the prompt or first example should show how to start.
+
+These are reading goals, not a requirement to fit every investigation above the
+fold. Keep the main path short and let readers open the supporting details.
+
+## Write the task directly
+
+Name the software, behavior or action in headings. Give the opening paragraph
+one job: explain what the page covers. Use concrete verbs such as install, trace,
+read, compare and calculate.
+
+| General wording | More useful wording |
+| ------------------------------------------------ | ------------------------------------------------------------------ |
+| Start with a question. | Set up REA. |
+| Follow a feature across the app. | Trace an Electron CSV export. |
+| Following a copy through Notion. | How Notion copies text and HTML. |
+| A position becomes a sound. | Calculate left/right sound panning. |
+| Follow the investigation. | REA case studies. |
+| Reviewed boundary / source owner / target extent | The helper / its surrounding code / the code section being checked |
+
+Questions also work when they name a behavior: “Where is the CSV created?” and
+“How does a copied block keep its structure?” give the reader something specific
+to look for.
+
+Explain necessary terms where they first matter. An IPC channel can be described
+as a named message between Electron processes. Keep exact API names, addresses
+and JSON paths in the code or result they identify.
+
+Give each paragraph new information. A diagram can summarize a sequence, while
+the code below explains individual steps. Repeating that REA supplies
+instructions, callers and constants in several surrounding paragraphs adds no
+new step. Explain that role once, then show the results.
+
+Use captions for useful context: which values are illustrative, where an excerpt
+comes from, or what a check covers. Scope a claim positively and precisely:
+“The compiled function matches 63 bytes” is more useful than a broad claim
+followed by several qualifications.
+
+## Build a page around one question
+
+### Guides
+
+1. Name the task and introduce a small example.
+2. Show a short flow of the relevant files, calls or observations.
+3. Provide a copyable agent prompt and its prerequisites.
+4. Explain the important code or returned fields.
+5. Let the reader try the example, with a command or one ZIP download.
+6. State the expected result and where to find it.
+7. Offer a specific follow-up question or another relevant guide.
+
+A command should work after the steps immediately before it. Use `npx` for a
+first CLI query when global installation is optional. Browser examples should
+open the hosted fixture by default; a local URL needs a server-start step. Keep
+target paths, debugging endpoints and other required inputs explicit.
+
+### Case studies
+
+1. Introduce the project and the particular feature being examined.
+2. Show a figure that explains the investigation or behavior.
+3. Give a short example prompt.
+4. Pair important REA queries with selected returned evidence.
+5. Connect that evidence to readable source or an explanation.
+6. Explain how the result was checked.
+7. Link the reconstruction repository and supporting sources.
+
+Show REA's useful contribution through a concrete finding: a missing stack
+argument, a caller, bytes behind a constant, or source ranges in a packaged
+bundle. Explain what the agent does with that finding. Credit source
+interpretation, reconstruction and external checks to the work that performed
+them.
+
+Keep a second investigation optional. Notion's clipboard path is the main
+story; Markdown tables and SQLite are additional examples. Native `