Mizuchi

🐉 Forge C from the ashes of assembly. What the compiler consumed, the dragon returns.

Mizuchi automates the cycle of writing C code, compiling, and comparing against a target binary, towards the goal of fully automatic matching decompilation.

It orchestrates a plugin-based pipeline that can leverage programmatic and AI-powered tools to automatically decompile assembly functions to C source code that produces byte-for-byte identical machine code when compiled.

• ✨ Automatic retries with detailed context on compilation or match failures
• 🐍 Integration with Claude, m2c, decomp-permuter, and objdiff.
• 🗺️ Decomp Atlas, a powerful webapp to browse functions and generate rich prompts in one click
• 📊 Beautiful Report UI to visualize the pipeline result

📚 Learn about this project and its benchmarks on this post

Achieve fully matching code automatically

Even partial matches provide a good start

Explore the function cloud by similarity

Pick your next function to decompile based on scoring

Build rich prompts to decompile a function in a single click

⚙️ What is Matching Decompilation?

Matching decompilation is the art of converting assembly back into C source code that, when compiled, produces byte-for-byte identical machine code. It’s popular in the retro gaming community for recreating the source code of classic games. For example, Super Mario 64 and The Legend of Zelda: Ocarina of Time have been fully match-decompiled.

Learn more by watching my talk.

npm install
npm run build && npm run build:ui

To enable the m2c programmatic phase:

git submodule update --init vendor/m2c
./scripts/setup-m2c.sh

To enable decomp-permuter (brute-force mutation matching). Works both in the programmatic phase and as background tasks during the AI-powered phase:

git submodule update --init vendor/decomp-permuter
./scripts/setup-decomp-permuter.sh

• ANTHROPIC_API_KEY environment variable set or login on Claude Code to cache credentials locally

1. Create a configuration file: Copy the example config and customize it for your project.

cp mizuchi.example.yaml /path/to/you/decomp/project/mizuchi.yaml

1. Index your codebase:

npm start -- index-codebase --config /path/to/your/decomp/project/mizuchi.yaml

1. Start the Decomp Atlas server:

npm start -- atlas --config /path/to/your/decomp/project/mizuchi.yaml

1. Generate prompts: Open Decomp Atlas at http://localhost:3000/, browse the functions and generate the prompts

2. Run the pipelines:

npm start -- run --config /path/to/your/decomp/project/mizuchi.yaml

Mizuchi executes a pipeline of plugins:

📌 Roadmap: See the issues tab for planned features.

Mizuchi generates three output files:

Decomp Atlas is a web UI for exploring your decompilation project and target the next functions to decompile. It includes a prompt builder that generates rich decompilation prompts.

# Build the CLI and UI
npm run build && npm run build:decomp-atlas

# Start the Decomp Atlas server
npm start -- atlas --config mizuchi.yaml

The server reads your mizuchi.yaml config and serves the Decomp Atlas UI at http://localhost:3000.

Note: Your project must have a mizuchi-db.json file in the root directory for the Decomp Atlas to work. Generate it with mizuchi index-codebase (see below).

The index-codebase command scans your decompilation project and generates a mizuchi-db.json file containing all discovered functions, their assembly, C source (if decompiled), call graphs, and vector embeddings.

1. Configure your mizuchi.yaml:

Add nonMatchingAsmFolders to the global section listing directories that contain non-matching assembly files (relative to projectPath):

global:
  projectPath: /path/to/decomp/project
  mapFilePath: /path/to/project.map
  target: gba # or n64, ps1, etc.
  nonMatchingAsmFolders:
    - asm/non_matching
    - asm

2. Run the indexer:

# Build first (if not already done)
npm run build

# Index the codebase
npm start -- index-codebase --config mizuchi.yaml

# Or in development mode
npm run dev -- index-codebase --config mizuchi.yaml

The indexer performs three phases:

1. Scan matched functions — finds C function definitions via ast-grep, resolves each to its compiled .o file using the map file, and extracts assembly via objdiff
2. Scan unmatched functions — reads .s/.S/.asm files from nonMatchingAsmFolders and parses function boundaries
3. Compute embeddings — generates vector embeddings using jina-embeddings-v2-base-code via a Python subprocess with MPS GPU acceleration (Apple Silicon) or CPU fallback

Options:

Incremental indexing: Re-running the command only recomputes embeddings for new or changed functions. Unchanged functions preserve their existing embeddings.

Python requirements for embeddings: Python 3.10+ is required. On first run, the indexer automatically creates a virtual environment at ~/.cache/mizuchi/python-venv/ and installs torch and transformers (~2-3 GB). The model weights are cached at ~/.cache/huggingface/. Use --skip-embeddings to skip this entirely.

See DEVELOPMENT.md for development setup, commands, and notes.