docs: add CLAUDE.md

CLAUDE.md

@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What is Mosh
+
+Mosh (mobile shell) is a remote terminal application that supports intermittent connectivity and roaming. Unlike SSH, it uses UDP and synchronizes terminal state as diffs, allowing the client to do predictive local echo and survive network changes.
+
+## Build System
+
+Mosh uses GNU Autotools (Autoconf/Automake).
+
+```bash
+./autogen.sh          # Generate build scripts (required after cloning)
+./configure           # Configure build
+make                  # Build
+make check            # Run all tests
+```
+
+Useful configure options:
+- `--enable-compile-warnings=error` — treat warnings as errors
+- `--enable-asan` — enable AddressSanitizer
+- `--enable-code-coverage` — enable coverage reporting
+- `--with-crypto-library=openssl|nettle|apple-common-crypto` — choose crypto backend (default: autodetect)
+- `--disable-client` / `--disable-server` — build only one side
+
+## Running Tests
+
+```bash
+make check              # Run all tests
+make V=1 check          # Verbose output
+make check-code-coverage  # Coverage report (requires --enable-code-coverage)
+```
+
+Test types:
+- **Unit tests** (`src/tests/`): ocb-aes, encrypt-decrypt, base64, nonce-incr, is-utf8-locale
+- **End-to-end tests**: tmux-based display/network/unicode/resize tests (see `src/tests/README.md`)
+
+## Static Analysis / Linting
+
+```bash
+make cppcheck    # cppcheck static analysis
+make scan-build  # Clang static analyzer
+```
+
+Code style uses `.clang-format` (Mozilla-based, 116-column limit). CI enforces clang-format on PRs.
+
+## Dependencies
+
+Ubuntu/Debian:
+```bash
+sudo apt install build-essential protobuf-compiler libprotobuf-dev pkg-config \
+    libutempter-dev zlib1g-dev libncurses5-dev libssl-dev bash-completion tmux less
+```
+
+## Architecture
+
+```
+src/
+  frontend/    — mosh-client.cc, mosh-server.cc entry points
+  crypto/      — AES-OCB encryption; supports OpenSSL, Nettle, Apple Common Crypto
+  network/     — UDP transport, state sync, compression, fragmentation
+  terminal/    — Terminal emulator, Unicode, character cell rendering
+  statesync/   — State diff/sync logic between client and server
+  protobufs/   — Protobuf definitions (hostinput, userinput, transportinstruction)
+  util/        — PTY, locale, timestamps, select wrapper
+  tests/       — Unit + end-to-end tests
+  fuzz/        — Fuzzing targets
+```
+
+**Data flow:**
+1. `mosh-client` SSHes to server, spawns `mosh-server`
+2. Server sends AES-128 key + UDP port over SSH, then SSH closes
+3. Client and server exchange terminal state diffs over UDP
+4. Client applies predictive local echo using its own terminal emulator
+5. Server sends authoritative state; client reconciles
+
+**Crypto:** AES-128-OCB with a fresh key per session. Key is passed out-of-band via SSH. The crypto backend is selected at configure time; the abstraction lives in `src/crypto/`.
+
+**State sync:** Both ends maintain a `Terminal::Complete` object. The network layer (`src/network/`) sends `TransportInstruction` protobufs containing diffs. The client uses `src/statesync/` to apply them.
+
+## Security Notes (from README)
+
+- Hardening flags enabled by default (`-fstack-protector-all`, `-D_FORTIFY_SOURCE=2`, `-fPIE`, RELRO, etc.)
+- `mosh-server` must ensure process environment is not readable by other users before writing the session key to stdout
+- C++17 is required minimum (protobuf compatibility)