Agent-first developer guide
Let Claude Code or Codex set up os8088
The quickest way to get started is to use Claude Code or Codex. I recommend using the latest models. Claude Code with Opus 5 and Fable 5 have been the most reliable coding models in this codebase. The goal of this developer's page is to guide you in using one of these models to understand the project, install what it needs, run the tools, boot the OS, and explain to you what it did.
Get the source
Start by cloning the repository:
git clone https://github.com/jggonz/os8088.gitThen run Claude Code or Codex from the os8088 folder.
Open a coding agent
This guide expects you to have Claude Code or Codex installed, signed in, and ready to
code. Run your agent in the os8088 folder after you clone it.
Claude Code
Open Claude Code on the folder where you keep source repositories. It will read the
repository's CLAUDE.md after checkout.
Codex
Open Codex on the folder where you keep source repositories. The setup prompt below
explicitly tells it to use CLAUDE.md as the repository brief.
The agent may need permission for a package manager, an administrator prompt, a download, or opening an emulator window. Read the reason it gives, then approve the action if it matches this setup.
Ask it to set up everything
Paste this as the first prompt. It works whether the repository is already open or has not been cloned yet.
Setup prompt
Help me setup os8088 dependencies so that I can run the 86Box configurations, and start contributing to this project. Set up this computer and repository for me end to end.
If os8088 is not already the current repository, clone https://github.com/jggonz/os8088.git into an os8088 directory and continue there. Read CONTRIBUTING.md, CLAUDE.md, README.md, and the relevant setup scripts before changing anything. Treat CLAUDE.md as the repository's agent instructions even if you normally look for another filename.
Detect the host operating system. Install or check the required development tools using the setup path documented by the project. On Windows, use WSL2 and keep the checkout inside its Linux filesystem. Ask before using administrator privileges or making external downloads, and explain each approval in one sentence. Configure the repository's Git hooks. Include 86Box and the matching ROM set when this host supports them.
After setup, build all standard floppy images. Boot os8088 headlessly in QEMU, drive it with the repository's own test tools, take and inspect a screenshot, and shut the emulator down. Do not modify product source. Fix setup problems you can safely fix, then retry the failed check.
Finish with a short report: what you installed or configured, what you successfully built and booted, the screenshot you inspected, and anything that still needs me.Stay in the conversation while it works. If it asks for an approval, answer there. If it finds a platform-specific choice, let it recommend one based on the checked-in documentation before you decide.
Try the virtual 86Box machines
Open a fresh terminal, change into the os8088 checkout, and use make
to launch an 86Box configuration. Each target builds the floppy images it needs before
opening the machine. Start with the standard XT:
cd os8088
make xtThe repository includes these period-correct machines:
XT configurations
make xt | An IBM PC/XT, 8088 at 4.77MHz, 256KB, VGA, and two 360KB floppies. |
|---|---|
make xt-640 | The same XT with VGA and 640KB of RAM. |
make xt-cga | A 256KB XT with CGA at 640x200 monochrome. |
make xt-hercules | A 256KB XT with Hercules at 720x348 monochrome. |
make xt-multimon | A 640KB XT with CGA and Hercules Plus; 86Box opens one window per card. |
make xt-sound | A 640KB XT with a Sound Blaster. |
Later PCs
make 286 | AMI 286 clone board, 12.5MHz, 1MB, and two 1.44MB drives. |
|---|---|
make 286-sound | The same board with a Sound Blaster 16. |
make 386sx | Shuttle HOT-304, 386SX at 16MHz, with 2MB. |
make 386 | Micronics 386DX board at 25MHz, with 2MB. |
make 386-xms | The same 386 with 4MB; Task Manager shows the XMS line. |
make 386-sound | The 386DX/25 with a Sound Blaster 16. |
make 486 | AMI 486 board, 486DX2 at 66MHz, 8MB, and Sound Blaster 16. |
make pentium | ASUS P/I-P55TP4XE, Pentium 133MHz, 16MB, and Sound Blaster 16. |
Making a change
Making a change is easy, just ask Claude Code or Codex to make the change you want.
Sample prompt
ultracode a control panel interface that lets me set the background color from a new control panel.When to use ultracode
Use ultracode for a substantial, self-contained feature when you want the
agent to explore the codebase, make a plan, implement the work, and verify it independently.
Use an ordinary prompt for a small, tightly scoped edit, a straightforward bug fix, or when
you want to review and direct each step yourself.
Creating an app
For a new standalone application, describe what you want to make and let the agent work from the package API and the existing examples in the repository.
Sample prompt
ultracode an excel spreadsheet clone that has a left tools menu instead of a top tools barPorting an existing app
To port an existing app, use an ultracode prompt that references a source repository to build a port of the app.
Sample prompt
ultracode a port of missile command from the ../6502-assembly-missile-command to work in os8088 as a packagePorting a C/C++ app
If you want to port a C/C++ app written for Windows, DOS, Linux, or any other operating
system, you can use the built in /port-to-os8088 skill like this:
Sample prompt
/port-to-os8088 the spreadsheet app in ../specialSheets-inCplusplusPrepare the Pull Requests
Let the agent do the mechanical checks and draft the explanation. Keep the final commit, push, and pull request under your approval.
Review prompt
Prepare this os8088 change for contribution, but do not commit, push, or open a pull request until I approve. Read CONTRIBUTING.md. Review the complete diff for correctness, 8086 compatibility, register and segment rules, memory and performance regressions, generated files, and missing specification updates. Run a clean build and the relevant boot verification again. Inspect the final screenshots. If everything passes, draft a commit message and a pull request body that state what changed, why, which SPEC.md sections changed, the exact verification performed, and whether the 360KB image was checked.