david.boston / prompt64
Codex, Claude, and local AI agents on the Commodore 64 Ultimate.
Star 0
Fork 0
Watch
Python 63%
Rust 33%
Assembly 2%
Makefile 1%
Linker Script <1%
21 1 1
bridge
client
docs
protocol
.gitignore
AGENTS.md
CHANGELOG.md
LICENSE
Makefile
README.md
README.md

Prompt64 0.2 #

Prompt64 is a native Commodore 64 Ultimate terminal for monitoring and controlling AI coding agents. A no_std Rust-MOS client talks over UCI TCP to a dependency-free Python bridge. Codex app-server is the production provider; the wire events and C64 UI remain provider-neutral.

Version 0.2 adds:

  • a 64×40 circular, color-preserving transcript outside the PRG image;
  • strict PROMPT64/2 framing and sequenced turn output;
  • 120-second reconnect leases with exact missing-output replay;
  • live command, file, MCP/tool, web, subagent, image, and compaction activity;
  • STATUS, ACTIVITY, CHANGES, and ACTIONS dashboard tabs on F7;
  • bounded Git change snapshots and unified one-context diff pages;
  • six editable quick-action prompts and optional JSON customization.

Credentials, provider session IDs, approval IDs, and lease bookkeeping remain on the bridge. Lease tokens exist only in C64 and bridge RAM; reset, power loss, explicit navigation, or bridge restart discards them.

Install a release #

The versioned release archive contains the complete source, a prebuilt PROMPT64.PRG, its SHA256SUMS, and the bridge package. Verify and unpack it:

sha256sum -c prompt64-0.2.0.tar.gz.sha256
tar -xzf prompt64-0.2.0.tar.gz
cd prompt64-0.2.0
sha256sum -c SHA256SUMS

Install the dependency-free Python bridge in a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install ./bridge
codex login
prompt64-bridge \
  --host 0.0.0.0 \
  --port 6464 \
  --codex-cwd /path/to/workspace \
  --workspace-root /path/to

Launch PROMPT64.PRG using the C64 Ultimate file browser or a trusted-LAN deployment tool. The packaged PRG initially offers 192.168.1.2 and . in its editable connection screen; replace them with the bridge host's LAN address and intended workspace before connecting. On ChromeOS/Crostini, forward TCP 6464 to the container and enter the Chromebook's LAN address.

Build, test, and run #

make lint
make test
make build BRIDGE_HOST=192.168.1.23
codex login
make run-bridge
make dist

The build uses the pinned Rust-MOS container and produces build/PROMPT64.PRG plus build/PROMPT64.map. It enforces a 32,257-byte PRG budget, preserving at least 512 bytes before sprite RAM, plus linker assertions around screen, transcript, and dashboard memory. See the memory map.

Real-hardware acceptance can run unattended:

make hardware-test \
  DEVICE_IP=192.168.8.208 \
  BRIDGE_HOST=192.168.8.147 \
  HARDWARE_TEST_CONFIRM=1

The target runs lint, host tests, the production Rust-MOS build, device identity checks, repeated reset/DMA deployments, deterministic streaming, heartbeat and approval reconnect faults, transcript wraparound, dashboard and Git fixtures, quick actions, explicit lease release, and reset-token loss. It drives the production PRG through paused keyboard-buffer injection and captures screen/color RAM only at coordinated quiescent checkpoints. Results are written to build/hardware-report.json. TCP 6464 must be free, reachable through any ChromeOS forwarding boundary, and no normal bridge should be running.

The bridge defaults to TCP 6464, reasoning display off, and Codex. Use PROVIDER=fake, REASONING=summary, or REASONING=verbose for development. Summary and Detailed modes display only Codex's generated reasoning-summary events. Developer mode requests Codex's developer reasoning level and displays raw reasoning events. The C64 can select Read Only, Ask Me to Approve, or Auto Review before starting a provider session.

Developer mode is also available as REASONING=developer. Because it exposes raw provider reasoning rather than generated summaries, use it only when that additional detail is appropriate for the active session.

Set PETSCII_KAOMOJI=1 to advertise a composable C64-safe symbol palette to Codex for agent instructions that request kaomoji:

make run-bridge PETSCII_KAOMOJI=1

The palette is ♥ ● ♠ ─ │ ╱ ╲ ↑ ← ▒, mixed freely with ASCII rather than restricted to a list of finished faces. It does not modify global agent instructions or bridge launches that omit the setting. Prompt64 renders ASCII underscore as a horizontal bar because that byte is otherwise a left arrow in the C64 upper/graphics character set.

Workspace requests are restricted to WORKSPACE_ROOT, which defaults to CODEX_CWD:

make run-bridge \
  CODEX_CWD=/home/me/projects/prompt64 \
  WORKSPACE_ROOT=/home/me/projects

The bridge has no transport authentication or encryption. Run it only on a trusted LAN, firewall port 6464, and expose the narrowest practical workspace root.

Release artifacts #

Run make dist from a clean committed tree. It reruns lint, host tests, and the release build, verifies that the bridge and client versions match, and creates:

  • build/dist/prompt64-0.2.0.tar.gz
  • build/dist/prompt64-0.2.0.tar.gz.sha256

The archive includes the source corresponding to HEAD, the built PRG, and its internal checksum. See the changelog for release notes.

Dashboard and controls #

F7 opens or closes the dashboard. It starts on STATUS while idle and ACTIVITY during a turn. F1/F3 changes tabs; UP/DOWN selects; LEFT/RIGHT pages; RETURN refreshes or opens a change/action. ACTIONS is unavailable during an active turn. Approval prompts take focus and then return to the dashboard.

CHANGES reports staged, modified, deleted, and untracked paths from a stable snapshot. RETURN opens bounded, unified one-context diff lines; binary and untracked paths receive descriptive entries rather than fabricated text diffs.

ACTIONS loads the selected prompt into the 92-byte composer for editing. Defaults are Review Changes, Run Tests, Explain Failure, Summarize Work, Commit Changes, and Continue Task. Set ACTIONS_FILE or pass --actions-file; see the example. Labels must be 1–30 printable ASCII bytes, prompts 1–92, and the merged result may contain no more than eight actions. Labels merge case-insensitively unless replace_defaults is true. Invalid files stop bridge startup.

Other controls:

  • RETURN sends the composer; arrows, HOME, DEL, CLR, and four-entry history edit it.
  • F1 opens reasoning settings while idle.
  • F3 browses the 64-line transcript while idle.
  • F5 returns to session selection and explicitly releases the bridge lease.
  • RUN/STOP cancels an active turn or returns an idle client to connection settings, explicitly releasing the lease.

An unexpected network loss does not release the session. Active work and pending approvals continue on the bridge for 120 seconds, with up to 64 KiB of sequenced current-turn frames retained. Reconnection sends the last applied sequence and replays only newer frames.

See the protocol reference and hardware bring-up guide.

License #

Prompt64 is free software licensed under the GNU General Public License version 3 or later. Package metadata uses the SPDX identifier GPL-3.0-or-later.