temple-os-mcp

An experimental MCP server that lets AI agents write and run HolyC programs on TempleOS through a QEMU VM.

Claude Code (or any MCP client) can execute HolyC code, manage files on the TempleOS filesystem, and capture screenshots of the VM display -- all through structured tool calls. Start the VM with --gui (or TEMPLE_OS_GUI=1) to watch TempleOS respond in real time as the AI works.

Ships with reference documentation served through the temple_reference tool, covering HolyC APIs, TempleOS architecture, working code patterns, and a step-by-step VM setup guide. Includes 14 demo programs showcasing everything from 3D graphics to inline assembly to web connectivity.

Primarily tested with Claude Code.

How It Works

  AI Agent (Claude Code, or any MCP client)
       |
  MCP Server (temple-os-mcp)
       |
  TempleBridge (serial + VM management)
       |
       +--- QEMU Monitor ---  VM lifecycle, screenshots
       +--- Serial (COM1) ---  command execution, file ops, output capture
       |
  QEMU VM (TempleOS)
       |
  SerialAgent.HC             listens on COM1, executes commands, returns output

TempleOS runs in a QEMU VM (4 cores, 512MB RAM) with its serial port mapped to a unix socket
A HolyC agent (SerialAgent.HC) runs inside TempleOS, listening on COM1
The MCP server sends STX/ETX-framed messages over the serial socket
The agent executes commands (run code, read/write files, list dirs) and returns results
All file transfers are base64-encoded for safe binary transport over serial
Each code execution uses an isolated hash table so symbol conflicts don't accumulate
Running HolyC code can issue FETCH/SERVE sub-requests over serial for web connectivity
Screenshots are captured via QEMU's screendump monitor command

Prerequisites

Linux (tested on Fedora 43)
uv (Python package manager)
QEMU with KVM (qemu-system-x86_64)
socat (serial/monitor socket communication)
mtools (writing agent to TempleOS disk during setup)
ImageMagick (convert/magick) for PNG screenshot conversion

Install on Fedora:

sudo dnf install qemu-system-x86 socat mtools ImageMagick

Setup

1. Clone and install

git clone https://github.com/barrettotte/temple-os-claude.git
cd temple-os-claude
uv sync

2. Create disk image and install TempleOS

Download the TempleOS ISO and place it at vm/iso/TOS_Distro.ISO, then:

./scripts/vm.sh create
./scripts/vm.sh install

A QEMU window will open. Follow the prompts: Yes to install, Yes to the VM question, press a key, wait for file copy, Yes to reboot, then close the window when the boot loader menu appears.

3. First-boot setup

This opens a QEMU window for the one-time first boot (dictionary decompression, tour prompt, etc.), then installs the serial agent to disk:

./scripts/vm.sh setup

In the window: select Drive C (press 1), wait for initialization (~30s), say No to the tour, then close the window once you see the C:/Home> prompt.

4. Start the VM

./scripts/vm.sh run       # headless
./scripts/vm.sh run --gui # with QEMU window to watch live

The agent auto-starts from disk. The script polls until it responds.

Verify it's working:

uv run temple ping
# PONG - agent is responding

Using an existing TempleOS VM

If you already have a TempleOS QEMU VM with a qcow2 disk image:

Copy or symlink your disk image to vm/disk/temple.qcow2
Run the agent installer (VM must be stopped):

./scripts/install_agent.sh

Start the VM:

./scripts/vm.sh run --gui

The installer writes SerialAgent.HC and Once.HC to C:/Home/ on the FAT32 filesystem. The agent auto-starts on boot via Once.HC.

Starting a new project

To use the MCP server from your own project repo:

Clone and install temple-os-claude (step 1 above)
In your project, create .mcp.json:

{
  "mcpServers": {
    "temple-os": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/temple-os-claude", "run", "temple-os-mcp"],
      "env": {
        "TEMPLE_OS_VM_DIR": "/absolute/path/to/your-project/vm",
        "TEMPLE_OS_GUI": "1"
      }
    }
  }
}

Open Claude Code in your project directory. The agent can set up the VM automatically -- it will create the disk image, download the TempleOS ISO, drive the installer via keystrokes, and install the serial agent. No manual steps required.

TEMPLE_OS_VM_DIR points to where the VM files live (disk image, sockets). Each project can use its own VM by pointing to a different directory, or share a VM by pointing to the same one. TEMPLE_OS_GUI=1 opens the QEMU window so you can watch TempleOS respond live as the AI works.

Your HolyC source files live in your project repo. The MCP server code lives in temple-os-claude. They connect via the serial socket.

Configuration

Claude Code (MCP)

The repo ships with a .mcp.json that configures the MCP server automatically. Open the project in Claude Code and it will pick up the server on start.

If you need to configure it from a different project, add this to that project's .mcp.json (see Starting a new project for details).

Tools

This exposes 24 tools to the AI agent:

