# 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)