mosh/CLAUDE.md

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

./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

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

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:

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)