Bytecode-to-assembly decompiler with jump target resolution, control flow annotation, and label generation for FLUX programs.
flux-decompiler is a Python module that converts FLUX bytecode back to human-readable assembly — it decodes all 30+ opcodes, resolves jump targets into named labels, annotates control flow (↕ conditional, ↓ unconditional, ↻ loop), and produces both clean and annotated assembly output.
The decompiler bridges the gap between raw bytes and understanding:
flux-disasm(C) provides a lightweight C disassembler; decompiler adds Python convenience and annotationsflux-signaturesuses decoded instructions for pattern analysisflux-timelinereferences decoded mnemonics in execution tracesflux-profilermaps opcode counts to human-readable namesflux-debuggershows current instruction names during steppingflux-coverageidentifies which decoded instructions were hit
| Feature | Description |
|---|---|
| Full ISA Coverage | 30+ opcodes: arithmetic, logical, comparison, jump, stack, move |
| Jump Resolution | JZ/JNZ/JMP/LOOP targets resolved to named labels |
| Control Flow Markers | ↕ conditional, ↓ unconditional, ↻ loop annotations |
| Two Output Formats | Clean to_asm() and annotated to_annotated() with stats |
| Mnemonic Statistics | Counts per instruction type in annotated output |
| Signed Operand Handling | Correct sign extension for imm8 and imm16 values |
| Unknown Opcode Handling | Gracefully marks unknown bytes as DATA |
from flux_decompiler import FluxDecompiler
# Decompile a factorial program
bytecode = [0x18, 0, 6, 0x18, 1, 1, 0x22, 1, 1, 0, 0x09, 0, 0x3D, 0, -6, 0, 0x00]
dec = FluxDecompiler(bytecode)
result = dec.decompile()
print(f"Instructions: {result.total_instructions}, Bytes: {result.total_bytes}")
print(f"Jumps: {result.jump_count}, Labels: {len(result.labels)}")
# Clean assembly output
print(result.to_asm())
# Annotated output with stats and control flow markers
print(result.to_annotated())python -m pytest tests/ -v
# or
python decompiler.pyflux-disasm— C disassembler (lightweight alternative)flux-signatures— Pattern detectionflux-timeline— Execution tracingflux-profiler— Performance profilingflux-debugger— Step debugger
Part of the SuperInstance FLUX fleet.