ZX Vibes Manual

This manual is the source-of-truth walkthrough for building a ZX Spectrum 48K project with the published zx-vibes packages. It covers installation, project creation, agent use, optional MCP setup, the manual CLI loop, debugging, testing, previewing, and troubleshooting.

Use it when you are making a game or small Spectrum program. If you are modifying the zx-vibes monorepo itself, use the repository workflow in the root README instead.

Start Here

InstallationCheck Node, pnpm, and terminal prerequisites before creating a project.Create a ProjectGenerate a game or platformer starter and understand the files it writes.First BuildRun the build, emulator, screen inspection, tests, and verify loop.Agent WorkflowGive Codex, Claude Code, or another coding agent the right local context.

Manual Sections

• Installation
• Create a Project
• First Build
• Agent Workflow
• MCP
• Manual CLI Workflow
• Debugging
• Testing
• Preview and Play
• Troubleshooting

What zx-vibes Provides

• pnpm create zx-vibes to scaffold a working Spectrum project.
• zxs build, zxs run, zxs verify, and zxs preview for the local loop.
• zxs boot and zxs play for browser playback of a clean 48K machine, snapshots, and tape files.
• Snapshot, memory, graphics, disassembly, scan, and xref commands for inspection and reverse-engineering workflows.
• zxs-mcp for Codex, Claude, and other MCP-capable coding agents.
• A default embedded Z80 assembler from @zx-vibes/asm, also exposed as zxasm.
• Local reference docs and project-local agent skills copied into generated projects.

The intended workflow is deliberately short: edit assembly, build, run in the emulator, inspect what happened, add or update tests, and verify before calling the task done.