DOSCODE is a retro AI coding agent for real DOS machines. It is inspired by modern terminal coding agents, but the client is built for MS-DOS, FreeDOS, DOSBox, and 8086/286/386/486/Pentium-era hardware.
The goal is simple: feel like a fast 1994 hacker tool that can talk to modern LLMs through a serial cable.
DOSCODE has two parts:
MS-DOS client <--- plain text serial ---> modern Python proxy <--- HTTPS ---> LLM provider
Location: client/
The DOS client is written in QuickBasic/QBasic-style BASIC and is responsible for the local experience:
- 80x25 text UI using
SCREEN 0 - CP437-style boxes and ANSI-era colors
- fixed input line at the bottom
- streamed chat area above the prompt
- local commands
- file reads and writes
- confirmed DOS command execution
- plain text serial communication over
COM1/COM2
The DOS client deliberately avoids HTTPS, TLS, heavy JSON, and modern runtime dependencies.
To build the DOS client, you need QuickBasic 4.5 compiler tools such as
BC.EXE and LINK.EXE. These tools are not included with MS-DOS, FreeDOS, or
DOSBox; they must be installed separately in the DOS environment. See
docs/build.md for the full build and DOSBox notes.
Location: proxy/
The proxy is written in Python 3 and runs on Linux, Windows, macOS, or a Raspberry Pi. It handles modern networking and provider APIs:
- OpenAI-compatible chat completions
- Claude Messages API
- OpenRouter
- Ollama
- serial transport through
pyserial - local development over
stdio - progressive line-by-line streaming to the DOS client
The current MVP implements the first target milestone:
- opens the DOS TUI
- draws a retro 80x25 frame
- connects to
COM1 - sends prompts to the proxy
- receives streamed
LINE ...responses - displays AI responses progressively
- supports
/read,/run,/model,/clear,/help, and/exit - includes parser hooks for
<READ>,<WRITE>, and<RUN>tool actions - asks for confirmation before
RUN
The next milestones are richer history, diff navigation, undo state, file
browser navigation, and fully automated multi-line <WRITE> application.
The client targets an 80x25 text screen:
┌ DOSCODE ───────────────────────────────────────────────────────────────────┐
│ model: claude-3-5-haiku path: C:\WORK │
├────────────────────────────────────────────────────────────────────────────┤
│ AI > DOSCODE ready. Proxy expected on COM1. Press F1 for help. │
│ You > fix BUILD.BAT │
│ AI > analyzing request... │
│ ◆ READ BUILD.BAT │
│ ✓ read 28 lines │
├────────────────────────────────────────────────────────────────────────────┤
│ > _ │
│ F1 Help F2 Files F3 Retry F4 Clear F5 Model TAB Commands │
└────────────────────────────────────────────────────────────────────────────┘
Colors are classic DOS colors:
- black background
- gray normal text
- green AI text
- yellow user text
- cyan titles
- red errors
- magenta actions
Implemented or reserved commands:
/help
/clear
/history
/model MODEL_NAME
/exit
/read FILE
/write FILE
/run COMMAND
/fix FILE
/explain FILE
/plan TASK
/apply
/diff
/undo
Examples:
/read AUTOEXEC.BAT
/run DIR
/fix CONFIG.SYS
/run always asks for confirmation on the DOS side before executing a command.
The protocol is line-oriented text. It is intentionally simple enough for DOS:
Client to proxy:
PROMPT 24
fix BUILD.BAT
Proxy to client:
LINE I will inspect the file
LINE <READ path="BUILD.BAT">
LINE found a bad PATH entry
LINE <WRITE path="BUILD.BAT">
END
See docs/protocol.md for details.
- MS-DOS, FreeDOS, or DOSBox
- QuickBasic 4.5 toolchain for building (
BC.EXEandLINK.EXE) - 640 KB conventional-memory target
SCREEN 0text mode- serial connection mapped to
COM1orCOM2
- Python 3.10+
pyserialwhen using a real serial port- network access for hosted LLM providers
- provider API key when required
Install proxy dependencies:
python3 -m pip install -r proxy/requirements.txtEnvironment variables:
LLM_PROVIDER=openai|claude|openrouter|ollama|mock
LLM_MODEL=claude-3-5-haiku-20241022
LLM_API_KEY=your-api-key
LLM_BASE_URL=optional-compatible-base-url
SERIAL_PORT=/dev/ttyUSB0 or COM3 or stdio or /tmp/pty_proxy
SERIAL_BAUD=9600
If LLM_MODEL is not set, the proxy picks a sensible per-provider default
(e.g. claude-3-5-haiku-20241022 for claude, gpt-4o-mini for openai).
For local development without serial hardware, use the mock provider and stdio:
cd proxy
LLM_PROVIDER=mock SERIAL_PORT=stdio python3 server.pyThen type a protocol frame manually:
PROMPT 15
/read BUILD.BAT
DOSBox cannot open an arbitrary host PTY through directserial realport:.
The validated setup uses socat to bridge a PTY to a TCP port and configures
DOSBox as a nullmodem TCP client:
# Terminal 1 — PTY <-> TCP bridge
socat -d -d pty,raw,echo=0,link=/tmp/pty_proxy TCP-LISTEN:2323,reuseaddr,fork &
# Terminal 2 — proxy talks to the PTY
cd proxy
python3 server.py --serial-port /tmp/pty_proxy --baud 9600In dosbox.conf:
[serial]
serial1=nullmodem server:localhost port:2323 transparent:1 rxdelay:100
serial2=dummyThe DOS client then talks to the proxy through COM1. See docs/build.md
for details and docs/scripts.md for monitor_serial.sh, which can tap the
traffic between DOSBox and the proxy.
Inside DOS, FreeDOS, or DOSBox with QuickBasic tools in PATH:
CD CLIENT
BUILD.BAT
RUN.BATSee docs/build.md for DOSBox and serial-port notes.
Helper scripts for development and debugging live in scripts/.
- Taps serial traffic between the proxy and DOSBox in real time using
socat - Prints each frame to the terminal with a direction label
- Saves logs to
/tmp/doscode_monitor/ - Requires
socat- macOS:
brew install socat - Debian/Ubuntu:
apt install socat
- macOS:
- Creates symlinks from a DOSBox-mounted directory to the
client/source files - DOSBox always sees the latest version without manual copying
- No external dependencies
See docs/scripts.md for full usage instructions, DOSBox
configuration, and baud-rate alignment notes.
client/
doscode.bas
ui.bas
serial.bas
parser.bas
files.bas
BUILD.BAT
RUN.BAT
proxy/
server.py
llm.py
protocol.py
requirements.txt
scripts/
monitor_serial.sh
link_dosbox_project.sh
docs/
protocol.md
build.md
scripts.md
README.md
AGENTS.md
LICENSE
DOSCODE is distributed under the Apache License 2.0. See LICENSE.