First working version.

CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A tool that runs an interactive shell behind a simulated serial (baud-rate) throttle,
+so that terminal output animates one character at a time instead of appearing all at
+once (e.g. to replay old VT100/ANSI animations that a fast terminal would render
+instantly).
+
+- `baudshell` — the program. Pure Python 3, self-contained: it launches `bash --norc`
+  in a PTY and throttles **both** directions of I/O in-process (no helper binary, no
+  `cc` build step).
+- `baud.c` — an *optional* standalone C pipe filter with the same throttling idea
+  (reads stdin, re-emits it one char per `10/baud` seconds to stdout). It is **not**
+  used by `baudshell`; it exists for the "throttle a piped animation file" use case,
+  e.g. `cat anim.ans | baud 9600`. It compiles independently (`cc baud.c -o baud`);
+  the `baud` binary it produces is gitignored.
+
+There is no build system, test suite, linter, or CI. Everything besides the two source
+files (the `baud` binary, `.DS_Store`) is in `.gitignore`.
+
+## Run
+
+No build step is needed for the shell:
+
+```sh
+./baudshell            # or: python3 baudshell
+./baudshell 2400       # simulate 2400 baud instead of the default 9600
+```
+
+`argv[1]`, if given, is the **baud rate** (a positive integer; default 9600, lower is
+slower). A non-integer or non-positive rate prints an error and exits 2.
+
+The program puts the terminal into raw mode and restores it on exit, so keystrokes
+reach the shell char-by-char. To leave, type `exit` in the shell (or close the
+terminal); the program detects the shell's exit and cleans up.
+
+## Architecture
+
+`baudshell` multiplexes two file descriptors with `select()`: the terminal
+(`sys.stdin`) and the PTY master. The single subprocess is `bash` (in its own session
+via `preexec_fn=os.setsid`, on the PTY slave); the throttle itself runs in-process.
+
+```
+keyboard ─► fd_term ─► throttled_copy ─► master ─► shell (bash)
+                                       │
+terminal ◄─ fd_term ◄─ throttled_copy ◄─ master ◄┘
+```
+
+- **Throttling is `throttled_copy(src, dst, baud)`**: read a chunk from `src`, then
+  write it to `dst` **one byte at a time, sleeping `10/baud` seconds between bytes**.
+  This runs for both directions — keystrokes are throttled into the shell, and the
+  shell's output is throttled out to the terminal, mirroring a real serial link.
+- `delay_per_char(baud)` returns `10/baud` seconds. A serial byte is 10 bits
+  (1 start + 8 data + 1 stop), so a line at `baud` bits/s carries `baud/10` bytes/s;
+  this is the same formula the original `baud.c` used.
+
+### End-of-stream / clean shutdown (the reason the old version hung)
+
+The loop breaks as soon as either copy returns `True` (stream finished), which is how
+the two termination cases are handled:
+
+- **Shell exits** (`master` reaches EOF) → stop, then reap the shell and propagate its
+  exit status. This is the fix for the original bug: the previous version ignored the
+  copy result and spun forever after the shell exited.
+- **stdin reaches EOF** (terminal closed / piped input drained) → stop, and
+  `shell.terminate()` kills the still-running shell.
+
+A `finally` block always restores the terminal's termios settings. Throttle math:
+rate must be `> 0`; unlike the C original, Python's `time.sleep` has no upper bound, so
+very low rates are accepted rather than rejected.