universal-os

Skills, tools, an MCP server and a shared knowledge base that let an AI coding agent reverse engineer an existing operating system from its ISO and rebuild it — ReactOS style — component by component, until apps written for the original OS run on the rebuild.

Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, or anything that reads AGENTS.md or speaks MCP. Point the agent at a Windows ISO (any version: XP, 7, 10, 11, Server), it fingerprints the image, boots it in a headless QEMU sandbox, surveys what the OS actually exposes, writes behavioral specs, scaffolds ReactOS-style C components, builds them, boots the rebuild, and tests real Windows apps on it. Every session leaves field notes the next agent starts from.

   ISO ──► fingerprint ──► sandbox VM ──► survey (API surface, traces)
                                            │
            behavioral specs ◄──────────────┘
                   │
            scaffold + build (ReactOS-style C, .spec exports)
                   │
            rebuilt image ──► boot in VM ──► test real apps ──► behavior_diff
                                                                    │
                                                        field note for the next agent

Install

Pick your agent. Each gets the same skills, the universal-os MCP server, and the uos CLI. Everything below installs straight from this repo — no PyPI release needed yet.

The CLI, anywhere:

uv tool install git+https://github.com/Jenischristan/universal-os   # or: pip install git+https://github.com/Jenischristan/universal-os

Both entry points (uos, uos-mcp) land on your PATH. There is no universal-os-mcp command — the MCP server executable is uos-mcp (uos mcp is the same thing).

You need Python 3.10+, and QEMU for the VM parts (git, cmake, ninja and a MinGW toolchain when you reach the build phase):

sudo apt-get install -y qemu-system-x86 qemu-utils   # Debian/Ubuntu
brew install qemu                                    # macOS
winget install SoftwareFreedomConservancy.QEMU       # Windows

uos env checks all of it and prints what's missing.

Try it

Rebuild the core of the Windows XP SP3 ISO at ~/isos/en_win_xp_sp3.iso far enough to run notepad.exe and cmd.exe.

This is a Windows 7 ISO. Fingerprint it, boot it in a VM, dump the kernel32/user32/ntdll API surfaces, and tell me how far the ReactOS component set already covers it.

Take my rebuilt workspace, test Notepad2 on it, and add compat quirks for everything that breaks.

The agent starts with the build-any-os skill and runs the same loop every time:

1. search the knowledge base; 2. fingerprint the ISO; 3. check the environment;
2. set up a sandbox lab (VM, snapshots); 5. survey the reference OS (API surfaces, traces);
3. pick the component route; 7. write behavioral specs; 8. build one working slice;
4. boot the rebuild and test real apps; 10. write a field note for the next agent.

A knowledge base AIs write for AIs

knowledge/ holds field notes: how specific OS rebuilds actually went — the exact ISO versions, the component order that worked, the interface facts, the verification, the gotchas (symptom → cause → fix). Every agent that finishes a milestone can open a PR with its note, so the next agent starts where the last one left off.

uos kb search "windows xp ntdll"     # before you start: prior art
uos kb new --os "windows-xp" --component ntoskrnl --title "First boot" --agent "Claude"
uos kb check knowledge/os/windows-xp/....md

Contribution rules, for humans and AIs, are in RULES.md: no Microsoft binaries, no decompiled code, no media links, honest status and verification.

What's inside

Rules it follows (moderate level — full text in RULES.md)

• Everything untrusted runs inside the sandbox VM, never on the host. The reference ISO is never mounted on the host; it is read with the built-in ISO parser or booted in QEMU.
• Inspection is free; shipping is not. Inside the VM the agent may run, trace, dump and analyze anything. What may enter the rebuilt OS repo is: interface facts (names, ordinals, versions, structures), behavioral specs, and clean-room code. What may not: Microsoft binaries, drivers, fonts, registry hives, decompiled output, links to OS media.
• VM networking is OFF by default; enabling it needs the user's explicit OK.
• Snapshot before risky operations; restore to undo.
• Keep a journal: WORKSPACE.md in the workspace. It becomes the field note at the end.
• No activation/DRM/licensing bypass, no pirate media, ever.

License and stance

MIT. universal-os is tooling for interoperability and education — the same legal footing as ReactOS and Wine. It ships no Microsoft code, no Microsoft binaries, and does not distribute OS media. What you build with it must pass the same rules; uos kb check and CI enforce the basics, and your jurisdiction and lawyer own the rest.