ReAgent

ReAgent is an open-source AI reverse-engineering agent that uses Ghidra and LLMs—including Claude, Codex, and OpenAI-compatible models—to reconstruct and validate C/C++ functions from compiled binaries. It combines independent reverser/checker models, agentic evidence gathering, candidate build and test gates, structural verification, and parity analysis in one autonomous workflow.

Original pre-0.2 demo: YouTube

Get started with your AI

Give your AI this repo and tell it what you want to do. It can check your setup, install the tools it needs, and walk you through anything that needs your help. Use an AI coding agent that can access files and run commands on your computer.

Copy this into your agent:

Help me set up https://github.com/Dryxio/reagent. Read the README, check my installed tools and AI provider setup, and help me install and configure what's missing. Ask which program or project to work on. Start with one small function. Run the setup check (re-agent doctor), explain which AI provider will be used and any API costs, and set a small model-call limit. Then try to recreate that function in C/C++ and show me the result, what passed validation, and what still needs checking.

You'll need a program to analyze and a supported AI provider. Your agent can help connect Ghidra and use an existing authenticated Claude or Codex CLI, or an API setup.

Setup agents: follow the setup workflow. Detect the host OS and installed toolchain, generate portable validation commands, and migrate incompatible existing commands before starting reversal. The user should not need an OS-specific prompt or edit command syntax manually.

What it does

re-agent reverse --class CTrain
    │
    ├── Configuration (YAML + supported environment overrides + CLI flags)
    ├── Function selection (dependency-order | easiest-first | high-impact)
    ├── Source and binary context
    │   ├── decompile, xrefs, structs, enums, vtables, globals, and strings
    │   └── normalized high P-code, CFG, assembly, and nearby project source
    ├── Reverser → checker → fix loop (bounded rounds and investigations)
    ├── Conservative structural verifier
    ├── Candidate overlay
    │   └── configured build, test, and runtime gates
    ├── Candidate parity gate (GREEN | YELLOW | RED)
    └── Reports, per-call logs, round checkpoints, session history, and knowledge graph

The tool generates candidate C/C++ implementations; it does not patch the original source tree automatically. A successful reversal can require four independent conditions:

1. the LLM checker returns PASS;
2. the objective verifier finds no strong structural mismatch;
3. candidate validation satisfies the configured acceptance policy;
4. parity is not blocked by the configured RED/YELLOW policy.

This is conservative verification, not a proof of semantic equivalence.

New in 0.4.0

Build, test, and runtime validation now support argument arrays that execute directly on Windows and POSIX. On native Windows, convert shell strings to arrays; legacy strings still require /bin/sh. re-agent doctor reports a missing shell.

• re-agent plan builds bounded function manifests without model calls.
• re-agent reverse --manifest reconstructs selected functions across classes, with dependency ordering and cumulative validation in an isolated project copy.
• re-agent evidence --manifest exports stored evidence into linked JSON packets and TSV indexes.
• re-agent status --manifest reports coverage, stale results, and individual validation checks.
• Evidence gaps remain explicit, and manifests stay readable after backend errors with empty messages.
• Clang indexing handles CRLF offsets; Codex CLI requests use UTF-8 stdin for large prompts.

See migration and configuration and the changelog.

Manual setup

Prefer to install it yourself? Expand the instructions below.

Requirements

• Python 3.10+
• Git, for the current source installation
• Ghidra plus a configured Ghidra Bridge
• At least one LLM setup:
  • Claude API: ANTHROPIC_API_KEY
  • OpenAI-compatible API: OPENAI_API_KEY
  • Claude CLI: an authenticated local claude command
  • Codex CLI: an authenticated local codex command

Installation

Install the agent and its Ghidra query bridge from PyPI:

python3 -m pip install --upgrade "auto-re-agent[ghidra-bridge]>=0.4.0"

For headless Ghidra exports, install the bridge with its PyGhidra extra:

python3 -m pip install --upgrade "auto-re-agent[headless]>=0.4.0"

To install the latest development versions directly from GitHub instead:

