{"id":51846084,"url":"https://github.com/wr/apple-ii-terminal-for-claude-code","last_synced_at":"2026-07-23T12:30:28.966Z","repository":{"id":371614222,"uuid":"1295893419","full_name":"wr/apple-ii-terminal-for-claude-code","owner":"wr","description":"A terminal app for Claude Code that runs natively on Apple IIe, IIe+, IIc, and IIgs.","archived":false,"fork":false,"pushed_at":"2026-07-22T22:49:28.000Z","size":5288,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-23T00:24:22.024Z","etag":null,"topics":["6502","65816","ai","apple-ii","apple-iigs","apple2","apple2gs","claude","claude-code","retrocomputing","vintage-computers"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-07-10T00:24:31.000Z","updated_at":"2026-07-22T22:49:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wr/apple-ii-terminal-for-claude-code","commit_stats":null,"previous_names":["wr/apple-ii-terminal-for-claude-code"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/wr/apple-ii-terminal-for-claude-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wr%2Fapple-ii-terminal-for-claude-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wr%2Fapple-ii-terminal-for-claude-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wr%2Fapple-ii-terminal-for-claude-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wr%2Fapple-ii-terminal-for-claude-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wr","download_url":"https://codeload.github.com/wr/apple-ii-terminal-for-claude-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wr%2Fapple-ii-terminal-for-claude-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35802930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["6502","65816","ai","apple-ii","apple-iigs","apple2","apple2gs","claude","claude-code","retrocomputing","vintage-computers"],"created_at":"2026-07-23T12:30:28.306Z","updated_at":"2026-07-23T12:30:28.949Z","avatar_url":"https://github.com/wr.png","language":"Python","funding_links":["https://www.buymeacoffee.com/wellsworkshop","https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee\u0026emoji=%E2%98%95\u0026slug=wellsworkshop\u0026button_colour=FFDD00\u0026font_colour=000000\u0026font_family=Arial\u0026outline_colour=000000\u0026coffee_colour=ffffff"],"categories":[],"sub_categories":[],"readme":"# Apple II Terminal for Claude Code\n\nA real Apple II, as a terminal for Claude Code.\n\n![](docs/demo.gif)\n\n[▶️ Build video](https://www.youtube.com/watch?v=6VsCheEJMIk)\n\nBoot a 140K floppy, dial a WiFi modem, and your Apple II becomes a terminal for the real `claude` CLI, bridged from a modern machine. The disk image is bootable on every model from the IIgs down to the II+ (or in an emulator).\n\nIt's not a chat toy. The backend is the actual agentic Claude Code, and the clients are bare-metal 65816 and 6502 that draw the whole UI themselves from a tiny 7-bit ASCII protocol. A IIgs gets a Super Hi-Res client with an animated splash, scrolling transcript, and thinking spinner; a IIe, IIc, IIc Plus, or II+ gets a text-mode client.\n\nPress Connect and it plays the 1986 dial-up soundscape: dial tone, touch-tones that spell `C-L-A-U-D-E` on the keypad, ring, and answer tone.\n\n\u003ca href=\"https://www.buymeacoffee.com/wellsworkshop\"\u003e\u003cimg src=\"https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee\u0026emoji=%E2%98%95\u0026slug=wellsworkshop\u0026button_colour=FFDD00\u0026font_colour=000000\u0026font_family=Arial\u0026outline_colour=000000\u0026coffee_colour=ffffff\" /\u003e\u003c/a\u003e\n\n## Apple II instructions\n\n### Prerequisites:\n\n1. An Apple II (IIgs down to the II+ — see [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) for the tested-model matrix)\n2. A Hayes-compatible modem (or modem emulator like the [WiModem 232 Pro](https://www.cbmstuff.com/index.php?route=product/product\u0026path=59_66\u0026product_id=113)) OR a serial connection to your modern Mac.\n3. [FloppyEmu](https://www.bigmessowires.com/floppy-emu/) or some way of writing a `.dsk` image to a floppy disk\n4. [Claude Code](https://claude.com/claude-code) installed and logged in on your modern Mac\n5. The **CLAUDE.dsk** disk image, from [Releases](https://github.com/wr/apple-ii-terminal-for-claude-code/releases) (or built from source, below)\n\n### Setup:\n\n1. **Bridge**, on the machine with the `claude` CLI:\n\n   ```sh\n   git clone https://github.com/wr/apple-ii-terminal-for-claude-code\n   cd apple-ii-terminal-for-claude-code\n   python3 ./bridge/bridge.py --telnet --app --backend code --workdir ~/your-project\n   ```\n\n   | Setup | Python install |\n   |---|---|\n   | TCP/emulator + `--backend code` | None; install and log in to the external `claude` CLI |\n   | Serial + `--backend code` | `python3 -m pip install -r bridge/requirements-serial.txt` |\n   | Any transport + `--backend chat` | `python3 -m pip install -r bridge/requirements-chat.txt` and set `ANTHROPIC_API_KEY` |\n   | Every optional bridge feature | `python3 -m pip install -r bridge/requirements.txt` |\n\n   It listens on TCP 6400. When an unpaired source IP first needs access, the bridge creates a 6-character code and prints it only on its own console. A native client exchanges the code for a private token and presents it on later connects. The 8-bit client persists that token on its boot disk across reboots; the IIgs client keeps it only in RAM for the current boot. A valid-token reconnect does not print a code. The generated code is discarded after a successful pairing, but an intercepted unused code can still be replayed from the same source IP. `--workdir` is the project Claude Code works in — in code mode it reads and writes files and runs commands in that directory, so point it at the repo you actually want on the wire.\n\n   \u003e **Trusted LAN only.** `--telnet` exposes a Claude session (in code mode, a shell on the host) to your network. Telnet is plaintext: anyone who captures LAN traffic may be able to replay a pairing code or token. Run it only on a home LAN you trust, and never port-forward it or bind it to a public interface. See [pairing flags](#advanced-bridge-options) to set a shared code or revoke access.\n\n   \u003e **What the bridge records.** Every prompt you type from the Apple II prints to the bridge's own console; replies are logged as metadata, not text. The pairing store records each token's SHA-256, first-seen IP, and pairing time at `$XDG_CONFIG_HOME/claude-ii-terminal/paired.json`, or `~/.config/claude-ii-terminal/paired.json` when XDG is unset. It never stores the plaintext token. The 8-bit client keeps that token on disk; the IIgs client retains it only in RAM until reboot. Full picture in [SECURITY.md](SECURITY.md).\n\n2. **Modem**: store the bridge's address as phone book entry 0, then save:\n\n   ```\n   AT\u0026Z0=192.168.1.50:6400      (your host's LAN IP)\n   AT\u0026W\n   ```\n\n   Your specific modem may require different commands. Feel free to open a GitHub issue if you want to contribute instructions for your specific hardware.\n\n   Connect on the boot menu dials entry 0. The menu also has a live Hayes AT console for whatever your modem needs. Cables, per-device commands (a fresh WiModem ships at 300 baud and wants `AT*B9600` once), and a \"modem plays dead\" checklist are in [docs/MODEM-SETUP.md](docs/MODEM-SETUP.md).\n\n3. **Disk**: copy `CLAUDE.dsk` to a FloppyEmu SD card (5.25\" mode, boots from slot 6). On a Mac, `tools/install-sd.sh` does it safely; FloppyEmu is very sensitive to FAT32 fragmentation, and macOS fragments more than you'd expect. If a card is already fragmented, `tools/install-sd.sh repair` fixes it. **Create backups before using!**\n\n4. Power on and pick **Connect** from the menu. With any luck, it should connect to the bridge automatically!\n\nTo update later, download the new release image and re-run `install-sd.sh`; it overwrites the existing image in place.\n\n## Emulator instructions\n\nI used [KEGS](https://kegs.sourceforge.net/), but any Apple II emulator with serial emulation should work. (KEGS needs an Apple IIgs ROM file you supply — see the KEGS docs.)\n\n1. Download **CLAUDE.dsk** from [Releases](https://github.com/wr/apple-ii-terminal-for-claude-code/releases).\n2. In KEGS, press **F4**: set **s6d1** to `CLAUDE.dsk`, and set Serial Port **Slot 2** to **Incoming** (KEGS then listens on TCP 6502).\n3. Start the bridge, then reboot the emulator with Ctrl-⌘-Reset:\n\n   ```sh\n   git clone https://github.com/wr/apple-ii-terminal-for-claude-code\n   cd apple-ii-terminal-for-claude-code/bridge\n   python3 bridge.py --connect 127.0.0.1:6502 --app --backend code --workdir ~/your-project\n   ```\n\n4. On the boot menu pick **1. Connect**, then type. `--workdir` is the project Claude works in.\n\n## Advanced bridge options\n\nThe bridge is one Python script. Pick a transport, a backend, and (for the native clients) `--app`. Two commands cover almost everything:\n\n```sh\n# Emulator (KEGS in Incoming mode):\npython3 bridge.py --connect 127.0.0.1:6502 --app --backend code --workdir ~/project\n\n# Real hardware (WiFi modem listening):\npython3 bridge.py --telnet --app --backend code --workdir ~/project\n```\n\n**Transport** (choose one):\n\n| Flag | Use |\n|---|---|\n| `--connect HOST:PORT` | Dial out to a listening emulator (KEGS Incoming, port 6502) |\n| `--telnet` | Listen for a WiFi modem or TCP client (port 6400) |\n| `--serial PORT` | A serial cable, e.g. `/dev/tty.usbserial-1420` (pair with `--baud`, default 9600) |\n\n**Backend:**\n\n| Flag | Use |\n|---|---|\n| `--backend code` | The real agentic Claude Code. Edits files and runs commands on the host, in `--workdir`. That's the point, but know it |\n| `--backend chat` | Plain Q\u0026A via the Messages API. Needs `ANTHROPIC_API_KEY` and `bridge/requirements-chat.txt` (default backend) |\n| `--workdir DIR` | Code mode: the project Claude works in |\n| `--model ID` | Override the Claude model |\n| `--effort LEVEL` | Chat thinking effort: low/medium/high/xhigh/max (default low) |\n\n**Native client:**\n\n| Flag | Use |\n|---|---|\n| `--app` | Native-client protocol. Required for the clients on the boot disk |\n| `--cols 40\\|80` | Screen width (default 80; use 40 for a II+ or a 40-column IIe) |\n\n**Pairing** (telnet only):\n\n| Flag | Use |\n|---|---|\n| `--pair-code CODE` | Fix one shared code for every caller; letters are case-insensitive (default: an on-demand code per source IP) |\n| `--clear-paired` | Revoke every stored token credential at startup |\n| `--no-pair` | Drop the pairing gate entirely (isolated networks only) |\n| `--host ADDR` | Bind address (default `0.0.0.0`; set `127.0.0.1` to keep it local) |\n\nRun `python3 bridge.py --help` for the rest (flow control, pacing, telnet negotiation, permission mode).\n\n## Generic terminal app instructions\n\nRun the bridge without `--app` and it speaks ordinary 40/80-column text, so any Apple II with a terminal program, or a stock IIc using the firmware's built-in terminal over a serial cable, can talk to Claude with nothing installed on the II. Wiring, pinouts, and per-machine settings are in [apple2/TERMINAL-SETUP.md](apple2/TERMINAL-SETUP.md).\n\n## Claude slash commands\n\nSlash commands from the II: the bridge handles `/help`, `/new` or `/clear`, `/mode chat|code`, `/model NAME`, and `/quit` or `/exit`. In code mode everything else passes through to the CLI, so `/cost`, `/context`, `/compact`, and your installed skills run for real. Ctrl-C interrupts a reply mid-think (the bridge kills the turn and sends what it has); pressed at an idle prompt it quits to the menu.\n\n- - -\n\n## Building from source\n\nYou don't need this to run it; the release disk is prebuilt. To hack on it you need [cc65](https://cc65.github.io/) (`brew install cc65`), [dos33fsprogs](https://github.com/deater/dos33fsprogs) (built anywhere, point `DOS33FSPROGS` at it), and Python 3 with `requirements-build.txt` installed.\n\n```sh\npython3 -m pip install -r requirements-build.txt\ncd apple2gs \u0026\u0026 ./build.sh                                    # both clients into one CLAUDE.dsk\npython3 preview.py assets.inc out.png                         # render the SHR screen, no emulator\n```\n\n`build.sh` starts from a pristine Apple DOS 3.3 System Master and injects both clients plus a machine-detecting HELLO; that master-based image is the one proven to boot KEGS, FloppyEmu, and real drives alike. The master is vendored at `apple2gs/dos33-master-jan83.dsk` (the January 1983 System Master, 143,360 bytes), so a clean checkout builds with nothing to fetch. It's Apple's OS, not ours; see [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md). Verify it:\n\n```sh\nshasum -a 256 apple2gs/dos33-master-jan83.dsk\n# 70986935d95c4a918852700364ac107607eb861a7d93a69c2b5caf44a696b17a\n```\n\nEverything else is generated at build time: the font from [unscii](http://viznut.fi/unscii/), the splash animation machine-ported from a gif, the sounds from tone tables in `gen_assets.py`. Provenance for the bundled material is in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).\n\nThe 8-bit client has its own harness: MAME with an emulated Super Serial Card mapped to a TCP socket, driven by Lua-scripted keystrokes, so the whole boot → dial → session → reply loop runs unattended.\n\n- - -\n\n## Credits\n\nThis project is not affiliated with or endorsed by Anthropic. This is a fan project that gives their excellent CLI a 1986 terminal for fun. \"Claude\" and the Clawd mascot are Anthropic's.\n\n- **Font:** [unscii](http://viznut.fi/unscii/) (CC0)\n- **Disk tooling:** [dos33fsprogs](https://github.com/deater/dos33fsprogs) by Vince Weaver.\n- **Emulator:** [KEGS](https://kegs.sourceforge.net/).\n- The Apple II community... Apple II forever!\n\nMIT license, covering this project's own code only. The build and the release disk also include third-party material (Apple's DOS 3.3, the Clawd art, the unscii font); provenance and status for each is in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwr%2Fapple-ii-terminal-for-claude-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwr%2Fapple-ii-terminal-for-claude-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwr%2Fapple-ii-terminal-for-claude-code/lists"}