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/feschber/lan-mouse 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.

WAIT — Mixed signals — read the receipts

• Last commit 2d ago
• 15 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{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 feschber/lan-mouse repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/feschber/lan-mouse.

What it runs against: a local clone of feschber/lan-mouse — 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 feschber/lan-mouse | 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 main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of feschber/lan-mouse. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/feschber/lan-mouse.git
#   cd lan-mouse
#
# 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 feschber/lan-mouse and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "feschber/lan-mouse(\\.git)?\\b" \\
  && ok "origin remote is feschber/lan-mouse" \\
  || miss "origin remote is not feschber/lan-mouse (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "input-capture/src/lib.rs" \\
  && ok "input-capture/src/lib.rs" \\
  || miss "missing critical file: input-capture/src/lib.rs"
test -f "input-emulation/src/lib.rs" \\
  && ok "input-emulation/src/lib.rs" \\
  || miss "missing critical file: input-emulation/src/lib.rs"
test -f "lan-mouse-gtk/src/lib.rs" \\
  && ok "lan-mouse-gtk/src/lib.rs" \\
  || miss "missing critical file: lan-mouse-gtk/src/lib.rs"
test -f "lan-mouse-cli/src/lib.rs" \\
  && ok "lan-mouse-cli/src/lib.rs" \\
  || miss "missing critical file: lan-mouse-cli/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
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/feschber/lan-mouse"
  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).

Lan Mouse is a cross-platform software KVM switch written in Rust that enables mouse and keyboard sharing across multiple PCs on a local network using DTLS encryption. It acts as an open-source alternative to Synergy/Share Mouse, allowing seamless input device control across machines running Windows, macOS, Linux (GNOME, KDE, Wayland compositors), with dedicated platform backends for input capture and emulation. Monorepo with 7 workspace members: core lan-mouse binary orchestrates; input-capture/ and input-emulation/ provide platform-specific backends (src files branch per OS/WM); lan-mouse-proto/ defines DTLS protocol; lan-mouse-gtk/ wraps GTK UI; lan-mouse-cli/ provides CLI wrapper; lan-mouse-ipc/ handles daemon communication. Shared input-event/ crate defines event types. Build system uses build.rs with shadow-rs for version metadata.

Linux desktop users, macOS users, and Windows users who maintain multiple computers and want unified input control without proprietary software; contributors interested in cross-platform Rust systems programming and input device handling across fragmented desktop environments (X11, Wayland, native APIs).

Actively developed (v0.10.0, recent CI/CD setup with GitHub Actions for release automation). Well-structured monorepo with proper build configuration, but not yet 1.0—still has known platform-specific caveats (X11 input capture unsupported, Wayland modifier issues). CI is robust with Cachix caching and multi-platform release workflows, indicating serious maintenance.

Single-maintainer repo (feschber) creates concentration risk. Moderate dependency footprint (tokio, webrtc-dtls, gtk) increases surface area; webrtc-dtls is from webrtc-rs community project, not battle-tested like OpenSSL. Platform fragmentation (7+ input backends: X11, libei, wlroots, macOS, Windows, XDG Portal) means fixes in one backend may not cascade—testing burden is high. Known unfixed issues (X11 capture, Sway modifier handling) suggest incomplete platform coverage.

Recent work appears focused on Wayland maturity (libei backend, wlroots/Sway/Hyprland/Wayfire support targeting GNOME ≥45, KDE Plasma ≥6.1); GTK UI is active (lan-mouse-gtk in workspace); CI pipelines are current (rust.yml, cachix.yml, release.yml). Known gaps listed in README suggest ongoing triage but not massive feature churn—maintenance-mode feel with targeted fixes.

Clone, build, and run:

git clone https://github.com/feschber/lan-mouse.git
cd lan-mouse
cargo build --release
./target/release/lan-mouse  # or: cargo run --bin lan-mouse

Optionally launch GTK UI: cargo run --bin lan-mouse-gtk --release. For NixOS users: nix develop (flake.nix present).

Daily commands: Development: cargo run --bin lan-mouse -- --help (CLI daemon). With GTK UI: cargo run --bin lan-mouse-gtk --release. Tests: cargo test --workspace. Release build: cargo build --release (uses codegen-units=1, LTO fat, strip, panic=abort for optimization). For NixOS: nix develop enters devShell from flake.nix.

