GitHub - neuromancer/rats-re · GitHub
/" data-turbo-transient="true" />
Skip to content
Search/
Sign in<br>Sign upAppearance settings
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
neuromancer
rats-re
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>21 Commits<br>21 Commits
config
config
docs
docs
ghidra
ghidra
include
include
src
src
wibo-src @ 7aaa7d9
wibo-src @ 7aaa7d9
.gitignore
.gitignore
.gitmodules
.gitmodules
LICENSE
LICENSE
Makefile
Makefile
README.md
README.md
binary-recons.toml
binary-recons.toml
View all files
Repository files navigation
Rats! source reconstruction with local LLMs
This repository is a work-in-progress reconstruction of the source code for<br>RATS.EXE, the original Windows version of<br>Rats! (1994) by Sean O'Connor. It builds<br>a Win32 executable with Microsoft Visual C++ 4.1 under<br>wibo and can be tested in<br>DREAMM.
The experiment explores how far local LLMs can take source reconstruction on a<br>small but realistic codebase rather than a toy example. Match fidelity remains<br>uneven, which is useful here: the aim is to present a realistic view of the<br>process and its current limitations, not to hide difficult functions.
Function reconstruction is restricted to local LLMs. Codex and Claude are used<br>for repository setup and benchmark orchestration, but they are not allowed to<br>write or edit the reconstructed source.
Unless noted otherwise, all experiments used Qwen3.8 27B BF16 on a 2024<br>MacBook Pro with an Apple M4 Max (16-core CPU, 40-core GPU) and 128 GB of memory.<br>The approach works—imperfectly, but usefully: the 36 retained functions took an<br>average logged time of 2m 32.1s each to reconstruct.
Setup
Clone with submodules, or initialise them after cloning:
git submodule update --init --recursive
The original executable is not included. Download the free Windows version<br>from the official Rats! page and<br>place its RATS.EXE in the repository root to use the original-executable and<br>binary-comparison targets.
Common commands
make # build out/RATS_RE.EXE, .map, .obj, and .asm<br>make toolchain # download, extract, and verify Microsoft Visual C++ 4.1<br>make run # launch the rebuilt executable in DREAMM<br>make run-original # launch the preserved original RATS.EXE<br>make test # bounded DREAMM smoke test of the rebuilt executable<br>make test-original # bounded DREAMM smoke test of the original executable<br>make debug # start the rebuilt executable in DREAMM's debugger<br>make report # report similarity for every reconstructed function<br>make compare-func FUNC=SaveHighScores ADDR=00409092
The checksum-pinned<br>MSVC 4.1 archive,<br>the required MSVC 4.1 libraries, wibo's compatible msvcrt40.dll, and DREAMM<br>4.0x21 are downloaded on demand. They remain ignored local build dependencies<br>and are not committed.
Reconstruction workflow
The checked-in ghidra/ directory contains assembly and decompiler exports for<br>all 177 internal functions. Assembly is the comparison authority; decompiled C<br>is only a semantic seed.
Install binary-recons once, then<br>run it from the repository root:
python3 -m pip install -e /path/to/binary-recons<br>binary-recons --next-function # reconstruct the next safe missing target<br>binary-recons --address 0x409092 # reconstruct or improve a specific target
The tool discovers Qwen automatically in the standard Hugging Face cache;<br>BINARY_RECONS_MODEL_PATH can override it. binary-recons.toml keeps automatic<br>selection inside the game-code ranges, starts and stops llama.cpp, and defines<br>the transactional files and binary-comp command. Each bounded run seeds one<br>function from Ghidra, asks Qwen for focused compile or assembly-diff repairs,<br>and retains the best safe compiling candidate. Use --target-score 95 for a<br>deeper pass or --dry-run-prompt to inspect the prompt without loading Qwen.
Measured local-model runs are recorded in<br>docs/MODEL_RESULTS.md.
Model results: 36 retained functions and 3 deferred addresses<br>Most retained candidates were generated with Unsloth's<br>Qwen3.8 27B GGUF in BF16<br>(Qwen3.8-27B-BF16, served as qwen3.8-27b-bf16) through llama.cpp with a<br>32,768-token context and the qwen model preset. The current workflow uses<br>Ghidra's decompilation as a mechanical seed, asks Qwen only for a meaningful<br>contract and bounded source edits, follows valid edits as a repair trajectory,<br>and retains the best result measured by binary-comp. Gemma 4 31B IT BF16 was<br>also benchmarked, but none of its candidates is retained in the source tree.
The scores below were remeasured from the current source tree with MSVC 4.1 and<br>binary-comp on 2026-08-16. Logged time includes managed-server...