<p align="center"> <img src=".github/assets/banner.png" alt="Harness for REA — an orchestrator plans, a sandboxed specialist takes the target apart" width="100%"> </p> <p align="center"> <a href="https://github.com/protonspy/harness-for-rea/releases"><img src="https://img.shields.io/github/v/release/protonspy/harness-for-rea?style=flat-square&color=818cf8" alt="Latest release"></a> <a href="https://www.npmjs.com/package/harness-for-rea"><img src="https://img.shields.io/npm/v/harness-for-rea?style=flat-square&color=38bdf8" alt="npm"></a> <a href="https://github.com/protonspy/harness-for-rea/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/protonspy/harness-for-rea/ci.yml?branch=main&style=flat-square&label=CI" alt="CI"></a> <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS-475569?style=flat-square" alt="Windows and macOS"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-f472b6?style=flat-square" alt="MIT license"></a> </p> <p align="center"> <a href="#how-a-task-runs">How a task runs</a> · <a href="#isolation">Isolation</a> · <a href="#mcp-integrations">MCP integrations</a> · <a href="#install">Install</a> · <a href="#using-it">Using it</a> · <a href="#development">Development</a> </p>

Harness for REA

A desktop app and a terminal UI for deep analysis of software you own or are authorized to study: understanding a legacy system, debugging, reverse engineering a binary or an app, and porting or reimplementing what it does.

You describe what you want in a chat. Two agents do the work:

| Agent | Runs on | Does | | -------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | The orchestrator | a model from OpenRouter, DeepSeek or any OpenAI-compatible provider | the agent you talk to: plans the task, prepares each step, writes and runs its own code (a decoder, a reimplementation, a probe), answers you | | The specialist | Claude Opus running the Claude Code CLI on your own Claude plan, in Docker | the deep analysis, in a container holding only the files a step needs, with REA built in and a root shell |

REA is a reverse engineering MCP server for native binaries, Android, .NET, Electron and JavaScript targets. The orchestrator does not analyse the target itself.

The split keeps the expensive, careful work with the specialist and the cheap planning and coding with the orchestrator, and keeps the target away from your machine: the specialist only ever sees copies of the files it was handed.

How a task runs

flowchart LR
    you(["You"]) <-->|"chat, questions,<br/>patches to approve"| orch["Orchestrator<br/>your provider's model"]
    orch -.-> log[("Event log<br/>SQLite + JSONL")]

    subgraph specc["Specialist container"]
        claude["Specialist<br/>Claude Code"] --- rea["REA"]
        claude --- work["Copies of the<br/>listed files"]
    end

    subgraph taskc["Task container"]
        tools["Orchestrator's tools<br/>workspace read-only<br/>scratch writable"]
    end

    orch -->|"context package"| claude
    claude -.->|"report + evidence<br/>+ contract"| orch
    orch -->|"writes and runs its code,<br/>replays test vectors"| tools

sequenceDiagram
    autonumber
    actor You
    participant O as Orchestrator
    participant H as Harness
    participant S as Specialist
    participant T as Task container

    You->>O: Request
    O->>O: Break it into steps
    O->>H: Delegate a step with a context package
    H->>S: Fresh container, files copied into /work
    S->>S: Analyse with REA and a shell
    S-->>H: Report citing evidence, ending with a contract
    H->>H: Validate the contract
    opt The contract fails
        H->>S: Send it back for a correction, up to twice
        S-->>H: Corrected report
    end
    H-->>O: Report and contract
    O->>T: Write its code and run replay_vectors
    T-->>O: Outputs compared byte for byte
    O-->>You: Answer, and a patch to approve
    You->>H: Approve the patch
    H->>H: Apply it to your files

1. You start a task in a project with a request. The orchestrator breaks it into steps.
2. For each analysis, the orchestrator writes a context package: a technical brief (what the artifact is, what is already known), the objective, the files, the questions and the report format. The specialist sees that package and nothing else — not your request, not the chat.
3. The specialist runs in a fresh container (or a sandbox the orchestrator prepared with tools and files), with the files copied into /work. It answers with a report whose claims cite evidence: a line range, an address in a binary, or an REA evidence id.
4. Every report ends with a contract, a JSON block the app validates: the functions mapped with their inputs, outputs and side effects; the constants found, each with a source or marked estimated; the questions left open; and test vectors — inputs given to the target and the output it produced, observed by running it. A report whose contract fails is sent back to the specialist for a correction, up to twice.
5. The orchestrator writes its code from the report and checks it with replay_vectors, which runs the vectors against its reimplementation and compares outputs byte for byte.
6. Changes to your files come back as patches. Nothing outside the task's containers changes until a patch is applied.

Questions and refusals

