Let Claude Code or Codex set up os8088

1Open a coding agent

This guide starts with Claude Code or Codex installed, signed in, and showing a prompt. Use whichever interface you prefer: terminal, editor, or desktop app. Give it access to a folder where it may create the os8088 checkout.

2Ask 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

I want to develop os8088. 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.

What the agent handles

3Ask it to prove the setup works

The full setup prompt already requests a boot check. Use this follow-up after an interrupted setup, after changing computers, or whenever "installed" is not enough evidence.

Verification prompt

Prove that this os8088 development environment works without changing tracked files. Read the repository's testing instructions, rebuild the standard disk images, and boot the OS headlessly in QEMU. Use the checked-in mouse and emulator-control tools to open a menu, capture a cropped screenshot, and inspect the image yourself. Shut down the emulator when finished. If a step fails because of the host setup, diagnose it, fix it with my approval where needed, and repeat the failed step. Show me the image and a concise pass/fail report.

If the verification stalls

Do not switch to a terminal tutorial. Give the failure back to the same agent:

Recovery prompt

Continue owning the setup. Read the complete error and inspect the repository's documented troubleshooting before changing anything. Check for a stale emulator, a missing executable, a version mismatch, a missing ROM set, or a host permission problem. Fix only the setup issue, retry the smallest failed check, and then rerun the complete boot verification. Explain any action that still requires me.

4Try the virtual 86Box machines

Once the automated QEMU check passes, ask the agent to open a period-correct machine you can use. This is the first time you need to care about a build command: the prompt names the exact target, and the agent handles it.

IBM PC/XT prompt

Launch the standard IBM PC/XT virtual machine in 86Box for me. Use `make xt`, building anything it needs first. Check that 86Box and its ROMs are ready, explain what I should expect during the first boot, and ask for permission before opening the GUI. Keep the session available while I try os8088. When I tell you I am done, close it cleanly and report any configuration files 86Box changed.

The repository carries multiple virtual machines. Ask for the one that matches what you want to see:

5Describe the change you want

You do not need to translate the task into assembly instructions. Give the agent the behavior, require it to read the contracts, and require a real boot at the end.

Change prompt

Read CLAUDE.md and the relevant sections of SPEC.md before touching code. I want this change:

[Describe the behavior you want and where you expect to see it.]

Inspect the existing implementation and propose a focused plan. Update SPEC.md first if an interface, constant, or data layout changes. Keep the implementation 8086-only and within the documented memory and performance budgets. Build it, boot it, exercise the affected path with the repository's test tools, take a focused screenshot, inspect it, and fix any problem you find. Do not call the work complete because it only assembles. Show me the final diff and the verification evidence.

Starting a new application

For a first project, ask for a small loadable package. The agent can use the existing Hello package as the working example and the package documentation as the contract.

Application prompt

Create a small loadable os8088 package that opens one window and [describe what it should draw or do]. Read CLAUDE.md, the package sections of SPEC.md, and the existing Hello package first. Follow the repository's package API and relocation rules, add the package to the appropriate software disk, and keep code and data within one segment. Build and boot it, launch it from the Disk window, interact with it, and inspect a cropped screenshot before showing me the result.

6Let the agent choose the complete test

The right verification depends on the code. Ask the agent to derive the test matrix from the repository instead of prescribing emulator commands yourself.

Test-planning prompt

Decide and run the complete verification for this diff. Read CLAUDE.md and docs/TESTING.md, identify every behavior and hardware path the change can affect, and tell me the test matrix before running it. Use QEMU automation wherever possible. For visible changes, capture and inspect focused images. Include 360KB media for boot, disk, or FAT changes; include CGA or Hercules for drawing changes; and use a period-correct 86Box machine when timing or hardware behavior cannot be established in QEMU. Shut down every emulator and summarize the evidence and remaining uncertainty.

7Ask it to prepare the contribution

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.