Skip to content

CLAUDE.md

Latest commit

 

History

History
108 lines (77 loc) · 6.95 KB

CLAUDE.md

File metadata and controls

108 lines (77 loc) · 6.95 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. Use Claude Teams (https://code.claude.com/docs/en/agent-teams) when appropriate to parallelize work.

Spawn a team with members:

  • Team Lead (claude-opus-4-6) - Extensive Classic Macintosh System 6 Application experience, make decisions and delegate work
  • Software Architect (claude-opus-4-6) - System 6 and Telnet Expert, reviews code for completeness, functionality, bug fixes, overall design
  • Build Engineer (claude-sonnet-4-6) - build releases with Retro68, copy to HFS disks. Does NOT launch or interact with Snow emulator — only builds and deploys to HFS image
  • Technical Writer (claude-sonnet-4-6) - create and update documentation, take screenshots, record any learnings for future use
  • UI/UX QA Engineer (claude-sonnet-4-6) - SOLE operator of Snow emulator. Boots Snow, runs all GUI automation and testing with python scripts. No other agent should launch or interact with Snow

Snow emulator ownership: Only the QA Engineer may launch, interact with, or take screenshots of Snow. The Build Engineer deploys to the HFS disk image (hmount/hcopy/humount) but must NOT run snowemu or use xdotool/scrot. This prevents conflicts from multiple agents controlling the same emulator instance.

Project Overview

Flynn is a Telnet client application for classic Macintosh (68000/Macintosh Plus) written in C, targeting System 6.0.8 with MacTCP 2.1. The primary use case is connecting to modern Linux telnetd servers for interactive terminal sessions (vi, nano, tmux, etc.).

Target Platform Constraints

  • Motorola 68000 CPU only (no PowerPC, no 68020+ instructions)
  • 4 MiB RAM on Macintosh Plus
  • System 6.0.8 primary target, System 7 secondary
  • MacTCP for networking (not Open Transport)
  • Latency and responsiveness are critical priorities
  • Monochrome only, no color or grayscale
  • Start with VT100

Build System

  • Cross-compile on Linux using Retro68 toolchain
  • Toolchain built from source, installed at Retro68-build/toolchain/ (in-repo, gitignored)
  • Source cloned at Retro68/ (in-repo, gitignored)
  • Build: ./scripts/build.sh (configures + makes), or manually: mkdir build && cd build && cmake .. -DCMAKE_TOOLCHAIN_FILE=../Retro68-build/toolchain/m68k-apple-macos/cmake/retro68.toolchain.cmake && make
  • CMake flag: -m68000 for Mac Plus compatibility
  • MacTCP.h is NOT in Retro68's Multiversal Interfaces — copied from wallops-146
  • Retro68 API quirks vs classic Toolbox: qd.thePort not thePort, GetMenuHandle not GetMHandle, AppendResMenu not AddResMenu, LMGetApplLimit() not GetApplLimit

Testing

Emulator: Snow (Primary)

Snow v1.3.1, a Rust-based classic Mac emulator with low-level hardware emulation. See docs/TESTING.md for complete guide.

IMPORTANT: Do NOT launch Snow, deploy to disk images, or run any automated testing unless the user explicitly asks. All testing and QA is done by the human driving the session. Only build and deploy when asked and ready to test.

  • Binary: tools/snow/snowemu (local copy, gitignored)
  • Workspace: diskimages/flynn.snoww (Mac Plus, 1.5x scale)
  • HDD image: diskimages/snow-sys608.img (90MB SCSI, System 6.0.8 installed)
  • ROM: roms/68k/128k/Macintosh Plus/1986-03 - 4D1F8172 - MacPlus v3.ROM
  • Floppies: tools/floppies/*.img (System 6.0.8 set, 800K each)
  • Keyboard: Right ALT = Command key (map_cmd_ralt: true)
  • Networking: DaynaPORT SCSI/Link Ethernet emulation, NAT mode (10.0.0.0/8)
  • File sharing: BlueSCSI Toolbox protocol (Tools > File Sharing)
  • Launch: DISPLAY=:0 tools/snow/snowemu diskimages/flynn.snoww &

GUI Automation

Snow can be fully automated via X11 for unattended testing. See docs/SNOW-GUI-AUTOMATION.md for the complete guide. Only run automated GUI tests when the user explicitly requests it.

  • Window manager: WindowMaker (wmaker) — KDE lacks _NET_ACTIVE_WINDOW support
  • Click method: xdotool mousedown 1 && sleep 0.05 && xdotool mouseup 1 (NOT xdotool click)
  • Screenshots: DISPLAY=:0 scrot screenshot.png (do NOT use import -window root — it permanently breaks Snow mouse input)
  • Coordinates: Screenshot pixel coords = X11 screen coords (1:1 at 1280x800)

Basilisk II (Deprecated)

Basilisk II was tested extensively but has critical incompatibilities with System 6.0.8. All 512KB ROMs force 32-bit addressing, which System 6 doesn't support, and synthetic mouse events don't register in its X11 event loop. See docs/TESTING.md for details.

Test Target

  • Host: <telnet-host> (user: <username>, password: <password>) — see local memory for real values
  • Service: telnetd (standard Linux)

Repository Conventions

  • Git remote: https://github.com/ecliptik/flynn.git
  • Use feature branches, commits, and worktrees for development
  • Do NOT commit: disk images, FLYNN.md, or other non-source artifacts
  • Maintain: README.md, CHANGELOG.md, TODO.md
  • Maintain a development journal documenting how the project was built with agentic AI

Reference Code

Two existing classic Mac C applications are in ./code-examples/ for reference:

  • wallops-146: IRC client by jcs@jcs.org - shows classic Mac event loop, menu handling, MacTCP usage, window management, focusable UI pattern
  • subtext-596: BBS server by jcs@jcs.org - contains telnet.c/telnet.h with a complete Telnet IAC negotiation implementation (server-side), MacTCP TCP wrapper API in tcp.c/tcp.h

Key patterns from reference code:

  • MacTCP wrapper functions: _TCPInit, _TCPCreate, _TCPActiveOpen, _TCPSend, _TCPRcv, _TCPStatus, _TCPClose, _TCPRelease, DNSResolveName
  • Classic Mac event loop: WaitNextEvent with EventRecord, handling mouseDown, keyDown, updateEvt, activateEvt, app4Evt
  • Mac Toolbox initialization sequence: InitGraf, InitFonts, FlushEvents, InitWindows, InitMenus, TEInit, InitDialogs, InitCursor, MaxApplZone
  • Telnet protocol: IAC command/option negotiation state machine, NAWS (window size), TTYPE, TSPEED, SGA, ECHO, BINARY options
  • The subtext telnet code is server-side; this project needs a client-side implementation (we send DO/WILL, they respond)

Architecture Notes

The application needs these core components:

  • Telnet protocol engine: Client-side IAC negotiation (the inverse of subtext's server-side implementation)
  • Terminal emulator: VT100/ANSI escape sequence parsing and rendering
  • MacTCP networking: TCP connection management using the MacTCP API (see tcp.c/tcp.h in examples)
  • Mac UI layer: Classic Mac event loop, window management, menus, keyboard input
  • DNS resolution: Using MacTCP DNR (see dnr.c/dnr.h in examples)

Programming Reference Material