Added a README.md

README.md

@@ -0,0 +1,57 @@
+# baudshell
+
+Run an interactive shell behind a simulated serial (baud-rate) throttle. Output
+scrolls across the screen one character at a time instead of appearing all at once,
+exactly as it would on a real slow serial terminal. It's the modern equivalent of
+watching a 9600-baud modem, and it makes old VT100/ANSI animations visible again
+that a fast terminal would otherwise render instantly.
+
+Requires Python 3 and a terminal (a TTY) — it puts the terminal in raw mode for
+the session and restores it on exit.
+
+## Usage
+
+```
+./baudshell [BAUD]
+```
+
+`BAUD` is the serial rate to simulate, in bits/second. It is optional; the default
+is **9600**. Lower is slower. You can also run it without the executable bit:
+
+```
+python3 baudshell [BAUD]
+```
+
+## Examples
+
+```sh
+./baudshell          # bash at the default 9600 baud
+./baudshell 2400     # slower still
+./baudshell 300      # a classic 300-baud modem — a dramatic typewriter effect
+./baudshell 115200   # nearly instantaneous
+```
+
+Type commands as usual. When you are done, type `exit` (or close the terminal);
+`baudshell` detects that the shell has exited and returns, leaving your terminal in
+its original state.
+
+The throttle applies in both directions, just like a real serial line: your
+keystrokes are fed into the shell at the chosen rate, and the shell's output is
+emitted back to the terminal at that same rate.
+
+## How it works
+
+The program launches `bash --norc` on a pseudo-terminal, then copies between your
+terminal and that PTY one byte at a time, sleeping `10 / baud` seconds between
+bytes (a serial byte is 10 bits, so a `baud`-bit line carries `baud/10`
+bytes/second). A non-positive or non-numeric rate prints an error and exits.
+
+## Also in this repo
+
+`baud.c` is a small standalone C filter with the same throttling idea, for piping
+a file rather than driving a shell:
+
+```sh
+cc baud.c -o baud
+cat animation.ans | ./baud 9600
+```