A DOS-based foundation for building apps on a real IBM 5160 that reach the modern world. First flagship demo: a Claude chat client that is the whole harness, running on the 8088.
| Component | Detail |
|---|---|
| CPU | Intel 8088 @ 4.77 MHz (8086 instruction set only) |
| RAM | 640 KB conventional |
| Video | IBM CGA (text 80x25 @ B800:0000, 320x200x4, 640x200x2) |
| Storage | PicoMEM disk emulation: raw .IMG files in HDD/ on its microSD |
| Network | PicoMEM v1.1 (FreddyV) — Pico W NE2000 emulation over WiFi, default I/O 300h, IRQ 3; also EMS (LoTech-compatible, up to 4 MB) and disk-image emulation |
| Other | Unidentified ISA cards — TBD |
wcl -0 for 8088 code), NASM for hand-written asm.PM2000 0x60 (NE2000 over WiFi, auto-detected);
Crynwr NE1000/NE2000 at 340h in emulators. DOS PC (HARNESS.EXE) --plain HTTP over TCP--> TLS tunnel --HTTPS--> Claude API
CGA text UI, scrollback, mTCP, (tunnel.py, socat
Messages API requests, SSE + JSON, or stunnel: copies
history on disk, API key, tools bytes, nothing else)
Why a tunnel: the Claude API requires TLS 1.2+. An 8088 at 4.77 MHz could in principle do the handshake, but it would take minutes and need lots of RAM for certificates and crypto state. Everything else, from building the request to parsing the streamed reply and keeping the history, the PC does itself. The tunnel has no knowledge of the API, so native TLS (BearSSL’s i15 big-number code is written for 16-bit multipliers) or a tunnel inside the PicoMEM firmware could replace it later without touching CLAWDOS. What CLAWDOS sends and expects is in API.md.
scripts/build.py makes a FreeDOS 1.4 HDD image
(16 heads x 63 sectors, as PicoMEM expects) with our own MBR, the 8086
FreeDOS kernel, DOS tools, mTCP and the PicoMEM drivers. Boots in DOSBox-X
(scripts/boottest.py) and on an 8088 PC in 86Box.NETUP.BAT loads PM2000 on a PicoMEM, or
Crynwr NE1000/NE2000 at 340h in emulators, then DHCP. Works in 86Box.bridge/dosbridge.py spoke
the API for the DOS PC and relayed tool calls over a line protocol. Replaced
by M5.5; its offline mock lives on as tunnel/mockapi.py.tunnel/tunnel.py, or socat/stunnel): request
writer, SSE and JSON parsing, thinking blocks echoed back, the tool loop,
the history as a file on the DOS PC, retries and lost-link recovery,
/model across providers that speak the API. The Python bridge is gone.
First live run (86Box 8088, 2026-10-31, before buffered upload in
766f1f8, so no longer what the code does): a fresh conversation’s first
request (11.7 KB up: prompt, tool schemas, one message) reached the first
token after 19 s and finished at 21 s, with the system prompt and tools
served from the prompt cache on the second run (cr=4061). Current
figures, up to a 135 KB request: Benchmark.edit (replace text in a file instead of
rewriting all of it: 49 whole-file writes of up to 5.4 KB happened),
search (grep with line numbers inside CLAWDOS: FIND took 10-79 s a
call), run with a list of commands that stops at the first failure
(FreeCOM has no &/&&; each TCC call was its own tool call), and a
clock (every file on the DOS PC was dated 1980-01-01). The clock first
came from the API’s Date header; since 2026-11 the boot scripts own it:
the PicoMEM 2’s battery clock (ASTCLOCK) and SNTP in NETUP.BAT, which
failed before on DNS and mTCP’s DHCP lease check.full_memory gives them
446K and an in-harness run 247K; the goal of ~560K is not met, so this
stays open. See M6.2 below.run
takes screenshot (the screen as the last program left it, taken
before the chat comes back) or shot_at (seconds after the first
command starts, copied from the timer interrupt into a 16 KB DOS
block that exists for that run only, in the harness and the launcher
alike, never an EMS page a program could have mapped over, for
programs that set text mode again on exit). The mode comes from the BIOS data area (mode,
mode and colour register shadows) unless shot_mode / shot_color
say otherwise. The PC makes the PNG itself (indexed, rows taken from
both CGA banks, one stored deflate block, CRC-32 and Adler-32: about
16 KB, 22 KB as base64) and the tool_result carries it as an image
block after the text. Through the launcher the screen goes to the
resumed harness in SHOT.RAW, so the encoder stays out of CLAWDOS.EXE.
A raster effect that changes registers mid-frame cannot be captured
faithfully. Before this, 13 demo runs came back as “(screen text)”;
fixes were “best guess, untested visually”.snapshot/restore tools on the DOS PC
replace hand-made copies (XCOPY C:\WG C:\WG3 took 43 s); the
conversation files in C:\CLAWDOS\CHATS already record what was written.lib/ (input line editor, windows/menus, the
HTTP client for other web APIs through the same tunnel) and a launcher for
ClawDOS apps.python3 scripts/bench.py (make bench, about six minutes since e90da2f) runs
image/tests/bench.bat in 86Box against the mock API: the mock’s !bench has
CLAWDOS.EXE do 20 reads of a 4 KB file, one run of VER with
full_memory (a real relaunch) and a 3.9 KB reply. Per round: gap the
seconds since the previous round ended (the tool call, its result written to
the history; at the baseline also the request’s length counted, a pass now
gone), len the request body, up the
time to send it, ttft-up the wait for the (mock) API, total the round.
The baseline was taken 2026-11-10 at f521559, 86Box IBM PC 5160 (8088 4.77
MHz, NE1000 on SLiRP). Later changes rerun it and compare; the scenario and the
format stay.
f521559)| round | gap s | len | up ms | up KB/s | ttft-up ms | total ms |
|---|---|---|---|---|---|---|
| 0 | - | 12926 | 2530 | 5.0 | 1210 | 4235 |
| 1 | 67 | 19063 | 2970 | 6.3 | 1100 | 4620 |
| 2 | 68 | 25200 | 3355 | 7.3 | 1100 | 5005 |
| 3 | 69 | 31337 | 3630 | 8.4 | 1155 | 5335 |
| 4 | 68 | 37474 | 4070 | 9.0 | 1155 | 5775 |
| 5 | 69 | 43613 | 4565 | 9.3 | 1100 | 6215 |
| 6 | 68 | 49752 | 4950 | 9.8 | 1155 | 6655 |
| 7 | 69 | 55891 | 5225 | 10.4 | 1155 | 6985 |
| 8 | 69 | 62030 | 5610 | 10.8 | 1155 | 7370 |
| 9 | 69 | 68169 | 6050 | 11.0 | 1155 | 7810 |
| 10 | 70 | 74309 | 6435 | 11.3 | 1155 | 8195 |
| 11 | 69 | 80449 | 6875 | 11.4 | 1210 | 8635 |
| 12 | 69 | 86589 | 7205 | 11.7 | 1155 | 8965 |
| 13 | 71 | 92729 | 7645 | 11.8 | 1210 | 9405 |
| 14 | 69 | 98869 | 8030 | 12.0 | 1210 | 9845 |
| 15 | 71 | 105009 | 8470 | 12.1 | 1100 | 10175 |
| 16 | 70 | 111149 | 8800 | 12.3 | 1210 | 10615 |
| 17 | 71 | 117289 | 9240 | 12.4 | 1210 | 11000 |
| 18 | 71 | 123429 | 9680 | 12.5 | 1155 | 11440 |
| 19 | 70 | 129569 | 10065 | 12.6 | 1155 | 11825 |
| 20 | 72 | 135709 | 10395 | 12.7 | 1155 | 12155 |
| 21 | 32 | 137848 | 10945 | 12.3 | 1210 | 33880 |
| all | 1698402 | 146740 | 11.3 | 206140 |
The turn took 1627 s from the first request to the last reply.
Final round: 3948 characters streamed in 21725 ms after the first, 182 characters/s (stop=end_turn). Relaunch round trip: program 3.1 s, CLAWDOS away 25.7 s. Stack: used 1347 of 4027 bytes; used 1557 of 4055 bytes (one line per HARNESS.EXE).
Upload runs at 5 KB/s for the first request and 12-13 KB/s for big ones, so
the 136 KB request of round 20 takes 10 s before the API sees it. The biggest
cost is outside the requests, though: about 68 s per read round (the run
round, with a short result, has ~6 s besides the relaunch), most likely the
4 KB tool_result going into the history a character at a time
(json_escape_cp437 into hist_write, an lseek and a write per
character). The stack never came within 2.4 KB of its end.
e90da2f, 2026-11-11)| round | gap s | len | up ms | up KB/s | ttft-up ms | total ms |
|---|---|---|---|---|---|---|
| 0 | - | 11790 | 715 | 16.1 | 990 | 2090 |
| 1 | 2 | 17895 | 1045 | 16.7 | 990 | 2530 |
| 2 | 2 | 24000 | 1375 | 17.0 | 990 | 2805 |
| 3 | 3 | 30105 | 1650 | 17.8 | 990 | 3080 |
| 4 | 3 | 36210 | 1925 | 18.4 | 990 | 3410 |
| 5 | 2 | 42317 | 2200 | 18.8 | 990 | 3685 |
| 6 | 2 | 48424 | 2475 | 19.1 | 990 | 3905 |
| 7 | 3 | 54531 | 2750 | 19.4 | 990 | 4180 |
| 8 | 2 | 60638 | 3135 | 18.9 | 935 | 4565 |
| 9 | 3 | 66745 | 3410 | 19.1 | 990 | 4840 |
| 10 | 2 | 72853 | 3630 | 19.6 | 990 | 5115 |
| 11 | 2 | 78961 | 4015 | 19.2 | 1045 | 5500 |
| 12 | 3 | 85069 | 4345 | 19.1 | 990 | 7315 |
| 13 | 3 | 91177 | 4620 | 19.3 | 1045 | 6050 |
| 14 | 3 | 97285 | 4950 | 19.2 | 990 | 6435 |
| 15 | 2 | 103393 | 5170 | 19.5 | 990 | 6600 |
| 16 | 3 | 109501 | 5555 | 19.3 | 990 | 6985 |
| 17 | 3 | 115609 | 5775 | 19.5 | 1045 | 7260 |
| 18 | 2 | 121717 | 6105 | 19.5 | 990 | 7590 |
| 19 | 2 | 127825 | 6435 | 19.4 | 990 | 7920 |
| 20 | 3 | 133933 | 6655 | 19.7 | 990 | 8140 |
| 21 | 24 | 136072 | 6820 | 19.5 | 990 | 25630 |
| all | 1666050 | 84755 | 19.2 | 135630 |
The turn took 211 s from the first request to the last reply.
Final round: 3948 characters streamed in 17820 ms after the first, 222 characters/s (stop=end_turn). Relaunch round trip: program 2.1 s, CLAWDOS away 23.5 s. Stack: used 1379 of 4027 bytes; used 1565 of 4055 bytes (one line per HARNESS.EXE).
The turn takes 211 s instead of 1,627 s. Nearly all of it is the gap between
rounds, down from about 68 s to 2-3 s: a 4 KB tool result now reaches the
history in three 2 KB writes instead of about 4,000 seeks and writes, and the
request is written once, with its length added up from known sizes, instead
of being read through twice. Upload rose from 12-13 KB/s to 19-20 KB/s (the
136 KB request takes 6.8 s instead of 10.4 s), since the body is read from
disk 2 KB at a time and PROMPT.TXT is no longer escaped a byte at a time on
every request. Each request is about 1.1 KB shorter than at the baseline,
because of changes made between the two runs (TOOLS.JSN minified in the
image, whole-line results with a trailer), not this one. ttft-up is about
990 ms against 1,100-1,210 ms: 50 ms of that is the mock, which no longer
waits before it answers; the rest is unexplained. The final round streams at
222 characters/s (182 before), most likely because the reply’s deltas now go
to the history through the buffer instead of a seek and a write each.
21e4a9c, 2026-11-11)| round | gap s | len | up ms | up KB/s | ttft-up ms | total ms |
|---|---|---|---|---|---|---|
| 0 | - | 11926 | 715 | 16.3 | 1045 | 2200 |
| 1 | 3 | 4537 | 330 | 13.4 | 990 | 1815 |
| 2 | 2 | 4537 | 275 | 16.1 | 990 | 1760 |
| 3 | 3 | 4537 | 330 | 13.4 | 990 | 1815 |
| 4 | 2 | 4537 | 330 | 13.4 | 990 | 1815 |
| 5 | 2 | 4538 | 275 | 16.1 | 1045 | 1815 |
| 6 | 3 | 4539 | 275 | 16.1 | 990 | 1760 |
| 7 | 2 | 4539 | 330 | 13.4 | 1045 | 1870 |
| 8 | 3 | 4539 | 330 | 13.4 | 990 | 1870 |
| 9 | 2 | 4539 | 330 | 13.4 | 1045 | 1870 |
| 10 | 2 | 4539 | 385 | 11.5 | 935 | 1870 |
| 11 | 3 | 4539 | 385 | 11.5 | 990 | 1870 |
| 12 | 2 | 4539 | 385 | 11.5 | 990 | 1870 |
| 13 | 3 | 4539 | 385 | 11.5 | 990 | 1870 |
| 14 | 2 | 4539 | 385 | 11.5 | 990 | 1870 |
| 15 | 3 | 4539 | 385 | 11.5 | 1045 | 1925 |
| 16 | 2 | 4539 | 330 | 13.4 | 1045 | 1870 |
| 17 | 3 | 4539 | 440 | 10.1 | 990 | 1925 |
| 18 | 3 | 4539 | 440 | 10.1 | 1045 | 1980 |
| 19 | 2 | 4539 | 385 | 11.5 | 1045 | 1925 |
| 20 | 3 | 4539 | 385 | 11.5 | 990 | 1870 |
| 21 | 25 | 572 | 55 | 10.2 | 1045 | 19030 |
| all | 103269 | 7865 | 12.8 | 58465 |
The turn took 136 s from the first request to the last reply.
Final round: 3948 characters streamed in 17930 ms after the first, 220 characters/s (stop=end_turn). Relaunch round trip: program 2.0 s, CLAWDOS away 24.0 s. Stack: used 1443 of 4027 bytes; used 1615 of 4055 bytes (one line per HARNESS.EXE).
The turn takes 136 s instead of 211 s, and len stays flat: after the
11.9 KB create of round 0, every read round sends 4.5 KB (its 4 KB tool
result and the fixed fields, no system, no tools, no earlier messages)
where it grew from 17.9 KB to 133.9 KB before; the round after the
full_memory relaunch is a 572-byte continue carried over in RESUME.TXT, not
a 136 KB replay. In all 103 KB go up instead of 1,666 KB, and upload time
falls from 84.8 s to 7.9 s. The gaps between rounds (2-3 s: the tool call and
its result written) and the wait for the mock (~1 s) are unchanged, so they
are now most of a round; small requests upload at 10-16 KB/s, below the
19-20 KB/s of big ones, since the fixed costs of a request weigh more. The
final round and the relaunch are as before. The stack peak rose by about 50
bytes (1,615 of 4,055).
6f17e97, 2026-11-11)| round | gap s | len | up ms | up KB/s | ttft-up ms | total ms |
|---|---|---|---|---|---|---|
| 0 | - | 14239 | 880 | 15.8 | 990 | 2310 |
| 1 | 2 | 4537 | 330 | 13.4 | 990 | 1815 |
| 2 | 2 | 4537 | 275 | 16.1 | 990 | 1760 |
| 3 | 3 | 4537 | 275 | 16.1 | 990 | 1815 |
| 4 | 2 | 4537 | 275 | 16.1 | 1045 | 1815 |
| 5 | 3 | 4538 | 275 | 16.1 | 1045 | 1815 |
| 6 | 2 | 4539 | 330 | 13.4 | 990 | 1815 |
| 7 | 3 | 4539 | 330 | 13.4 | 1045 | 1870 |
| 8 | 2 | 4539 | 330 | 13.4 | 1045 | 1870 |
| 9 | 3 | 4539 | 330 | 13.4 | 990 | 1870 |
| 10 | 2 | 4539 | 330 | 13.4 | 990 | 1815 |
| 11 | 2 | 4539 | 330 | 13.4 | 1045 | 1870 |
| 12 | 3 | 4539 | 330 | 13.4 | 1045 | 1870 |
| 13 | 2 | 4539 | 330 | 13.4 | 990 | 1815 |
| 14 | 3 | 4539 | 330 | 13.4 | 1045 | 1870 |
| 15 | 2 | 4539 | 385 | 11.5 | 1045 | 1925 |
| 16 | 3 | 4539 | 385 | 11.5 | 1045 | 1925 |
| 17 | 3 | 4539 | 385 | 11.5 | 1045 | 1925 |
| 18 | 2 | 4539 | 385 | 11.5 | 1045 | 1925 |
| 19 | 3 | 4539 | 385 | 11.5 | 990 | 1925 |
| 20 | 2 | 4539 | 385 | 11.5 | 1045 | 1925 |
| 21 | 27 | 572 | 55 | 10.2 | 1045 | 18975 |
| all | 105582 | 7645 | 13.5 | 58520 |
The turn took 137 s from the first request to the last reply.
Final round: 3948 characters streamed in 17875 ms after the first, 221 characters/s (stop=end_turn). Relaunch round trip: program 2.1 s, CLAWDOS away 25.4 s. Stack: used 1497 of 4027 bytes; used 1629 of 4055 bytes (one line per HARNESS.EXE).
Nothing slowed down: 137 s against 136 s, the same per-round gaps, uploads
and waits; the relaunch’s 25.4 s is inside the 23.5-25.7 s the earlier tables
show. The bench’s one run is a full_memory relaunch, so the lending around
an in-harness run (two DOS calls and a heap trim, M6.2)
is not in it; the harness’s startup trim of its near heap and the buffers’
new home are. Round 0 is 2.3 KB longer than in 21e4a9c because TOOLS.JSN
grew (the screenshot arguments, and the memory notes of 65df948). The stack peak
is 1,629 bytes (1,615 before).
Problem (as of 2026-10). HARNESS.EXE stays resident while the run tool’s program runs:
about 355 KB of it (mTCP and its buffers, the chat, the heap), leaving ~285 KB
(Stage 1 memory, dc21363, already won ~90 KB). On the DOS PC this cost:
time.h/stdlib.h and on big functions; Claude wrote
its own tiny DOS.H and an empty STDLIB.H (C:\TESTS\DEV) to get by, and once
compiled with “Available memory 0”.Goal (not met: full_memory gives 446K, see the table below). A program run starts has at least ~560 KB free, so stock Turbo C
compiles with its own headers, spawns TLINK itself, and Turbo C’s MAKE.EXE
(already on the image in C:\TC) can drive builds. CLAWDOS comes back afterwards
on the same conversation with the program’s output as the tool result, the chat
screen as it was, and the link restored.
Approaches (pick one in the design session):
-unsafe, the scrollback/screen, the input
line), shuts mTCP down cleanly (releasing the packet driver) and exits
with a code that tells the stub to run the command. The stub runs it with
output capture (the INT 10h hook moves into the stub), writes the output,
then runs CLAWDOS again in resume mode. No vectors point into freed memory,
because CLAWDOS really exits. Costs a reload of the ~120 KB EXE and a
reconnect (a few seconds) per big run.Status (branch relaunch, a spike of approach 1). The chat client is now
HARNESS.EXE, and CLAWDOS.EXE (src/clawdos, a small-model C program linking
lib/shell.c) is the launcher the user types: it starts HARNESS with -launched;
the run tool then writes the commands to C:\CLAWDOS\RUN.TXT and the harness
saves its state (RESUME.TXT: chat file, pending tool_use id, round, convo flags,
switches; SCREEN.SAV: the 16 KB of video memory plus the scroll and console
state) and exits with code 200. The launcher runs the commands exactly as the
in-process tool would, writes RUN.OUT and starts HARNESS -resume, which
reopens the history file, restores the screen, shows the result under the Run
header and continues the rounds (lib/relaunch.h, Chat::resume/continueTurn).
Measured in DOSBox-X in the spike (image/tests/relaunch.bat, 2026-10; today’s
figures are in the table under “Memory for in-harness runs”): a program got 449 KB,
against 220 KB in-process; the launcher’s block was 50 KB; the harness was away
1.7 s for a 1.0 s program. Only a run with full_memory: true goes through
the launcher (the model decides: TOOLS.JSN and DEVTOOLS.TXT say to set it for
compilers, linkers, assemblers, freshly built programs and batch files); the
rest run inside the harness, with no reconnect. HARNESS started on its own
runs everything in-process and tells the model the flag had no effect. The
Up/Down input history travels in SCREEN.SAV. The launcher’s 50 KB was left as
it is: most of it is the output capture’s buffers and the C runtime that
shell.c’s formatting needs. Still to do: timing on the real PC, and building
WarGames with stock headers and MAKE through full_memory.
First live runs on the 86Box 8088 (2026-10-31, before buffered upload; the
relaunch’s current cost is in Benchmark): a 35 s dir /s | find kept
CLAWDOS away 46 s, so a relaunch costs about 11 s there (the 133 KB EXE reloads,
reconnects and reopens the history); TCC -c VOYAGER.C reported “Available
memory 215298” and TLINK ran, where the in-process run had no room. Two faults
came out of it, both fixed: the resumed CLAWDOS failed mTCP’s DHCP lease check
once the clock had been set from the API (DHCP had stamped the lease with the
1980 boot clock; fixed then by moving the stamp in MTCP.CFG, and since 2026-11
by NETUP taking a fresh lease after SNTP), and it could draw the local TCP port its predecessor had just
closed, because mTCP’s tick counter starts at 0 in every process (the port now
comes from the BIOS time of day). CLAWDOS -resume retries a resume that failed.
Leaning toward 1: simpler, no EMS dependency, and CLAWDOS’s exit/start paths are already tested. The open questions either way:
Testing. DOSBox-X with --mock: a boottest that has Claude run stock
PRIMES.C with time.h through plain TCC (auto-linked) and checks the
resumed tool result in the mock’s log; a mock !tool for a big run; a check
that a program’s free memory (e.g. MEM) is above the goal. Then the 86Box
8088 (scripts/test8088.py) and the real PC, building WarGames with
stock headers and MAKE.
The runs full_memory leaves inside the harness had fallen to 149K started
directly and 78K through COMMAND.COM (HARNESS.EXE alone, first message, at
9139304; the table below), and a
COMMAND.COM run short of memory hung the PC instead of failing. Now:
tests/unit/eatmem.c, outside the harness) it cannot load its
strings and asks on the keyboard where to find another copy; with standard
input on NUL nobody answers. From about 72K (where EXEC fails cleanly) up to
that it stops there. lib/shell.c now refuses a command that needs
COMMAND.COM with under 100K free and tells the model to set full_memory;
a program started directly that does not fit fails with DOS’s own “Not
enough memory”. The “cliff” for which the launcher’s timed screenshot copy
had once been kept out of EMS (CLAWDOS.EXE grown past a size, the run hanging)
was the same prompt. (The copy has since left EMS for another reason: a
program may map its own pages into the frame the interrupt handler writes.)_fheapshrink). If the block cannot come
back (a program stayed resident), the turn ends after the result.MEM’s largest executable program size from inside a run, DOSBox-X:
| started directly | through COMMAND.COM | |
|---|---|---|
before the threads and screenshots work (7723879), HARNESS.EXE alone |
176K (180,240) | 105K (107,808) |
before this (9139304), HARNESS.EXE alone |
149K (152,528) | 78K (80,096) |
| near heap given back, screen save a DOS block | 169K (173,872) | 99K (101,440) |
| + the API buffers lent | 242K (247,936) | 171K (175,504) |
| + the HTTP, scratch and error buffers lent | 250K (255,872) | 179K (183,440) |
| the same under CLAWDOS.EXE | 198K (202,832) | 127K (130,400) |
| under CLAWDOS.EXE, late in the tool tour | 127K (130,400) | |
full_memory (the launcher alone) |
446K (456,240) | |
after the review fixes (c38ae0b), HARNESS.EXE alone |
247K (253,184) | 176K (180,768) |
| the same under CLAWDOS.EXE | 196K (200,592) | 125K (128,176) |
image/tests/runmem.bat checks these (floors 230K/160K alone, 176K/105K
under the launcher), the refusal and the turn that ends when the memory does
not come back. The lending costs about 165 ms before the commands and 220 ms
after them on the 86Box 8088 (shot8088.bat’s run: line for a plain
in-harness run, 77cce24); the benchmark’s one run is a relaunch, so it is not
in the tables above.
See the README.