Tool	Description
`temple_exec`	Execute HolyC code, return output
`temple_exec_file`	Upload and run a .HC file from host
`temple_exec_bg`	Execute HolyC code without waiting (for graphics/animation)
`temple_exec_file_bg`	Upload and run a .HC file without waiting
`temple_screenshot`	Capture VM display as image
`temple_upload_file`	Upload any file from host to TempleOS (auto-chunks, base64)
`temple_read_file`	Read a file from TempleOS filesystem
`temple_write_file`	Write a file to TempleOS filesystem
`temple_list_dir`	List directory contents
`temple_delete_file`	Delete a file
`temple_system_info`	OS info (uptime, cores)
`temple_send_key`	Send keystroke via QEMU
`temple_mouse_click`	Click at absolute screen coordinates (640x480)
`temple_ping`	Check agent is responding
`temple_reference`	Programming reference (7 topic documents)
`temple_vm_create`	Create VM directory and disk image
`temple_vm_download_iso`	Download the TempleOS ISO
`temple_vm_boot_iso`	Boot from TempleOS ISO for installation
`temple_vm_install_agent`	Install serial agent to disk
`temple_vm_start`	Start the VM
`temple_vm_stop`	Stop the VM
`temple_vm_status`	Check VM status
`temple_vm_restart`	Stop, start, and wait for agent (full boot cycle)
`temple_vm_reinstall_agent`	Stop, reinstall agent, start, wait for agent

CLI

uv run temple exec 'Print("Hello from TempleOS!\n");' # run inline HolyC
uv run temple exec-file src/demo/Mandelbrot.HC        # run a .HC file
uv run temple screenshot tmp/screen.png               # capture the display
uv run temple ping                                    # check agent is alive
uv run temple start                                   # start VM
uv run temple stop                                    # stop VM

Snapshots

./scripts/vm.sh snapshot my-snapshot
./scripts/vm.sh restore my-snapshot   # VM must be stopped

Environment Variables

Variable	Description
`TEMPLE_OS_VM_DIR`	Path to the VM directory containing `disk/` and `sockets/` (default: `<project>/vm`)
`TEMPLE_OS_GUI`	Set to `1` to always open the QEMU window (default: headless)
`TEMPLE_OS_PROJECT_DIR`	Override project root path (default: auto-detected from `pyproject.toml`)

Project Structure

temple-os-claude/
  temple_os_mcp/
    server.py  MCP server (24 tools)
    bridge.py  Python API for serial + VM management
    cli.py     CLI entry point
  docs/
    templeos-setup.md         VM setup guide (new project walkthrough)
    holyc-language.md         HolyC syntax, types, operators, quirks
    templeos-graphics.md      CDC, drawing primitives, 3D transforms, sprites, shading
    templeos-doldoc.md        DolDoc commands, widgets, forms, popups, links
    templeos-system.md        memory, files, tasks, input, math, sound, time
    templeos-patterns.md      working code examples (games, animation, menus, controls)
    templeos-architecture.md  OS design, scheduler, interrupts, boot, debugging
  scripts/
    vm.sh             QEMU VM lifecycle (create/install/setup/run/stop)
    install_agent.sh  writes agent to TempleOS disk via mtools
  src/
    agent/
      SerialAgent.HC  serial agent that runs on TempleOS (command loop)
    demo/
      Hello.HC        text output and basic sanity check
      Mandelbrot.HC   Mandelbrot fractal renderer (2D pixel graphics)
      Cube.HC         solid filled 3D cube with painter's algorithm and black edges
      Teapot/         Utah teapot OBJ loaded and parsed in HolyC, solid 3D rendered
      DolDoc.HC       DolDoc document system: colors, trees, links, popup menus
      Sound.HC        PC speaker: raw tones, Play() notation, sweeps, melodies
      FileIO.HC       file read/write, directory listing, block-level I/O
      Multicore.HC    parallel computation with JobQue across CPU cores
      Sprites.HC      programmatic bitmap sprites, GrBlot animation, ROP_COLLISION
      Assembly.HC     inline x86_64 assembly: registers, RDTSC, CPUID, port I/O
      Tasks.HC        spawning child tasks, DeathWait, shared memory, suspend/resume
      Registry.HC     persistent state across reboots with RegDft/RegExe/RegWrite
      WebFetch.HC     fetch a web page from TempleOS via serial bridge HTTP proxy
      WebServer.HC    serve TempleOS-generated HTML on the host via serial bridge
  vm/
    iso/      TempleOS ISO (gitignored)
    disk/     QEMU disk images (gitignored)
    sockets/  runtime unix sockets (gitignored)

Demos

Mandelbrot

3D Cube

Utah Teapot

File Transfer

All file writes to TempleOS are base64-encoded automatically. This means any file type works -- HolyC source, OBJ meshes, binary data. The temple_upload_file tool handles large files by chunking into 1KB segments (each base64-encoded separately). The agent decodes on the TempleOS side before writing to disk.

