eighty-three

A ZX81 emulator for macOS, Linux and Windows, with ZXpand+ support, a debugger and an MCP server.

The emulation core is based on EightyOne by Michael D Wynne, rebuilt around C++17 + SDL2 + CMake with a new front end.

What it does:

• Video is generated per CPU cycle, the way the ZX81 itself does it, so SLOW and FAST modes and WRX hi-res work.
• Sound: the beeper and the AY-3-8910 (ZonX / ZXpand+).
• Keys are mapped by physical position, so the OS keyboard layout does not matter. Any key can be rebound.
• ZXpand+: the SD card is a folder on your disk, and the ZXpand Commander shell boots from the menu.
• Loads .P, .P81, .Z81, .O, .80, .81 by drag-and-drop or from File > Open, and saves .P, .P81, .T81 or a .Z81 snapshot. .P files go through the ROM's own LOAD routine, so programs that auto-start do.
• Debugger: disassembly, registers, memory and stack editing, breakpoints (execution, conditional, and watchpoints on memory or ports), an inline assembler, a BASIC listing view.
• e83_mcp, a headless ZX81 with 66 tools over the Model Context Protocol, in every release package.

Install

Prebuilt packages are on the releases page.

macOS 11 and later on Apple Silicon, macOS 10.15 and later on Intel. One universal app covers both. Unpack and drag eighty-three.app into Applications; the bundle carries its own SDL2, the ROMs and the guide. It is signed ad-hoc and not notarised, so the first launch of a downloaded copy is refused. On macOS 15 and later: double-click it, dismiss the warning, then System Settings > Privacy & Security > Open Anyway. On macOS 14 and earlier: right-click the app > Open > Open.

Windows. Unpack the zip anywhere and run eighty-three.exe. SDL2 and the Microsoft C++ runtime are in the folder. The executable is unsigned, so SmartScreen shows "Windows protected your PC" the first time: More info > Run anyway. Keep the folder together, because the emulator reads ROMs\ and USER_GUIDE.md from next to the exe.

Linux. Unpack the tarball and run ./install.sh, which installs into ~/.local without root, or run ./eighty-three from the unpacked folder. The prebuilt binary links your system's SDL2 and its file name says which distribution it was built on. If it does not start on yours, build from source:

git clone https://github.com/alffcpu/eighty-three.git
cd eighty-three
./scripts/build.sh --deps    # installs what is missing, then builds
./build/eighty-three

build.sh recognises pacman, apt, dnf, zypper, apk, xbps, emerge and brew, and checks dependencies by capability rather than by package name, so a hand-built SDL2 counts. Without --deps it installs nothing: it prints the exact command for your system and stops.

First-launch details: USER_GUIDE.md, Getting Started > Installing.

Quick start

The emulator boots to the ZX81 BASIC prompt, a blinking K cursor.

• Load. Drag a .P file onto the window, or File > Open.
• Type. P types PRINT at the K cursor, as on a real ZX81. Symbols come from the ZX81 SHIFT layer. The on-screen keyboard, with legends read from the ROM, is under File > Settings > Input > Remap ZX81 keyboard.
• ZXpand+. Put .p files into Documents/eighty-three/ZXpand_SD_Card/ and browse them with Machine > ZXpand+ menu.
• Settings. File > Settings covers the ROM edition, RAM size, WRX hi-res, ZXpand+, sound, display scale and theme.
• Help. Info > Help opens the user guide inside the emulator.

USER_GUIDE.md covers the keyboard, file formats, settings, sound, the debugger and the MCP server.

Screenshots

MCP server

e83_mcp speaks the Model Context Protocol over stdio and exposes 66 tools: registers, memory, single-stepping, breakpoints, disassembly, an inline assembler, the BASIC listing, the keyboard, the ZXpand SD card, and the screen both as a PNG and as text. It also measures: coverage, an instruction trace, a T-state profiler that separates the program's own work from the time the CPU spends drawing the picture, sound capture, and recording the screen to a GIF. Load a symbol file and every address argument takes a label name.

It is its own headless ZX81, not a remote control for the emulator window. The agent gets a machine of its own to boot, load programs into and inspect. The GUI can run at the same time; the two are independent.

The server ships in every release package next to the emulator. Its single argument is the folder containing ROMs/: the unpacked package folder on Linux and Windows, and eighty-three.app/Contents/Resources/ on macOS, where the ROMs travel inside the bundle.

{
  "mcpServers": {
    "eighty-three-zx81": {
      "command": "/path/to/eighty-three-1.1-linux-x86_64/e83_mcp",
      "args": ["/path/to/eighty-three-1.1-linux-x86_64/"]
    }
  }
}

Clients with a command line can add it in one line, for example claude mcp add eighty-three-zx81 -- ./build/e83_mcp ./build/. The repository also carries a .mcp.json for clients that read that convention.

Protocol details, the full tool table and the argument formats: USER_GUIDE.md, MCP Server for AI Agents.

Build from source

./scripts/build.sh --deps --test   # macOS/Linux: install what is missing,
                                   # build, run the test suite

scripts\build.cmd --test   :: Windows: Visual Studio 2022 + vcpkg

Details, CMake options and how releases are packaged: BUILDING.md.

ROMs

The ZX81 ROM images and the ZXpand+ overlay are included, so the emulator runs out of the box. They are third-party firmware, not covered by this project's licence, and each keeps its own copyright. The conditions they are distributed under are in roms/NOTICE.txt.

Licence

GPL-2.0-or-later, inherited from EightyOne (© Michael D Wynne). Full text: COPYING.

Bundled third-party components keep their own licences, listed in THIRD_PARTY_LICENSES.md: the Fuse Z80 core, Pasmo, Dear ImGui, nlohmann/json, JetBrains Mono, the ROM images and the ZXpand Commander menu program.

Credits

• Michael D Wynne, EightyOne, whose emulation core this is built on.
• Philip Kendall and the Fuse team, the Z80 core.
• Charlie Robson, ZXpand+ and the ZXpand Commander shell.
• Julián Albo, Pasmo, the Z80 assembler used by the inline assembler.
• Omar Cornut, Dear ImGui.