Compiler-in-the-loop decompilation workbench for binary-matching game reversing.
Rebrew recompiles your C with the compiler that built the target and compares the bytes against the target, function by function; a function is done when they are identical (EXACT, or RELOC after masking relocations). One Python CLI carries the compile-compare loop, a genetic-algorithm matcher, the function metadata store, and the verifier.
- Function authoring, byte diffs, compiler flag search, GA matching, and bounded symbolic proofs.
- Library identification, globals/types, data layout, and whole-binary verification.
- Prioritized work and separate file, executable-byte, and stored data-verdict accounting.
- BinSync field reconciliation and provenance, plus live Ghidra structural operations.
- Symbol exports: splat
symbol_addrs, and a synthetic PDB stamped with the target's own debug-record GUID/age (rebrew export pdb, needsllvm-pdbutil). - Config-driven toolchains, compile caching, and six packaged agent workflows.
See the documentation index for guides, reference contracts, and integrations. The CLI reference owns command flags; toolchain documentation owns compiler/platform support.
Use Python 3.15+ and Linux x86_64 with Docker (default) or Podman for shipped
compiler profiles.
Wine, DOSBox, and native compiler runtimes live inside their images; missing
images require rebrew toolchain pull <profile> or an authorized build from
recompile-toolchains.
# Preferred: rebrew-*.whl from https://github.com/maci0/rebrew/releases.
# Installing it builds python-flirt from source, so it needs a Rust toolchain
# unless you override it with the exact published native wheel (see Development).
uv tool install ./rebrew-*.whl
# Fallback: from source (same Rust requirement).
uv tool install git+https://github.com/maci0/rebrew.git
mkdir my-decomp && cd my-decomp
rebrew intake /path/to/server.dll # scaffold, detect compiler, discover, document stubs
rebrew doctor # resolve relevant prerequisite failures
rebrew toolchain list # inspect the detected profile
rebrew status --json # inspect accounting
rebrew todo --json # choose a scoped actionUse rebrew <command> for every tool, including CMake and objdiff build hooks;
see the CLI reference.
rebrew schema prints the clispec 0.3 document, needs no project, and stays
JSON under rebrew -o text. For every other command, rebrew -o json <command>
selects JSON and rebrew -o text stays text. Each
command's own --json selects the same JSON output; it is declared per
command, so it must follow the command name. A pipe stays text until one of
those is set.
Symbolic proving needs the optional extra in the environment running Rebrew:
uv tool install --reinstall 'rebrew[prove] @ git+https://github.com/maci0/rebrew.git'.
BinSync needs the binsync extra; combine extras as rebrew[prove,binsync]
when using both. Contributor checkouts use make setup.
intake does not run library detection or build coverage documents. Continue
with Getting started.
Project commands find rebrew-project.toml by walking up from the working directory;
standalone binary inspection commands can accept a binary path.
For a manually configured project, use rebrew init --target server --binary server.dll,
place the binary in original/, then follow rebrew doctor. Target names normally
use the binary stem (server); binary filenames keep the extension (server.dll).
rebrew todo --json # select an existing stub or uncovered function
rebrew test src/server/fcn_10003da0.c --json
rebrew diff src/server/fcn_10003da0.c --json
rebrew verify --compare --json
rebrew lint --json
rebrew coverage export --output snapshots/ # optional portable snapshots for offline viewingintake names its stubs fcn_<VA>.c; for a catalog VA with no source,
rebrew skeleton 0xVA prints the file it creates.
Check library attribution before implementing a function. test and verify
earn byte verdicts, including regressions. EXACT and RELOC count as matched;
a RELOC function whose bytes in the raw link equal the reference becomes EXACT
through rebrew verify --text --raw-link (linked EXACT);
PROVEN records semantic evidence under the proof's assumptions and earns no
byte-match credit. See match types.
Function/data metadata are CLI/API-managed. Never hand-edit their TOMLs or write
STATUS in C. Function identity and state live in format-3 MODULE.0xVA metadata rows;
addressless evidence and support purposes live under [source] in the same store.
Source can include optional /* ADDRESS: MODULE 0xVA */ anchors immediately
above definitions. Retired source tags and old metadata formats are rejected. See
metadata ownership.
For integration sync, preview a concrete state directory first:
rebrew sync pull --state-dir ./binsync-state --dry-run --json
rebrew binsync diff ./binsync-state --jsonApply incoming changes within the requested scope. Publishing state with
--git-push, uploading source to decomp.me, and starting persistent watch/server
processes require an explicit request. See
BinSync integration.
rebrew init copies AGENTS.md, PRINCIPLES.md, and packaged skills into a project.
rebrew skills list --json lists the effective packaged/user-overlaid skills;
load the skill matching the task and only the references needed for it.
rebrew init --check detects scaffold drift; --refresh-agents regenerates it and keeps
anything after the <!-- rebrew: project rules below, kept by --refresh-agents --> line.
The Python API guide covers library imports, registry views, structured errors, and injectable clients. The CLI/config compatibility policy and Python/API versioning policy are in CONTRIBUTING.md.
For component authors, the Cordis guide owns the composition contracts; its runnable tutorial demonstrates provider replacement and teardown.
The maintained FLIRT binding builds from an immutable, hash-verified source
archive and requires a Rust toolchain (qualified with Rust 1.99.1 and maturin
1.15.0). Normal CPython 3.15 wheels for qualified Linux glibc, macOS ARM64,
and Windows AMD64 hosts are available in the
maintained binding release.
The Rebrew wheel and source archive are distributed through GitHub releases;
the direct source dependency is not compatible with Warehouse/PyPI publishing.
Managed fixed-platform deployments can override this requirement with the exact
published native wheel using tool.uv.override-dependencies; its hash must be
checked before installation. Free-threaded Python and musl are not qualified. The optional binsync extra
needs a JDK and Apache Ant on PATH to build JPype 1.7.1 on Python 3.15
(qualified with OpenJDK 27 and Ant 1.10.18).
A contributor checkout also needs a sibling
resembl checkout at ../resembl
(tag v5.3.0) and the host tools listed in
CONTRIBUTING.md,
which also says which gate needs each one. From the directory that will hold
both checkouts:
git clone https://github.com/maci0/rebrew.git
cd rebrew/
make doctor # report every missing prerequisite and its fix (read-only)
make clone-resembl # clone the pinned resembl into ../resembl
make setup # uv sync --locked --all-extras --group similarity + pre-commit hooks
make test-one T=tests/test_annotation_roundtrip.py # single-file edit-test loop
make test # full suite
make pr-check # the local CI gates, before a pull requestmake help lists the contributor targets.
Flag-axis refresh from decomp.me (maintainer, needs network):
make gen-flags (FLAGS_REF=<commit-or-tag> to sync a pinned ref instead of the
default branch, make gen-flags-check to report upstream drift). The generated
header's Synced: date follows SOURCE_DATE_EPOCH, so re-syncing one upstream
commit writes the same file.
ECOSYSTEM.md maps public compiler, similarity, coverage and third-party interoperability boundaries. Integration details belong in the topical guides linked from the documentation index.
MIT. See LICENSE. Optional dependency grants and required notices are recorded in NOTICE.