uv run temple exec-file src/demo/Hello.HC               # upload + run a .HC file

From an MCP client, temple_upload_file("path/to/model.obj", "C:/Home/model.obj") uploads any file.

Web Connectivity

TempleOS has no networking stack. The serial bridge provides HTTP connectivity by proxying requests through the host:

Fetching -- HolyC code calls WebGet(url) which sends a FETCH sub-request over serial. The Python bridge performs the HTTP GET and returns the content. See src/demo/WebFetch.HC.

Serving -- HolyC code generates HTML and calls WebServe(port, html) which sends a SERVE sub-request. The bridge starts an HTTP server on the host. See src/demo/WebServer.HC.

These functions are defined inline in the demo files (not built into the agent) since they use the agent's serial I/O functions from the parent scope.

Limitations

Graphics programs block the agent. Programs with infinite draw loops (like the Cube or Teapot demos) prevent the agent from responding to serial commands. Use temple_send_key("esc") to exit them, then wait for the agent to recover.
Output capture is limited to 64KB per EXEC call. Larger output is silently truncated.
The VM runs 4 CPU cores by default. TempleOS uses cooperative multitasking with a master/slave core model -- only Core 0 tasks have windows.
PC speaker audio requires PulseAudio on the host. The VM is configured with -machine pcspk-audiodev=snd0 for speaker emulation.

Troubleshooting

Agent stops responding

TempleOS may have crashed. Stop and restart:

./scripts/vm.sh stop
./scripts/vm.sh run --gui

VM won't start (socket errors)

Stale socket files may exist from a previous crash. Stop the VM and clean up:

./scripts/vm.sh stop
rm -f vm/sockets/*.sock vm/temple.pid
./scripts/vm.sh start

Interactive debugging

Connect directly to the QEMU monitor or serial port:

./scripts/vm.sh monitor  # QEMU monitor (type 'help' for commands)
./scripts/vm.sh serial   # raw serial connection to TempleOS

Serial Protocol

Communication between host and agent uses STX (0x02) / ETX (0x03) framed messages.

Commands (host -> agent)

PING                        -> PONG
EXEC\n<holyc code>          -> OK\n<output>        | ERR\n<message>
READ\n<path>                -> OK\n<file content>  | ERR\n<message>
WRITE\n<path>\n<base64>     -> OK                  | ERR\n<message>
APPEND\n<path>\n<base64>    -> OK                  | ERR\n<message>
DIR\n<path>                 -> OK\n<listing>       | ERR\n<message>
DEL\n<path>                 -> OK                  | ERR\n<message>
CLICK\n<x>\n<y>             -> OK                  (sets ms.pos, simulates left click)
INFO                        -> OK\n<key=value lines>
RDY                         (sent once on agent startup)

WRITE and APPEND content is base64-encoded by the host and decoded by the agent before writing to disk.

Sub-requests (agent -> host, during EXEC)

Running HolyC code can send sub-requests back to the host mid-execution. The bridge handles these transparently before returning the EXEC response:

FETCH\n<url>                -> <response body>      (bridge fetches URL)
SERVE\n<port>\n<html>       -> OK: serving on ...   (bridge starts HTTP server)
SERVE_STOP                  -> OK: server stopped   (bridge stops HTTP server)

References

TempleOS -- official site
TempleOS source code -- full OS source
TempleOS wiki -- community documentation
MCP specification -- Model Context Protocol

Navigation Menu

Repository navigation

About

Repository files navigation

temple-os-mcp

How It Works

Prerequisites

Setup

1. Clone and install

2. Create disk image and install TempleOS

3. First-boot setup

4. Start the VM

Using an existing TempleOS VM

Starting a new project

Configuration

Claude Code (MCP)

Tools

CLI

Snapshots

Environment Variables

Project Structure

Demos

Mandelbrot

3D Cube

Utah Teapot

File Transfer

Web Connectivity

Limitations

Troubleshooting

Serial Protocol

Commands (host -> agent)

Sub-requests (agent -> host, during EXEC)

References

About

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
docs		docs
images		images
scripts		scripts
src		src
temple_os_mcp		temple_os_mcp
.gitignore		.gitignore
.mcp.json		.mcp.json
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

temple-os-mcp

How It Works

Prerequisites

Setup

1. Clone and install

2. Create disk image and install TempleOS

3. First-boot setup

4. Start the VM

Using an existing TempleOS VM

Starting a new project

Configuration

Claude Code (MCP)

Tools

CLI

Snapshots

Environment Variables

Project Structure

Demos

Mandelbrot

3D Cube

Utah Teapot

File Transfer

Web Connectivity

Limitations

Troubleshooting

Serial Protocol

Commands (host -> agent)

Sub-requests (agent -> host, during EXEC)

References

About

Topics

Resources

Stars

Watchers

Forks

Used by

Contributors

Languages