• Cargo.toml — Workspace root defining all member crates (input-capture, input-emulation, lan-mouse-gtk, etc.) and shared dependencies; essential for understanding project structure and build configuration.
• input-capture/src/lib.rs — Core abstraction for capturing mouse/keyboard input across platforms; implements platform-specific backends (Windows, macOS, X11, Wayland).
• input-emulation/src/lib.rs — Core abstraction for emulating/injecting input events on remote machines; critical counterpart to input-capture supporting multiple platform backends.
• lan-mouse-gtk/src/lib.rs — GTK-based GUI entry point and main application logic; orchestrates input capture, network communication, and user configuration.
• lan-mouse-cli/src/lib.rs — CLI interface providing command-line access to lan-mouse functionality; alternative entry point to GTK GUI.
• input-event/src/lib.rs — Shared protocol layer defining input event types and cross-platform scancode abstractions used by capture and emulation crates.
• build.rs — Build script using shadow-rs to embed git metadata and versioning; required for release builds.

Add Support for a New Input Capture Platform (e.g., Linux Wayland via new protocol)

1. Create new backend module in input-capture/src/{protocol_name}.rs implementing the capture trait (input-capture/src/lib.rs)
2. Define platform detection logic and feature gate in lib.rs (e.g., #[cfg(target_os = "linux")]) (input-capture/src/lib.rs)
3. Export the new backend in the public API enum/match arms (input-capture/src/lib.rs)
4. Add corresponding emulation backend in input-emulation/src/{protocol_name}.rs (input-emulation/src/lib.rs)
5. Update Cargo.toml to add new protocol dependency if needed (Cargo.toml)

Add a New Configuration Option to the GTK UI

1. Define the new configuration field in config.toml and document it (config.toml)
2. Add UI control to window.ui (e.g., Switch, Entry, ComboBox) (lan-mouse-gtk/resources/window.ui)
3. Bind the UI control to the settings object in the main window implementation (lan-mouse-gtk/src/lib.rs)
4. Update authorization or settings logic to respect the new configuration (lan-mouse-gtk/src/authorization_window/imp.rs)

Add a New Keyboard Scancode Mapping for an Unsupported Key

1. Identify the platform-specific keycode and target scancode standard (input-event/src/scancode.rs)
2. Add mapping entry in the scancode translation table (Windows -> Linux, X11 -> macOS, etc.) (input-event/src/scancode.rs)
3. Test on target platform by running input capture and verifying the key event fires (input-capture/src/{platform}.rs)
4. Verify emulation uses the translated scancode correctly (input-emulation/src/{platform}.rs)

Add a New CLI Command

1. Define command parsing logic in lan-mouse-cli/src/lib.rs with argument struct (lan-mouse-cli/src/lib.rs)
2. Implement command handler that calls core lan-mouse logic (lan-mouse-cli/src/lib.rs)
3. Wire command into main entry point dispatcher (lan-mouse-cli/src/lib.rs)

• Rust + GTK — Memory-safe language with minimal runtime overhead; GTK provides native cross-platform UI on Linux/Unix, Windows GTK bindings, and macOS via Quartz/Cocoa bridges
• Platform-specific input APIs (Windows low-level hooks, X11 XTest, libei, XDG Portal) — Required to bypass OS-level input protection and sandbox restrictions; each platform has its own privileged input mechanism
• Workspace structure (7 member crates) — Isolates concerns: input-capture/emulation are reusable by CLI and GUI; input-event provides type safety; modular platform support avoids monolithic code
• shadow-rs build-time versioning — Embeds git commit hash and build metadata for accurate version reporting and debugging in the field

• Multi-backend input capture (X11, Wayland libei, Windows, macOS) instead of single unified layer

  • Why: Each platform has incompatible low-level input APIs and permission models; no single cross-platform input standard exists
  • Consequence: Code duplication across platform modules, maintenance burden for each platform; but gains native performance and compatibility

• GTK UI as primary interface instead of web/Electron

  • Why: GTK is lightweight, native-looking, and respects system accessibility settings; Electron would add 200MB+ overhead
  • Consequence: Requires GTK runtime; less familiar to some developers; but vastly smaller memory footprint and tighter OS integration

• Separate input-capture and input-emulation crates

  • Why: Capture is typically privileged (needs input monitoring); emulation is injected into remote peers; different dependency and security models
  • Consequence: Increases complexity; but allows CLI/headless operation without needing full desktop environment on server side

• Using scancode mapping instead of keycode passthrough

  • Why: Keycodes are OS-specific (QWERTY vs Dvorak, language layouts); scancodes are hardware-independent
  • Consequence: Must maintain scancode translation tables; but enables true keyboard layout independence across machines

• Not a client-server architecture; peer-to-peer only (all machines are peers, no central control server)
• Does not support clipboard synchronization (input events only: mouse + keyboard)
• Does not provide network encryption or TLS out-of-the-box (relies on LAN physical security or separate VPN layer)
• Not intended for remote desktop access (no screen sharing; only input/output sharing for same-room multi-PC setups)
• Does not support mobile devices (desktop-only: Windows, macOS, Linux)

DTLS certificate generation: rcgen creates self-signed certs at runtime—ensure /tmp or equivalent is writable and check rustls/rcgen version compatibility (0.23.12 and 0.13.1 pinned). Platform-specific build features: X11 capture and layer_shell_capture are feature-gated; building without them silently disables those backends. Wayland libei requirement: Input capture on Wayland requires libei library installed system-wide (not bundled). GTK optional: gtk feature is optional; headless daemon runs without it but UI requires it. macOS/Windows native dependencies: May need XCode Command Line Tools or MSVC toolchain + SDK headers not in Cargo.lock. Flake.nix usage: Project includes Nix flake; devShell may cache dependencies unexpectedly.

• DTLS (Datagram TLS) — Lan-mouse uses webrtc-dtls for encrypted UDP traffic over LAN; understanding DTLS vs TLS is essential for security review and debugging connection issues
• Input event abstraction (trait-based backends) — The project's core design (Capture/Emulate traits) decouples platform-specific input APIs (X11 XTest, Windows Win32, libei, IOKit) from core logic; understanding this pattern is critical for adding new platforms
• Wayland input protocols (libei, layer-shell, XDG Desktop Portal) — Wayland has no unified input capture API unlike X11; lan-mouse implements 3+ different protocols (libei for Plasma, layer-shell for wlroots, portal for GNOME) making Wayland support fragmented
• Self-signed certificate generation (rcgen) — Lan-mouse generates ephemeral DTLS certificates at runtime using rcgen; understanding cert lifecycle and pinning is needed for peer verification and security hardening
• Async message passing (Tokio channels) — All input events flow through tokio::sync channels between capture, protocol, and emulation layers; understanding backpressure and ordering is critical for debugging latency or lost inputs
• X11 vs Wayland input model differences — X11 has XTest but no grabbing; Wayland has no universal input API and requires compositor-specific protocols; this explains why X11 capture is unimplemented and why Wayland has multiple backends
• macOS IOKit and Quartz event taps — macOS backend (input-emulation/src/macos.rs) likely uses IOKit for input and Quartz event taps for capture; understanding these Apple-specific APIs is needed for macOS-specific bugs

• input-leap/input-leap — Actively maintained Synergy fork in C++; direct competitor solving the same KVM problem with different tech stack and longer maturity
• deskflow/deskflow — Another Synergy fork (formerly Barrier) in C++; similar cross-platform input sharing with different approach to platform backends and SSL/DTLS
• webrtc-rs/webrtc — Provides the webrtc-dtls crate used by lan-mouse for encryption; understanding its API and limitations is critical for protocol debugging
• wlroots/wlroots — Wayland compositor library that lan-mouse targets (Sway, Hyprland build on it); key to understanding the layer-shell and libei input paths
• GNOME/mutter — GNOME Wayland compositor; lan-mouse must handle its libei/portal integration differently than wlroots compositors, making it an important test platform

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 integration tests for lan-mouse-proto serialization/deserialization

The lan-mouse-proto crate handles protocol communication between peers but has no visible test coverage. Given this is a network-critical component for mouse/keyboard sharing, integration tests would catch serialization bugs, protocol version mismatches, and edge cases in message handling. This directly impacts reliability across the LAN.

• [ ] Create tests/integration_test.rs in lan-mouse-proto/ directory
• [ ] Test serialization/deserialization round-trips for all protocol message types
• [ ] Add tests for protocol versioning and backward compatibility scenarios
• [ ] Run tests in CI via rust.yml workflow to catch regressions

Add platform-specific e2e tests for input-capture and input-emulation

The input-capture and input-emulation crates contain platform-specific code (x11.rs, windows.rs, macos.rs, libei.rs) but no visible tests. Since input handling is OS-dependent and critical to functionality, adding basic e2e tests per platform would catch regressions when dependencies update. This is especially important given the complex FFI boundaries (libei, X11, Windows APIs).

• [ ] Create tests/ directory in input-capture/ with platform-gated tests using #[cfg(target_os = '...')]
• [ ] Add basic test for input capture initialization on each platform (X11, Windows, macOS)
• [ ] Repeat for input-emulation/ crate (verify mouse/keyboard event injection works)
• [ ] Update rust.yml to run platform-specific tests on corresponding runners

Add detailed CLI and IPC protocol documentation to DOC.md

lan-mouse-cli and lan-mouse-ipc are core components but DOC.md appears incomplete (README snippet cuts off). Contributors need clear documentation of: CLI command structure, IPC message formats, authentication flow, and config file schema (config.toml). This reduces friction for contributors extending CLI features or IPC handlers.

• [ ] Expand DOC.md with 'CLI Interface' section documenting all commands from lan-mouse-cli/src/lib.rs
• [ ] Add 'IPC Protocol' section documenting message types and socket communication from lan-mouse-ipc/
• [ ] Document config.toml schema with examples for each field in build-aux/ or main config.toml
• [ ] Add authentication/fingerprint flow diagram (referenced in authorization_window.ui but undocumented)

• Add integration tests for protocol round-trip: lan-mouse-proto/tests/ is absent; write tests serializing/deserializing mouse move, click, and keyboard events via DTLS to verify wire format stability across versions: Medium
• Document X11 limitations in DOC.md: README notes X11 capture is unsupported but rationale and workarounds are missing; add section explaining why (XTest limitations, no input grabbing) and recommend Wayland or xdotool fallback: Low
• Expand input-event crate tests: input-event/Cargo.toml is sparse; add unit tests for mouse/keyboard event normalization and boundary conditions (negative coordinates, modifier combos) to catch platform-specific quirks early: Low-Medium
• Add GitHub Actions job to test feature combinations: Current CI lacks matrix testing of feature flags (gtk on/off, x11_capture on/off, libei on/off); add job that tests common permutations to catch feature interaction bugs: Medium
• Create troubleshooting guide for Wayland modifier key issues: Sway/wlroots compositors have known modifier bugs (mentioned in README); write concrete reproduction steps and debug output parsing in CONTRIBUTING or TROUBLESHOOTING file: Low

• High · Outdated rustls Dependency — Cargo.toml - rustls dependency. The project uses rustls 0.23.12, which may have known vulnerabilities. rustls is a critical cryptographic library used for TLS operations. Regular updates are essential to patch security issues. Fix: Regularly update rustls to the latest stable version. Run 'cargo update rustls' and test thoroughly. Consider using cargo-deny or similar tools to audit dependencies.
• High · Potential Remote Code Execution via Network Input — lan-mouse-proto crate, input-emulation, input-capture modules. The project handles network input for mouse/keyboard sharing via LAN. The use of webrtc-dtls and custom protocol handling (lan-mouse-proto) without clear input validation could lead to RCE if deserialization or protocol parsing is not properly secured. Fix: Implement strict input validation and bounds checking for all network-received data. Use fuzzing tools (cargo-fuzz) to test protocol parsing. Audit serialization/deserialization (serde) configurations for unsafe patterns.
• High · Insufficient Certificate Validation — lan-mouse-gtk (fingerprint_window.ui), webrtc-dtls integration. The project uses rcgen (0.13.1) for certificate generation and rustls for TLS. The fingerprint_window.ui suggests certificate pinning or fingerprint verification, but the actual implementation details are unclear. Weak certificate validation could allow MITM attacks. Fix: Implement robust certificate pinning with public key pinning. Verify that certificate validation is performed on both client and server sides. Use certificate transparency logs for validation. Document the security model clearly.
• Medium · Release Profile Uses Strip Without Debug Info Backup — Cargo.toml - [profile.release]. The release profile includes 'strip = true' and 'panic = abort', which removes debug information. While this is common for releases, it prevents post-mortem debugging of security issues and crashes in production. Fix: Consider maintaining separate debug symbols for security incident investigation. Use separate symbol files (.pdb, .dsym) or upload them to a symbol server rather than stripping entirely.
• Medium · Unsigned Binary Releases — .github/workflows/release.yml, build process. The GitHub workflows (release.yml) and build process don't show evidence of signed releases or binary checksums. Users cannot verify the integrity of downloaded binaries. Fix: Implement GPG signing for all releases. Generate and publish checksums (SHA-256) for each binary. Document the verification process for users. Consider using cosign for container/binary signing.
• Medium · Potential Privilege Escalation via Input Emulation — input-emulation/src (all platform implementations). The input-emulation crate provides keyboard/mouse emulation capabilities across multiple platforms (Windows, macOS, X11, libei). Improper implementation could allow code execution in privileged contexts. Fix: Audit all platform-specific input emulation code for privilege escalation vectors. Use principle of least privilege for the daemon. Implement capability restrictions on Linux (CAP_SYS_ADMIN). Document required permissions clearly.
• Medium · Unencrypted Configuration File — config.toml (root), configuration handling. The config.toml file is referenced but likely stored in plaintext. User configuration may contain sensitive data like hostnames, IPs, or authentication tokens. Fix: Implement encryption for sensitive configuration values. Use platform-specific credential storage (Keyring on Linux/Windows/macOS). Document where sensitive data should never be stored in plaintext.
• Medium · Network Binding Configuration Risk — firewall/lan-mouse.xml, network binding configuration. The firewall rule (firewall/lan-mouse.xml) suggests the application binds to network ports. Without clear documentation of default bindings, there's risk of unintended exposure. Fix: Document all default ports and bindings. Implement secure-by-default configuration (bind to localhost by default, require explicit LAN binding). Use localhost for control channels.
• Low · Missing Security Policy Documentation — undefined. No SECURITY.md or security policy file is visible in the repository. Users cannot report vulnerabilities responsibly Fix: undefined

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.