---
slug: "regenerator2000"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ricardoquesada/regenerator2000@main/README.md"
repo: "https://github.com/ricardoquesada/regenerator2000"
source_file: "README.md"
branch: "main"
---
# Regenerator 2000

![Rust](https://github.com/ricardoquesada/regenerator2000/actions/workflows/rust.yml/badge.svg)
[![Crates.io Version](https://img.shields.io/crates/v/regenerator2000)](https://crates.io/crates/regenerator2000)
[![discord](https://img.shields.io/discord/775177861665521725.svg)](https://discord.gg/r5aMn6Cw5q)

![logo](https://github.com/ricardoquesada/regenerator2000/raw/HEAD/docs/regenerator2000_logo.png)

A modern, interactive 6502 disassembler for Commodore 8-bit machines. A modern take on [Regenerator][regenerator].

- **🕹️ Manual Analysis** — A fast, keyboard-centric TUI for hands-on exploration: navigate code, define data, label subroutines, add comments, and iteratively refine your disassembly.
- **🤖 Automated Analysis** — A built-in MCP Server lets AI assistants drive the disassembler programmatically. Paired with purpose-built skills, it can analyze entire programs — classifying blocks, tracing routines, and naming symbols — with minimal human intervention.

Use either workflow on its own, or combine them: let the AI do a first pass, then refine the results interactively.

Check out the [Examples](https://regenerator2000.readthedocs.io/en/latest/examples/) to see what can be accomplished, featuring pre-disassembled games across different Commodore platforms!

[regenerator]: https://csdb.dk/release/?id=247992

## Features

Regenerator 2000 brings modern conveniences to 6502 disassembly:

- **Disassembly**: Full 6502 support including undocumented opcodes.
- **Hex Dump**:
  - Side-by-side view with disassembly.
  - Synchronized or independent navigation.
  - Unshifted or Shifted PETSCII and Screencode charset.
- **Sprites**:
  - Side-by-side view with disassembly.
  - Multicolor or Single Color
- **Bitmap**:
  - Side-by-side view with disassembly.
  - High-Resolution (320x200) and Multicolor (160x200).
  - Uses quadrant-block rendering for full resolution in TUI.
- **Charset**:
  - Side-by-side view with disassembly.
  - Multicolor or Single Color
- **Blocks**:
  - Side-by-side view with disassembly.
- **Debugger**: Connect to VICE for live disassembly, breakpoints, run/step (F2–F9); Debugger panel in the right pane.
- **Mini map**: Mini map of the file being analyzed.
- **Systems**: Supports Commodore 8-bit machines: C64, C128, VIC-20, Plus/4, PET 4.0, PET 2.0, and 1541.
- **Import**: Load the following file formats
  - PRG: PRG files
  - CRT: Cartridge images with bank selection support
  - D64: 35/40/42-track disk images
  - D71: 70/80-track double-sided disk images
  - D81: 80-track disk images
  - T64: Tape images
  - VSF: VICE Session files
  - RAW / BIN: Raw binaries files
  - DIS65: 6502bench project files
  - REGEN2000PROJ: Regenerator 2000 project files
- **Binary Unpacker**: Emulate a cycle-accurate 6502 background sandbox to automatically decompress packed C64 programs.
- **Export** to .asm or HTML. Supported assemblers:
  - **64tass**
  - **ACME**
  - **Kick Assembler**
  - **ca65**
- **Project Management**: Save and load your work
- **Analysis**: Auto-analysis to identify code and data regions.
- **Editing**:
  - **Labels**: Add, edit, and remove local and global labels.
  - **Enums**: Define and apply three-tiered value-to-name mappings (System, Global, Project-specific) to replace magic numbers in disassembly and data with semantic names.
  - **Comments**: Add side comments and line comments.
  - **Origin**: Change the load address/origin of the binary.
  - **Data Types**: Convert regions to Code, Byte, Word, Address, Lo/Hi Address, Hi/Lo Address,
    Lo/Hi Word, Hi/Lo Word, PETSCII Text, Screencode Text, External File, or Undefined.
  - **Undo/Redo**: Full history support for all actions.
- **Navigation**:
  - **Jump**: Go to specific addresses, specific line numbers, or follow
    operands.
  - **X-Ref**: Inspect cross-references for labels/addresses.
  - **History**: Navigate back to previous locations.
- **Customization**:
  - Configure document settings (max x-refs, system, assembler).
  - Customizable display options (show/hide all labels, etc.).
- **TUI**:
  - Text User interface
  - Everything can be done from the keyboard
  - **Visual Mode**: Vim-like selection for batch operations.
- **MCP Server**:
  - Model Context Protocol (MCP) server support for programmatic access
  - HTTP and stdio transport modes
  - Tools for disassembly manipulation, memory search, block operations
  - Resources for accessing binary data and views
  - Bundled analysis skills that automate block classification, routine tracing, and symbol naming
- **Fast**:
  - Extremely fast

![hexdump screenshot](https://github.com/ricardoquesada/regenerator2000/raw/HEAD/docs/regenerator2000_hexdump_screenshot.png)
![charset screenshot](https://github.com/ricardoquesada/regenerator2000/raw/HEAD/docs/regenerator2000_charset_screenshot.png)
![sprites screenshot](https://github.com/ricardoquesada/regenerator2000/raw/HEAD/docs/regenerator2000_sprites_screenshot.png)
![bitmap screenshot](https://github.com/ricardoquesada/regenerator2000/raw/HEAD/docs/regenerator2000_bitmap_screenshot.png)
![debugger screenshot](https://github.com/ricardoquesada/regenerator2000/raw/HEAD/docs/regenerator2000_debugger_screenshot.png)

## Requirements

### Recommended Terminals

To ensure the best experience, especially regarding keyboard shortcuts and rendering, we recommend using a modern
terminal.

| Platform    | Recommended Terminals                              |
| :---------- | :------------------------------------------------- |
| **Windows** | Windows Terminal, Alacritty, WezTerm               |
| **macOS**   | iTerm2, Ghostty, Alacritty, kitty, WezTerm         |
| **Linux**   | Ghostty, Alacritty, kitty, WezTerm, GNOME Terminal |

## Installation

### From Crates.io

```bash
cargo install regenerator2000
```

### From Source

```bash
git clone https://github.com/ricardoquesada/regenerator2000.git
cd regenerator2000
cargo install --path .
```

### Quick Start with AI Agents

To quickly start analyzing binaries using an AI agent (such as Antigravity or Claude Code), you can use the [regenerator2000-template](https://github.com/ricardoquesada/regenerator2000-template) repository. It comes pre-configured with all the required skills and agent permissions so you can start analyzing and reverse-engineering binaries immediately.

## Usage

Start the application with an optional file to load:

```bash
regenerator2000 [OPTIONS] [path/to/file.prg]
```

## CLI Options

- `--help`: Print help message
- `--version`: Print version information
- `--import_lbl <PATH>`: Import VICE labels from the specified file
- `--export_lbl <PATH>`: Export labels to the specified file (after analysis/import)
- `--export_asm <PATH>`: Export assembly to the specified file (after analysis/import)
- `--export_html <PATH>`: Export HTML to the specified file (after analysis/import)
- `--assembler <NAME>`: Override the assembler format for export. Valid values: `64tass`, `acme`, `ca65`, `kick`
- `--headless`: Run in headless mode (no TUI), useful for batch processing
- `--verify`: Verify export roundtrip (export → assemble → diff) for all assemblers. Implies `--headless`
- `--mcp-server`: Run MCP server (HTTP on port 3000)
- `--mcp-server-stdio`: Run MCP server via stdio
- `--vice <HOST:PORT>`: Auto-connect to VICE binary monitor at startup (e.g. `--vice localhost:6502`)
- `--dump-system-config-files <PATH>`: Dump all built-in system config files (`system-*.toml`) to the specified directory and exit. Useful for inspecting or customizing system definitions.
- `--dump-theme-files <PATH>`: Dump all built-in theme files (`theme-*.toml`) to the specified directory and exit. Edit them and place in the [config directory](https://regenerator2000.readthedocs.io/en/latest/install/) to create custom themes.
- `--dump-enum-files <PATH>`: Dump all built-in enum files (`enum-*.toml`) to the specified directory and exit. Edit them and place in the [config directory](https://regenerator2000.readthedocs.io/en/latest/install/) to create custom enums.

Supported file formats: `.prg`, `.crt`, `.d64`, `.d71`, `.d81`, `.t64`, `.vsf`, 6502bench (`.dis65`), `.bin`, `.raw`, and `.regen2000proj`.

## Keyboard Shortcuts

All the keyboard shortcuts are documented here: [keyboard_shortcuts](https://regenerator2000.readthedocs.io/en/latest/keyboard_shortcuts/)

## Support and Documentation

- [Documentation](http://regenerator2000.readthedocs.io/)
- [Examples](https://regenerator2000.readthedocs.io/en/latest/examples/): Disassembled Commodore games and software showcase, demonstrating what can be achieved with Regenerator 2000 on various supported platforms.
- [Support in Discord][discord] (join the `#regenerator2000` channel, under **"Misc Projects"**)

[discord]: https://discord.gg/r5aMn6Cw5q

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Acknowledgements

- [Regenerator][regenerator]: The original 6502 disassembler for Windows.
- [unp64][unp64]: The C64 binary unpacker by iAN CooG, which the unpacker module is based on.
- [64tass][64tass], [ACME][ACME], [Kick Assembler][Kick Assembler], [ca65][ca65] : Supported assemblers.

[unp64]: https://csdb.dk/release/?id=260619
[64tass]: https://tass64.sourceforge.net/
[ACME]: https://sourceforge.net/projects/acme-crossass/
[Kick Assembler]: http://www.theweb.dk/KickAssembler/
[ca65]: https://cc65.github.io/

## License

Dual license: MIT and Apache 2