python3 -m pip install --upgrade \
  "ghidra-ai-bridge @ git+https://github.com/Dryxio/ghidra-bridge.git@main" \
  "auto-re-agent @ git+https://github.com/Dryxio/reagent.git@main"

Set up Ghidra evidence

Run these commands from the project you want to reverse:

# Create ghidra-bridge.yaml, then edit its Ghidra project/program paths
ghidra-bridge init

# Requires the bridge headless extra and a local Ghidra installation
ghidra-bridge export all

# Optional but recommended when reversed source/hook patterns are available
ghidra-bridge build-map

# Confirm that exports and configuration are visible
ghidra-bridge info

See the bridge documentation for its Ghidra, export, and source-map configuration.

Quick start

Create a configuration in the target project:

# Recommended portable default
re-agent init --profile generic-cpp

# Other available profiles
# re-agent init --profile windows-x64
# re-agent init --profile gta-reversed
# re-agent init --profile openrct2

Running re-agent init without --profile preserves the original GTA-reversed defaults. Prefer an explicit profile for new projects.

Then edit re-agent.yaml. At minimum, select an LLM, point the backend at the installed bridge executable, set the source paths, and configure validation.

llm:
  provider: claude-cli
  model: sonnet

# Optional: use a different provider/model for checking.
agents:
  checker:
    provider: codex
    model: gpt-5.4

backend:
  type: ghidra-bridge
  cli_path: ghidra-bridge

project_profile:
  name: generic-cpp
  language_standard: C++20
  source_root: src
  hooks_csv: null

orchestrator:
  max_review_rounds: 4
  investigation_enabled: true
  max_investigations: 8
  selection_strategy: dependency-order
  max_attempts_per_function: 3

validation:
  enabled: true
  copy_project: true
  project_root: .
  build_commands:
    - [cmake, -S, ., -B, build]
    - [cmake, --build, build]
  test_commands:
    - [ctest, --test-dir, build, --output-on-failure]
  require_build: true
  require_tests: true
  require_verified: true
  # This explicitly attests that the project-owned commands above are
  # meaningful validation gates. Leave false for untrusted commands.
  trust_configured_commands: true
  keep_project_copy: false
  parity_fail_on_red: true
  parity_fail_on_yellow: false

Validation is deliberately strict: with the generated defaults, no configured commands produce UNKNOWN, and require_verified: true rejects that result. For exploration without build validation, explicitly set validation.enabled: false; such results are not build-verified.

Start with one function before launching a class run:

re-agent reverse --address 0x401000
re-agent reverse --class CTrain --max-functions 10
re-agent status

LLM providers

Claude API

llm:
  provider: claude
  model: claude-sonnet-4-5-20250929

Set ANTHROPIC_API_KEY or RE_AGENT_LLM_API_KEY.

Claude CLI

Authenticate the local Claude Code CLI first, then configure:

llm:
  provider: claude-cli
  model: sonnet
  cli_path: claude
  effort: high
  max_budget_usd: 1.0

Claude CLI supports real session resume and reports usage/cost metadata. A stale CLI login can still require re-authentication even when its auth-status command reports a session.

OpenAI-compatible APIs

llm:
  provider: openai # or openai-compat
  model: your-model
  base_url: https://your-endpoint.example/v1 # optional

Set OPENAI_API_KEY or RE_AGENT_LLM_API_KEY.

Codex CLI

llm:
  provider: codex
  model: gpt-5.4

Codex uses the authenticated local codex exec command. CLI-provider max_tokens values are planning allowances, not hard output limits.

Omit agents.reverser or agents.checker to reuse the top-level llm configuration for that role. A role block is a complete role configuration, not a field-by-field merge with llm.

Evidence and investigation

When supported by the backend, the reverser preloads a bounded evidence bundle and can request additional read-only operations:

• decompile, xrefs_from, and xrefs_to
• struct and enum
• vtable, global, and strings
• context, normalized pcode, and cfg

Evidence bundle data is also ingested into reports/re-agent/knowledge-graph.json, connecting functions, calls, globals, and strings. Unsupported bridge capabilities degrade gracefully.

Candidate validation

Generated code is written to an overlay. With copy_project: true, the project is copied to a temporary directory, the candidate replaces the matching body there,