Ricapar/ClawDOS

ClawDOS

ClawDOS Roadmap

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.

Target hardware

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

Software stack

Claude chat architecture

 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.

Milestones

Benchmark

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.

Baseline (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.

The frozen prefix and buffered history (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.

Message threads (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).

Memory for in-harness runs (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).

M6.2: full-memory run

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:

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):

  1. Exit and relaunch through a stub. A tiny resident launcher (NASM, 8086, a few KB; e.g. CLAWDOS.COM, which the user starts instead of CLAWDOS) runs HARNESS.EXE. For a big run CLAWDOS saves its state (conversation file, pending tool id, flags like -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.
  2. Swap CLAWDOS out to EMS. Like Ralf Brown’s SPAWNO: copy CLAWDOS’s memory into EMS pages (PicoMEM offers up to 4 MB), shrink to a small stub, exec, copy back. No reload, but every hooked vector (INT 10h capture, 1Bh/23h Ctrl-Break, the packet driver’s receive upcall into mTCP) must be unhooked first and the packet driver released and re-acquired; the TCP connection still dies while the receiver is gone. Needs EMS (none in 86Box’s IBM PC 5160 unless an EMS board is emulated); a disk swap file would be the fallback.

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.

Memory for in-harness runs (2026-11-11)

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:

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.

Repo layout

See the README.