# Retrodisasm

> Disassemble retro ROMs (NES, CHIP-8) into bit-perfect reassemblable assembly with retrodisasm. Use when the user wants to disassemble a ROM, reverse-engineer NES code, inspect ROM internals, batch-process ROMs, verify reassembly, or convert binaries to assembly source.

- Skill: `yuki001/retrodisasm` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add yuki001/retrodisasm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuki001/retrodisasm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Yuki001 (https://skillmd.com/u/yuki001)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yuki001/retrodisasm

---


# retrodisasm

retrodisasm is a tracing disassembler for NES and CHIP-8 ROMs. It traces execution flow to distinguish code from data, producing assembly that reassembles to a bit-identical binary.

## Binary Resolution

This skill ships prebuilt binaries in `tools/`:

| Platform | Path |
|----------|------|
| Windows | `{skill_dir}/tools/win/retrodisasm.exe` |
| macOS | `{skill_dir}/tools/macos/retrodisasm` |
| Linux | `{skill_dir}/tools/linux/retrodisasm` |

**Always prefer the bundled binary.** Resolve the platform automatically (`uname -s` → `MINGW*`/`MSYS*` = win, `Darwin` = macos, `Linux` = linux) and use the corresponding path. The command examples below use `retrodisasm` as a placeholder — substitute with the actual binary path.

If the bundled binary is missing or unsuitable for the current platform:
```bash
# Option A: download latest prebuilt release from GitHub
#   https://github.com/retroenv/retrodisasm/releases
#   -> extract into {skill_dir}/tools/<platform>/

# Option B: install via Go
go install github.com/retroenv/retrodisasm@latest
```

## Quick Start

```bash
# Basic disassembly (auto-detects NES from .nes extension)
retrodisasm -o output.asm game.nes

# Explicit system and assembler
retrodisasm -s nes -a ca65 -o output.asm game.nes

# Output to stdout
retrodisasm -o - game.nes

# Verify output reassembles to identical binary
retrodisasm -o output.asm game.nes -verify
```

If `-o` is omitted, output defaults to `<input>.asm`.

## Supported Systems and Assemblers

| System | Flag | Assemblers |
|--------|------|------------|
| NES | `-s nes` | `ca65` (default), `asm6`, `nesasm`, `retroasm` |
| CHIP-8 | `-s chip8` | `retroasm` |

Auto-detection by extension: `.nes` → NES, `.ch8` / `.rom` → CHIP-8.

## Assembler Selection

Choose the assembler with `-a`:

| Assembler | Flag | Reassembly command |
|-----------|------|--------------------|
| ca65 | `-a ca65` (default) | `ca65 out.asm -o out.o && ld65 out.o -t nes -o out.nes` |
| asm6 | `-a asm6` | `asm6f out.asm out.nes` |
| nesasm | `-a nesasm` | `nesasm out.asm -o out.nes` |
| retroasm | `-a retroasm` | `retroasm out.asm -o out.nes` |

**Important:** asm6 output requires **asm6f v1.6 (modifications v03)** or later. retroasm does not support `-verify`.

## NES-Specific Options

### Code/Data Log Files

Use a `.cdl` file from FCEUX or Mesen to guide disassembly with known code/data boundaries:

```bash
retrodisasm -o output.asm game.nes -cdl game.cdl
```

### ca65 Linker Config

Specify a custom linker configuration for ca65 output:

```bash
retrodisasm -o output.asm game.nes -c custom.cfg
```

### Undocumented 6502 Opcodes

```bash
# Emit mnemonics instead of .byte directives (incompatible with -verify)
retrodisasm -o output.asm game.nes -output-unofficial

# Stop tracing at unofficial opcodes unless explicitly branched to
retrodisasm -o output.asm game.nes -stop-at-unofficial
```

## Binary Mode

Disassemble raw binary data without an NES/CHIP-8 header:

```bash
# PRG-ROM at standard NES CPU address
retrodisasm -binary -base 8000 -o prg.asm prg.bin

# Custom base address
retrodisasm -binary -base 0200 -o ram.asm ramdump.bin
```

Use `-binary` any time the input lacks a recognized file header.

## Batch Processing

Process multiple ROMs with a glob pattern:

```bash
retrodisasm -batch "roms/*.nes"
```

Each ROM produces `<romname>.asm` in the same directory.

## Output Formatting

| Flag | Effect |
|------|--------|
| `-nohexcomments` | Omit hex opcode bytes from comments |
| `-nooffsets` | Omit file offsets from comments |
| `-z` | Include trailing zero bytes in banks (default: omit) |

Default output format shows address, hex bytes, and instruction:
```asm
Reset:
  sei                            ; $8000 78
  cld                            ; $8001 D8
  lda #$10                       ; $8002 A9 10
  sta PPU_CTRL                   ; $8004 8D 00 20
```

## Verification

`-verify` reassembles the output with the chosen assembler and compares it to the original input. The assembler must be installed and on PATH.

```bash
retrodisasm -o output.asm game.nes -verify
```

Not compatible with `-output-unofficial` or `-a retroasm`.

## Logging

| Flag | Effect |
|------|--------|
| `-debug` | Enable debug logging for troubleshooting |
| `-q` | Quiet mode, suppress non-error output |

## File Reference

| File | What it covers |
|------|---------------|
| Output `.asm` | Reassemblable assembly source |
| Input `.cdl` | Code/data log from FCEUX/Mesen |
| Input `.cfg` | ca65 linker configuration |

## Limitations

- Mapper support is experimental and may not handle all banking scenarios
- Complex self-modifying code may not disassemble perfectly
- retroasm does not support verification
- `-output-unofficial` is incompatible with `-verify`