tiny-dec

Learn decompilation by building one from scratch.
_{19 stages. Every step inspectable. From raw RISC-V bytes to readable C.
RV32I: the simplest real ISA, so the focus stays on decompilation, not instruction encoding.}

[!TIP] This project is inspired by the amazing open-source efforts behind angr, radare2, and Ghidra. Thanks for all the open-source work that makes projects like this possible.

[!NOTE] This is a teaching tool, not a production decompiler. The pipeline is deliberately factored into many small, isolated stages so that each concept can be studied independently. A real-world decompiler (Ghidra, IDA, angr, Binary Ninja) would fuse, reorder, or iterate these passes for performance and precision. We trade that efficiency for clarity: if you can follow each stage here, you will understand what the production tools are doing under the hood.

Learn with Our AI Tutor

We ship tiny-dec as a Claude Code plugin. An AI tutor assesses your level, walks you through each pipeline stage, quizzes you, and lets you experiment with real binaries, all inside your terminal.

See the Pipeline in Action

_{A bird's-eye view of all 19 stages. Explore interactively at tiny-dec.zzhang.xyz.}

Quick Start

Learn with the AI Tutor

Install Claude Code, then:

# 1. Add the marketplace
/plugin marketplace add ZhangZhuoSJTU/tiny-dec

# 2. Install the plugin
/plugin install tiny-dec@tiny-dec

# 3. Reload to activate
/reload-plugins

Type /tiny-dec:teach-decompilation to start.

Install from Source

# System dependencies (Ubuntu/Debian)
$ sudo apt-get install -y clang lld llvm binutils build-essential python3 python3-pip

# Python dependencies
$ pip install poetry
$ poetry install

# Build RV32I fixture binaries for tests
$ ./scripts/build_fixtures.sh

Decompile

# Full decompilation to C (default)
$ poetry run tiny-dec decompile ./binary.elf

# Target a specific function
$ poetry run tiny-dec decompile ./binary.elf --func parse_record

# Stop at any intermediate stage and look inside
$ poetry run tiny-dec decompile ./binary.elf --stage ssa --func main

# Inspect binary metadata
$ poetry run tiny-dec info ./binary.elf

Every stage is a window into the pipeline:

loader → decode → pcode → disasm → ir → simplify → dataflow → ssa
→ calls → stack → memory → scalar_types → aggregate_types → variables
→ range → interproc → structuring → c_lowering → c

Test

$ poetry run pytest            # all 500 tests
$ poetry run ruff check .      # lint
$ poetry run mypy tiny_dec     # type check

Example Output

Raw RISC-V instructions go in. Readable C comes out:

; parse_record
addi x2, x2, -32
sw   x1, 28(x2)
sw   x8, 24(x2)
addi x8, x2, 32
sw   x10, -12(x8)
sw   x11, -16(x8)
addi x10, x0, 0
sw   x10, -20(x8)
sw   x10, -24(x8)
jal  x0, 0x11154
lw   x10, -24(x8)
lw   x11, -16(x8)
bge  x10, x11, 0x111b8
lw   x10, -12(x8)
lw   x11, -24(x8)
slli x11, x11, 3
add  x10, x10, x11
lw   x11, 0(x10)
lw   x10, -20(x8)
add  x10, x10, x11
sw   x10, -20(x8)
lw   x10, -12(x8)
lw   x11, -24(x8)
slli x11, x11, 3
add  x10, x10, x11
lw   x11, 4(x10)
lw   x10, -20(x8)
add  x10, x10, x11
sw   x10, -20(x8)
lw   x10, -24(x8)
addi x10, x10, 1
sw   x10, -24(x8)
jal  x0, 0x11154
lw   x10, -20(x8)
lw   x1, 28(x2)
lw   x8, 24(x2)
addi x2, x2, 32
jalr x0, 0(x1)

#include <stdint.h>

typedef struct agg_8 {
  int32_t field_0;
  int32_t field_4;
} agg_8;