flowchart TD
    q["The specialist asks a question"] --> om{"Can the orchestrator's model<br/>answer it from the context package?"}
    om -- "yes" --> back["The answer goes back to the specialist"]
    om -- "no: only you know" --> user["You are asked"]
    r["The specialist declines a step<br/>under its usage policy"] --> wait["The task waits for you"]
    wait --> stop["Stop the task"]
    wait --> skip["Skip the step"]
    wait --> other["Ask for a different<br/>technical approach"]

Questions. Either agent can ask you a question mid-run. The specialist's questions go first to the orchestrator's model, which answers from the context package when it can; questions about authorization, ownership or purpose always come to you.

Refusals. If the specialist declines a step under its usage policy, the task waits for you to stop it, skip the step, or ask for a different technical approach. The request is never reworded to get past the refusal.

Projects. A project is one target — a file (an APK, an executable, an archive) or a folder — with a goal and the model its tasks use. Tasks in a project share its sandboxes and everything earlier tasks found, and the questions one analysis left open are handed to the next.

Isolation

flowchart TB
    subgraph host["Your machine"]
        files["Your files"]
        keys["OS keychain<br/>one entry per provider"]
        data[("App data folder<br/>event log + raw output")]
        app["Harness for REA"]

        subgraph docker["Docker"]
            taskc["Task container<br/>your source read-only,<br/>scratch area, internet"]
            specc["Specialist container<br/>copies of your files,<br/>as root, internet"]
            vol[("Volume<br/>Claude sign-in token")]
        end
    end

    files -- "mounted read-only" --> taskc
    files -- "copied" --> specc
    vol -- "mounted" --> specc
    keys --> app
    app --> data
    app -. "patch, on your approval" .-> files

• The specialist runs in a container per delegation, or in a sandbox the orchestrator created for the project; of your files it sees only the copies made for it, as root, with internet access. Its Claude Code runs with no user or project settings, so a CLAUDE.md or settings left in /work by an earlier step are never loaded.
• The orchestrator's tools run in a task container, as root with internet access, where your source is mounted read-only; they write to your machine only through its scratch area.
• The specialist signs in with your Claude plan once; the token lives in a Docker volume mounted into the specialist's container.

[!WARNING] The container keeps a target away from your machine, not from your Claude account. The specialist has a root shell and internet access beside the sign-in token, so a hostile target that steers it can read the token and send it out. Do not analyse an untrusted sample with an account you cannot afford to expose.

• Provider API keys are kept in the OS keychain, in one entry per provider both apps read, and redacted from everything the app records or sends to a model.
• Everything the agents do is recorded per task: an event log in SQLite and each agent's raw output as JSONL, in the app's data folder.

MCP integrations

Engines that run on your machine reach the agents only through the app. Cheat Engine: the agents read the live memory of a Windows process you approved, through a bridge the app ships and that answers read-only commands only. IDA Pro: the agents read the database you have open in IDA — decompilation, disassembly, cross-references, types and bytes — through a plugin the app ships, derived from ida-pro-mcp, with its read-only tools only.

flowchart LR
    subgraph specc["Specialist container"]
        cc["Claude Code"] --> mcp["MCP server<br/>the tools you allowed"]
    end
    orch["Orchestrator"]

    subgraph host["Your machine"]
        app{"Harness for REA<br/>checks the agent,<br/>the tool and the target"}
        ce["Cheat Engine<br/>+ read-only bridge"]
        proc["The approved process"]
        ida["IDA Pro<br/>+ read-only plugin"]
        idb["The approved database"]
    end

    mcp -- "calls over the run directory" --> app
    orch -- "its allowed tools" --> app
    app --> ce
    ce -- "reads memory" --> proc
    app --> ida
    ida -- "reads" --> idb

• Settings → MCP integrations lists the integrations the app carries, each off by default. Turning one on runs its checks — for Cheat Engine: the executable exists, the bridge script is installed in its autorun folder, and the bridge answers with the version the app carries; for IDA Pro: the plugin is installed in IDA's user plugins folder and answers with the version the app carries — and a failed check says what fixes it.
• Each integration has its own page, with one toggle per tool for the orchestrator and one for the specialist. The specialist starts with every tool; the orchestrator starts with status (and Cheat Engine's get_process_list) only, and turning on a tool that reads a target warns that what it returns goes to the orchestrator's provider.
• Every target is approved by you, even in an automatic task: a process by its name, PID and executable path; a database by its input file's name, its path and its SHA-256. A delegation with an approved target cannot reach any other. What the tools read from it — secrets included — goes to the agents' models and their reports, and the specialist's container has full internet access.
• The bridge only reads: the process list, modules, memory regions, memory, value and byte scans, pointer chains, disassembly, symbols and structures. Writing memory, injecting code and debugging are not there to call. Its pipe takes any local client, so while Cheat Engine runs with the bridge, the app's checks bind the agents but not other programs on your machine.
• **The IDA plugin only read