If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mobile-shell/mosh shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 7w ago
• 16 active contributors
• Distributed ownership (top contributor 34% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mobile-shell/mosh repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mobile-shell/mosh.

What it runs against: a local clone of mobile-shell/mosh — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mobile-shell/mosh | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 78 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mobile-shell/mosh. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mobile-shell/mosh.git
#   cd mosh
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mobile-shell/mosh and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mobile-shell/mosh(\\.git)?\\b" \\
  && ok "origin remote is mobile-shell/mosh" \\
  || miss "origin remote is not mobile-shell/mosh (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/frontend/mosh-client.cc" \\
  && ok "src/frontend/mosh-client.cc" \\
  || miss "missing critical file: src/frontend/mosh-client.cc"
test -f "src/frontend/mosh-server.cc" \\
  && ok "src/frontend/mosh-server.cc" \\
  || miss "missing critical file: src/frontend/mosh-server.cc"
test -f "src/crypto/crypto.cc" \\
  && ok "src/crypto/crypto.cc" \\
  || miss "missing critical file: src/crypto/crypto.cc"
test -f "src/crypto/base64.cc" \\
  && ok "src/crypto/base64.cc" \\
  || miss "missing critical file: src/crypto/base64.cc"
test -f "scripts/mosh.pl" \\
  && ok "scripts/mosh.pl" \\
  || miss "missing critical file: scripts/mosh.pl"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 78 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~48d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mobile-shell/mosh"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Mosh (Mobile Shell) is a remote terminal application written in C++ that replaces SSH for interactive sessions, adding support for intermittent connectivity, IP roaming, speculative local echo, and client-side prediction of server behavior. It solves the SSH problem of connection drops when switching networks (Wi-Fi to cellular) and high-latency link frustration by predicting keystrokes locally while awaiting server confirmation. Classic C++ project using GNU Autotools: configure.ac drives the build, m4/ contains macro logic, source code lives in src/ (inferred but not shown), platform-specific code in macosx/ and debian/, shell completions in conf/bash-completion. Build artifacts and CI configuration in .github/workflows; packaging for multiple distributions (Debian, Fedora, macOS) in separate directories.

Systems administrators, developers, and mobile workers who use SSH regularly but need reliable remote terminal sessions over unreliable or roaming networks (switching Wi-Fi networks, cellular handoffs). Contributors are maintainers of remote access tools and users who want SSH-like authentication without SSH's connection fragility.

Production-ready and actively maintained. The project has CI/CD pipelines (.github/workflows/ci.yml, cifuzz.yml, release.yml), established packaging for Debian and Fedora (debian/, fedora/mosh.spec), and comprehensive build tooling (configure.ac, autogen.sh). Recent activity visible in GitHub Actions workflows and maintained ChangeLog/NEWS files; this is not a hobby project.

Low risk for production use but moderate risk for new contributors due to C++ complexity and platform-specific concerns. The codebase is 526KB of C++ with M4 macro complexity (104KB of configure machinery), and the README explicitly notes environment variable security requirements per OS (GNU/Linux, OS X, FreeBSD all verified but other platforms untested). Single release pipeline (build-package.sh, build-source-package.sh) means packaging is centralized.

The project maintains active CI with workflows for formatting checks (clang-format.yml), fuzzing (cifuzz.yml), and releases (release.yml). Debian and Fedora package maintenance is current (debian/watch, fedora/mosh.spec present), and the ChangeLog is actively updated. No specific PR/issue counts visible in file list, but GitHub Actions suggest frequent test runs.

git clone https://github.com/mobile-shell/mosh.git && cd mosh && ./autogen.sh && ./configure && make && make install. Requires autotools (autogen.sh), C++ compiler, and development libraries (curses, openssl inferred from configure.ac M4 macros).

Daily commands: After make: mosh-server runs on remote (invoked by SSH), mosh-client connects locally. For development: make check (inferred from Makefile.am), ./mosh-client user@host to test a connection. .clang-format present indicates code style enforcement.

• src/frontend/mosh-client.cc — Primary client entry point that handles terminal I/O, key input prediction, and speculative echo—core to Mosh's interactive behavior.
• src/frontend/mosh-server.cc — Server daemon that manages session state, terminal emulation, and network synchronization with roaming clients.
• src/crypto/crypto.cc — Cryptographic layer implementing OCB encryption and HMAC authentication for secure session transport.
• src/crypto/base64.cc — Base64 encoding/decoding used throughout for key material and encrypted payload serialization.
• scripts/mosh.pl — SSH wrapper script that orchestrates client-server connection establishment and session handshake.
• src/frontend/terminaloverlay.cc — Predictive terminal emulator that renders speculative local echo before server confirmation.
• configure.ac — Autotools configuration defining build dependencies (OpenSSL, Curses) and platform-specific compilation flags.

Add a new protocol message type

1. Define message structure in protocol header (typically in stmclient.h or a new protos/ file) (src/frontend/stmclient.h)
2. Add serialization/deserialization logic in base64/encoding layer (src/crypto/base64.cc)
3. Implement handler in server state machine (mosh-server.cc) (src/frontend/mosh-server.cc)
4. Implement handler in client state machine (stmclient.cc) (src/frontend/stmclient.cc)
5. Add integration test in examples (e.g., ntester.cc) (src/examples/ntester.cc)

Improve speculative prediction model

1. Review and extend the terminal overlay state machine logic (src/frontend/terminaloverlay.cc)
2. Add new key-event prediction rules or escape sequence handlers (src/frontend/terminaloverlay.h)
3. Create test cases in termemu example to validate predictions (src/examples/termemu.cc)
4. Integrate new rules into client's prediction loop (mosh-client.cc) (src/frontend/mosh-client.cc)

Support a new platform or transport

1. Add platform-specific network socket code in configure.ac (e.g., UDP or new transport) (configure.ac)
2. Implement roaming/IP change detection in client loop (src/frontend/mosh-client.cc)
3. Update server's socket binding and session tracking (src/frontend/mosh-server.cc)
4. Test with ntester or add new test harness in examples/ (src/examples/ntester.cc)

• UDP (not TCP) — Allows session continuity across roaming (IP changes, network switches) without TCP's connection state barriers; each packet is independent.
• OCB authenticated encryption (OpenSSL) — Provides confidentiality and authenticity in a single pass, critical for security over untrusted networks without reliable packet ordering.
• Speculative local echo + predictive terminal emulator — Masks high-latency and intermittent connectivity by rendering keystrokes immediately while waiting for server confirmation, preserving interactive feel.
• Perl SSH wrapper (mosh.pl) — Bridges the gap between standard SSH workflows and Mosh's session setup, allowing users to invoke mosh like SSH without new infrastructure.
• GNU Autotools (Autoconf/Automake) — Ensures portable cross-platform builds (Linux, macOS, BSD, iOS) with conditional compilation and dependency detection.

• Stateless UDP-based protocol vs. connection-oriented streams

  • Why: Roaming requires IP address changes; UDP avoids connection teardown/rebuild overhead on network switch.
  • Consequence: Protocol must handle out-of-order packets, duplicates, and implement application-level retransmission; complexity shifts from OS to Mosh.

• Aggressive client-side prediction vs. strict server echoing

  • Why: User experience improves dramatically if keystrokes appear instantly; prediction is often correct (arrows, normal text).
  • Consequence: On misprediction (e.g., vi mode switch), screen flickers; requires robust state reconciliation.

• Cryptographic overhead on every keystroke packet

  • Why: Security and privacy critical for roaming over untrusted networks (Wi-Fi hotspots, cellular).
  • Consequence: Higher CPU and bandwidth per keystroke vs. raw SSH; mitigated by batching and OCB efficiency.

• Terminal emulation logic duplicated in client (overlay) and server

  • Why: Client needs local copy of state to make predictions; server maintains true state.
  • Consequence: Risk of divergence; must keep emulation rules in sync.

• Does not provide file transfer; use scp/rsync over Mosh session separately.
• Does not handle authentication; delegates to SSH and its key management.
• Does not support graphical applications (X11/Wayland forwarding not designed in).
• Not a VPN; does not encrypt or route arbitrary traffic, only the terminal session.
• Does not replace SSH; relies on SSH for initial connection establishment.

1. Environment variable security: mosh-client passes AES session keys via env vars; the README explicitly warns that some OSes don't isolate process environment variables from other users—audit this per target platform. 2. UTF-8 requirement: README states 'requires a UTF-8 environment to run'; locale misconfiguration will break the client. 3. SSH invocation: Mosh bootstraps via SSH (configure.ac likely probes for SSH path); if SSH is not in PATH or uses non-standard port, connection setup fails silently. 4. UDP firewall rules: Protocol runs on UDP (not TCP); UFW rules are in conf/ufw/applications.d/mosh, but misconfiguration blocks roaming entirely.

• Speculative local echo — Mosh's core differentiator—the client predicts keystrokes and renders them immediately while awaiting server confirmation. Understanding prediction accuracy, RTT recovery, and underline-on-uncertain-prediction is essential to contributing to client logic.
• UDP-based reliable transport — Mosh doesn't use TCP like SSH; it runs over UDP with custom congestion control and frame sequencing. Crucial for handling packet loss and roaming without connection resets.
• Client-side prediction and state reconciliation — The client maintains a shadow model of the server's terminal state and reconciles when predictions diverge. Core architecture pattern affecting client-server protocol design.
• GNU Autotools (Autoconf/Automake) — The entire build system uses M4 macros and Autotools; understanding configure.ac and m4/ is mandatory for cross-platform porting and dependency management.
• AES session key management — Mosh uses AES for session encryption and passes keys via environment variables (flagged in README as security-sensitive per OS). Critical for understanding the authentication and encryption architecture.
• Terminal multiplexing and ANSI escape sequences — Mosh must correctly parse and predict ANSI control codes for cursor movement, colors, and full-screen app behavior. Bugs here break vi, emacs, alpine, irssi—all mentioned as test cases in README.
• Network roaming and connection migration — Unlike SSH, Mosh survives IP address changes (Wi-Fi to cellular). The protocol must track client identity independently of IP; essential for understanding how sessions persist across network transitions.

• OpenSSH/openssh-portable — Mosh leverages SSH for authentication and initial connection setup; understanding OpenSSH internals helps debug connection bootstrap
• tmux/tmux — Both are remote terminal multiplexers dealing with latency and disconnection; tmux handles session persistence while Mosh handles network resilience—often used together
• vim/vim — Mosh mentions vim as a full-screen app it must handle correctly; understanding terminal control sequences and prediction edge cases requires studying vi/vim terminal behavior
• terminal-emulators/iterm2 — Mosh client must emulate terminal behavior accurately; iTerm2 is referenced in the README as a test case for full-screen app compatibility
• charm-k8s/charm — Charm is an alternative remote shell focused on web-native protocols; competitive project solving similar latency/roaming problems with different transport

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive CI workflow for macOS and Fedora package builds

The repo has build scripts for macOS (macosx/build.sh, macosx/osx-xcode.sh, macosx/brew-deps.sh) and Fedora (fedora/mosh.spec), but .github/workflows/ci.yml likely only tests on Linux. Adding dedicated workflows would catch platform-specific build failures early, especially important for a mobile shell that targets multiple OSes.

• [ ] Examine .github/workflows/ci.yml to confirm macOS and Fedora builds are not currently tested
• [ ] Create .github/workflows/macos-build.yml that runs macosx/build.sh and macosx/osx-xcode.sh on macOS runners
• [ ] Create .github/workflows/fedora-build.yml that builds the RPM using fedora/mosh.spec
• [ ] Test Debian package build using debian/rules in the existing CI
• [ ] Verify all platform-specific dependencies are installed in each workflow

Add shell completion tests for bash-completion config

The repo ships bash completion configuration at conf/bash-completion/completions/mosh, but there's no visible test suite to validate that completions work correctly. Adding tests would ensure the mosh command-line interface completions don't break with future changes.

• [ ] Create a new test file (e.g., tests/test-bash-completion.sh or similar test directory)
• [ ] Write test cases that source conf/bash-completion/completions/mosh and verify completion functions are defined
• [ ] Add test cases for common mosh flags (--ssh, --server, --client, etc.) to ensure they complete correctly
• [ ] Integrate the bash completion tests into .github/workflows/ci.yml
• [ ] Document testing approach in README or CONTRIBUTING guide

Add man page validation and consistency checks

The repo has man pages (man/mosh.1, man/mosh-client.1, man/mosh-server.1) but no automated validation. Man pages can drift from actual code behavior or contain formatting errors. Adding CI validation would catch these issues before release.

• [ ] Create a CI workflow step (or add to existing ci.yml) that uses 'man' or 'groff' to validate man page syntax and formatting
• [ ] Add a script (e.g., scripts/validate-man-pages.sh) that extracts all command-line flags from man pages and compares against actual help output
• [ ] Verify man page references to scripts/mosh.pl, macosx/, debian/, and fedora/ are accurate and up-to-date
• [ ] Add checks to ensure man pages reference the same flags and options in all three files (mosh, mosh-client, mosh-server)
• [ ] Integrate validation into ci.yml and .clang-format checks workflow

• Add unit tests for the prediction model: README details the speculative local echo algorithm, but no test/ directory is visible in the file list. Creating test harnesses for Terminal and Prediction classes (inferred from architecture) would improve confidence in porting to new platforms.
• Document platform-specific security checks: README mentions GNU/Linux, OS X, and FreeBSD environment isolation verified, but Windows, Android, and iOS are not listed. Audit COPYING.iOS and add a security-check matrix in a docs/ folder.
• Complete bash completion for mosh flags: conf/bash-completion/completions/mosh exists but likely only has basic completion. Expand it to cover --ssh, --server, --bind-server, and other advanced flags documented in README (or add missing flags to the client if they exist).

The Mosh codebase demonstrates moderate security posture. Primary concerns include custom cryptographic implementations that require formal security audits, lack of explicit security build flags documentation, and absence of a vulnerability disclosure policy. The project structure shows good separation of cryptographic code into dedicated modules, and use of established tools like OpenSSL. No obvious hardcoded credentials, injection vulnerabilities, or exposed secrets were detected in the file structure. Recommendation: Conduct formal cryptographic audit, implement explicit security compiler flags, and establish vulnerability reporting process.

• Medium · Cryptographic Implementation in Custom Code — src/crypto/ocb_internal.cc, src/crypto/ocb_openssl.cc. The codebase implements custom cryptographic functions (OCB mode in src/crypto/ocb_internal.cc and src/crypto/ocb_openssl.cc) rather than relying solely on well-tested library implementations. Custom crypto implementations are prone to subtle vulnerabilities including timing attacks, side-channel leaks, and implementation errors. Fix: Conduct formal security audit of custom cryptographic code. Consider using only OpenSSL's validated OCB implementation. Ensure constant-time implementations to prevent timing attacks. Add comprehensive cryptographic test vectors.
• Medium · Base64 Implementation in Security-Critical Code — src/crypto/base64.cc, src/crypto/base64.h. Custom base64 encoding/decoding implementation (src/crypto/base64.cc) in a cryptographic module could introduce vulnerabilities if not properly validated against attack vectors like padding oracle attacks or buffer overflows. Fix: Use well-tested library implementations for base64 encoding (e.g., OpenSSL's base64 functions). If custom implementation is necessary, ensure it's been formally reviewed and tested against known attack vectors.
• Low · Benchmark and Example Code in Production Distribution — src/examples/benchmark.cc, src/examples/encrypt.cc, src/examples/decrypt.cc. Cryptographic benchmarking and example code (src/examples/benchmark.cc, encrypt.cc, decrypt.cc) may inadvertently expose implementation details or provide attack templates if included in production builds. Fix: Ensure example and benchmark code is excluded from production builds. Mark these as development/testing only. Document their purpose clearly.
• Low · Missing Security Headers in Build Configuration — Makefile.am, configure.ac. The build system (Makefile.am, configure.ac) does not explicitly document compiler security flags (stack protection, ASLR, PIE, fortify source) that should be enabled for a security-sensitive application like a remote shell. Fix: Add compiler flags: -fstack-protector-strong, -D_FORTIFY_SOURCE=2, -fPIE. Add linker flags: -pie, -z relro, -z now. Document these in configure.ac with proper autoconf checks.
• Low · No Visible Security Policy or Vulnerability Disclosure Process — Repository root. No SECURITY.md, security policy, or vulnerability disclosure guidelines are present in the repository, making it difficult for security researchers to responsibly report vulnerabilities. Fix: Create a SECURITY.md file with: vulnerability disclosure process, contact information, responsible disclosure timeline, and bug bounty information if applicable.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.