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/haimgel/display-switch 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 all four use cases

• Last commit 5w ago
• 8 active contributors
• MIT licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits
• ⚠ 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 haimgel/display-switch repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/haimgel/display-switch.

What it runs against: a local clone of haimgel/display-switch — 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 haimgel/display-switch | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 66 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/app.rs" \\
  && ok "src/app.rs" \\
  || miss "missing critical file: src/app.rs"
test -f "src/configuration.rs" \\
  && ok "src/configuration.rs" \\
  || miss "missing critical file: src/configuration.rs"
test -f "src/display_control.rs" \\
  && ok "src/display_control.rs" \\
  || miss "missing critical file: src/display_control.rs"
test -f "src/usb.rs" \\
  && ok "src/usb.rs" \\
  || miss "missing critical file: src/usb.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 66 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~36d)"
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/haimgel/display-switch"
  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).

display-switch is a Rust daemon that monitors USB device connect/disconnect events and automatically switches monitor inputs via DDC/CI (Display Data Channel), turning a $30 USB switch into a multi-monitor KVM switch. When you plug a USB device into a switch, it detects the connection and commands all connected monitors to switch to a specific input (HDMI1, DisplayPort2, etc.), making it feel like a hardware KVM without the expensive hardware. Monolithic daemon: src/main.rs bootstraps a long-running app (src/app.rs) that reads INI config (src/configuration.rs), monitors USB events (src/usb.rs via rusb), detects platform-specific device connections (src/platform/), and commands monitors to switch inputs (src/display_control.rs). Platform abstraction is handled via compile-time feature flags in src/platform/mod.rs with separate implementations for macOS, Windows, and Linux.

Systems engineers and power users with multiple computers and shared multi-monitor setups who want hardware-agnostic monitor switching without buying a $500+ KVM switch. Contributors are primarily individuals maintaining multi-computer workstations (macOS, Windows, Linux) who need cross-platform USB monitoring and DDC/CI control.

Actively developed and production-ready. The project is at v1.5.0 with a clean CI/CD pipeline (.github/workflows/build.yml), Homebrew distribution, and support for three major OSes. Last activity and version history suggest steady maintenance, though the single-maintainer pattern (haimgel) and modest GitHub presence indicate it's a specialized niche tool rather than mainstream.

Low risk for core functionality but moderate platform-specific fragility: USB detection uses platform-specific backends (libusb on Linux, WinAPI on Windows, native APIs on macOS in src/platform/), DDC/CI monitor communication relies on external crates (ddc, ddc-hi, ddc-macos, ddc-i2c, ddc-winapi) which may have stale dependencies, and single maintainer means feature requests or bugs may have long turnaround. Dependency footprint is modest (~15 direct deps) but platform-specific crates are critical points of failure.

No specific open issues visible from file list, but the repo maintains active CI/CD (build.yml runs on commits), has dependabot configured (.github/dependabot.yml) to auto-update Rust deps, and releases are automated (.github/release.yml). The v1.5.0 tag and Makefile suggest active building/testing cycle. Recent work appears focused on platform stability rather than new features.

git clone https://github.com/haimgel/display-switch.git
cd display-switch
cargo build --release
./target/release/display_switch --help

On macOS with Homebrew: brew install haimgel/tools/display_switch.

Daily commands: Dev: cargo run (reads config from platform-specific paths: ~/Library/Preferences/display-switch.ini on macOS, %APPDATA%\display-switch\display-switch.ini on Windows, ~/.config/display-switch/display-switch.ini on Linux). Production: make builds release binary, or cargo build --release. Debug output: set RUST_LOG=debug env var (uses simplelog).

• src/main.rs — Entry point and main event loop that orchestrates USB device detection and monitor switching—every contributor must understand the app's startup and control flow.
• src/app.rs — Core application state machine and command execution logic; essential for understanding how USB events trigger display switches.
• src/configuration.rs — Configuration file parsing and schema definition; required for understanding user settings and how they map to device behavior.
• src/display_control.rs — DDC/CI protocol abstraction for monitor control; critical for implementing or debugging display input switching.
• src/usb.rs — USB device detection and event monitoring using libusb; essential for understanding how the app detects connected/disconnected devices.
• src/platform/mod.rs — Platform abstraction layer dispatcher for Windows, macOS, and Linux; required for cross-platform feature implementation.
• Cargo.toml — Dependency manifest defining critical libraries (ddc-hi, rusb, clap); understand this to evaluate library choices and version constraints.

• main.rs (Entry & Event Loop) (Rust std, rusb, clap) — Initializes logging, parses CLI args, creates USB hotplug listener, and runs the core event loop until shutdown signal.
  • Failure mode: Crashes on USB enumeration failure; entire daemon halts (user must restart).
• app.rs (State Machine) (Rust enum/match, configuration, display_control) — Maintains application state, dispatches USB device events to configured actions, and orchestrates display input switching and shell command execution.
  • Failure mode: Unmatched device ID → no action taken (silent failure); display switch error → logs error but doesn't retry.
• configuration.rs (Config Parser) (config crate, serde, INI format) — Parses INI configuration files defining USB device → action mappings (display input switch, shell command).
  • Failure mode: Malformed INI → panics during daemon startup; missing required fields → validation error.
• display_control.rs (DDC/CI Interface) (ddc-hi crate, DDC/CI protocol) — Communicates with monitors via DDC/CI protocol to switch input sources; handles VCP code translation and I2C communication.
  • Failure mode: Monitor doesn't support DDC/CI or no I2C access → I/O error; VCP code mismatch → monitor doesn't switch.
• usb.rs (USB Device Detection) (rusb, platform-specific PnP detection) — Enumerates USB devices, registers hotplug event listener, and notifies main.rs of device connection/disconnection.
  • Failure mode: libusb initialization fails → app cannot detect devices; hotplug listener registration

Add a new monitor input source mapping

1. Define the input source constant and enum variant in src/input_source.rs (e.g., HDMI3, DisplayPort2) (src/input_source.rs)
2. Add DDC/CI input code mapping in src/display_control.rs if it differs from standard VCP codes (src/display_control.rs)
3. Update configuration schema in src/configuration.rs to allow users to reference the new source (src/configuration.rs)
4. Test the mapping by adding a configuration entry and running the daemon with USB events (Cargo.toml)

Add platform-specific USB device detection

1. Create a new file src/platform/pnp_detect_<platform>.rs with the platform's USB event listener implementation (src/platform/pnp_detect_windows.rs)
2. Export the implementation in src/platform/mod.rs and add conditional compilation guards (src/platform/mod.rs)
3. Update src/usb.rs to call the platform-specific detector in the hotplug event loop (src/usb.rs)
4. Test device connection/disconnection handling in src/app.rs event processing (src/app.rs)

Add a new shell command action on device switch

1. Extend the Action enum in src/configuration.rs to include ShellCommand variant with command string and timeout (src/configuration.rs)
2. Implement the shell command execution in src/app.rs's execute_action function using shell-words crate (src/app.rs)
3. Add configuration file documentation and example in README.md showing the new action syntax (README.md)
4. Test by creating a config with a ShellCommand action and triggering a USB device change (Cargo.toml)

• Rust — Memory safety without GC, cross-platform compilation, excellent async/sync primitives for USB event handling, and reliable daemon behavior.
• rusb (libusb) — Cross-platform USB device enumeration and hotplug event detection without OS-specific bloat; unified API for Windows, macOS, Linux.
• ddc-hi crate — High-level DDC/CI abstraction for monitor control; handles low-level protocol negotiation and input source switching via VCP codes.
• clap for CLI — Ergonomic command-line argument parsing with automatic help/version generation for daemon mode and testing.
• config crate with INI format — Human-readable configuration files (matching KVM switch expectations); pluggable parsing for easy user configuration.

• Single-threaded event loop in main.rs instead of async/tokio

  • Why: Simplicity and reduced latency for USB hotplug events; daemon doesn't handle concurrent high-throughput I/O.
  • Consequence: Blocking USB operations during display switching; not suitable for high-frequency event streams but acceptable for user-triggered monitor switches.

• DDC/CI as the primary monitor control mechanism

  • Why: Universal standard across monitor brands; no proprietary driver or EDID parsing required.
  • Consequence: Depends on monitor DDC/CI support; some older or budget monitors may not implement input switching via DDC/CI.

• Platform abstraction via conditional compilation (#[cfg]) rather than trait objects

  • Why: Zero-cost abstraction; compiled code only includes Windows/macOS/Linux path, reducing binary size and complexity.
  • Consequence: Code duplication across platform modules; requires platform-specific testing for each OS.

• Stateless configuration file parsing (no daemon reload)

  • Why: Avoids state inconsistency and complex reload logic; users restart daemon to apply config changes.
  • Consequence: Users must manually restart the daemon when configuration changes; no hot-reload capability.

• Does not support keyboard/mouse switching (only monitor inputs via DDC/CI).
• Does not provide a GUI or web dashboard; configuration is file-based only.
• Does not handle monitor discovery or auto-configuration; users must manually configure monitors and input sources.
• Does not support EDID-based monitor identification; relies on USB device IDs for action triggering.
• Does not implement monitor power management beyond DDC/CI wake; cannot force shutdown or deep sleep.

Config file is required and must be INI: app will not auto-create it; missing config will fail silently or with generic log messages. Per-platform USB device IDs differ: Windows uses WinAPI registry, Linux uses libusb, macOS uses IOKit—same VID:PID may not work identically across platforms. DDC/CI unreliability: many monitors respond inconsistently to DDC commands; if a monitor doesn't support DDC/CI, the app cannot control it silently (no error, just no-op). Linux requires i2c kernel module: /dev/i2c-* must exist and be readable for ddc-i2c to work. Homebrew tap is custom: brew install haimgel/tools/display_switch requires the custom tap to be added first. RUST_LOG env var is case-sensitive: must be RUST_LOG=debug, not rust_log.

• DDC/CI (Display Data Channel/Command Interface) — Core protocol used by display-switch to command monitors; understanding its limitations (not all monitors implement it, some commands are unreliable) explains why the tool doesn't work universally
• USB hot-plug detection / PnP (Plug and Play) — display-switch's entire premise depends on detecting USB device connect/disconnect events; platform-specific implementations differ significantly (WinAPI device notifications vs. libusb hotplug vs. IOKit), making cross-platform testing critical
• I2C (Inter-Integrated Circuit) — Monitors expose DDC/CI over I2C bus; Linux backend uses i2c-dev kernel driver, Windows uses DDC-over-MCCS API, macOS uses IOKit—I2C is the physical/logical layer underneath
• Platform abstraction via compile-time feature flags — display-switch uses Rust's conditional compilation (cfg attributes and feature flags) to maintain single codebase for macOS/Windows/Linux; this is the pattern chosen to avoid runtime dispatch overhead
• INI file configuration with subsections — Config schema uses per-monitor subsections ([monitor1], [monitor2]) to override global settings; this is non-trivial parsing pattern that users must understand for multi-monitor setups
• Daemon/service lifecycle (daemon mode, signal handling) — display-switch runs as a long-lived background process monitoring USB events; proper daemon setup (stdout/stderr handling, PID files on Unix, Windows service registration) is platform-specific but essential for production use
• Vendor ID / Product ID (VID/PID) enumeration — USB device identification is done via hex VID:PID pairs (e.g., '1050:0407'); understanding USB enumeration and how VIDs/PIDs are assigned is necessary to configure the tool for any USB switch

• torvalds/linux — kernel i2c subsystem that ddc-i2c (Linux backend) depends on; relevant for understanding /dev/i2c-* device permissions and DDC/CI protocol at OS level
• libusb/libusb — underlying USB library that rusb wraps; understanding libusb context/device enumeration helps debug USB detection issues
• ddcutil/ddcutil — standalone C tool that also controls monitors via DDC/CI; mature reference implementation for DDC protocol and monitor compatibility quirks
• GyroFlow/gyroflow_toolbox — another Rust multi-platform daemon using similar platform abstraction patterns and CI/CD setup via GitHub Actions
• barrier/barrier — software KVM alternative that shares keyboard/mouse across systems; complementary tool often used alongside display-switch for full KVM-like experience

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 platform-specific integration tests for DDC/CI display control

The repo has platform-specific display control implementations (src/platform/wake_displays.rs, src/display_control.rs) but no visible test files. Adding integration tests would verify DDC/CI commands work correctly on macOS, Windows, and Linux before release, reducing user-reported bugs for monitor switching failures.

• [ ] Create tests/display_control_tests.rs with mock DDC implementations for each platform
• [ ] Add platform-specific test modules in tests/ for wake_displays behavior
• [ ] Integrate tests into .github/workflows/build.yml to run on all three OS targets
• [ ] Document test setup requirements (e.g., DDC library mocking) in CLAUDE.md

Add USB device detection tests covering edge cases in pnp_detect modules

src/platform/pnp_detect_windows.rs and src/platform/pnp_detect_libusb.rs handle critical USB device detection logic but lack visible unit tests. Edge cases like device disconnection, rapid reconnection, and malformed USB events could cause monitor switches to fail silently.

• [ ] Create tests/usb_detection_tests.rs with mock USB device events
• [ ] Add unit tests in src/platform/ testing disconnection/reconnection scenarios for Windows and Linux paths
• [ ] Test configuration reload behavior when USB events occur (src/configuration.rs interaction)
• [ ] Add property-based tests using proptest for malformed USB event handling

Complete the Installation section in README.md with platform-specific setup guides

The README.md ends abruptly with 'Linux and Windows: download and extract the files from the releas' (incomplete sentence). This leaves users without clear installation, configuration, and daemon setup instructions for macOS (launchd via dev.haim.display-switch.daemon.plist), Windows (service installation), and Linux (systemd service). Configuration file examples are missing entirely.

• [ ] Complete Windows installation section with .exe download, service registration steps, and UAC requirements
• [ ] Add macOS section documenting launchd setup using dev.haim.display-switch.daemon.plist and log locations
• [ ] Add Linux section with systemd unit file generation and udev rules for USB device permissions
• [ ] Document config.ini format with examples for each platform's section (using src/configuration.rs as reference)
• [ ] Add troubleshooting section referencing src/logging.rs log output locations

• Add integration tests for src/configuration.rs parsing: create test INI files in tests/ directory and verify per-monitor overrides parse correctly (currently no test coverage visible for config validation)
• Document the exact DDC/CI input codes for common monitors (Dell, LG, Lenovo): create a monitors.md file mapping monitor_id substrings to their specific input codes since users currently must discover these via trial-and-error
• Add systemd service template and Windows Task Scheduler example config: src/platform/ has Linux and Windows but no installation instructions for running display-switch as a daemon—add templates to docs/ so users don't run it interactively

The display-switch project is a relatively well-structured Rust application with moderate security posture. Key strengths include use of a memory-safe language (Rust) and clear module organization. Primary concerns are: 1) potential USB device spoofing/confusion attacks, 2) unvalidated command execution via shell-words, 3) DDC/CI protocol's lack of authentication, and 4) insufficient documentation on configuration file and privilege handling. The application operates at a system level with hardware access, making input validation and privilege management critical. No hardcoded secrets or obvious injection vulnerabilities were identified in the provided file structure, but direct code review is needed for definitive analysis. Consider conducting a full security audit with emphasis on USB device

• Medium · Use of shell-words crate for command parsing — Cargo.toml (shell-words = "1.1"). The dependency 'shell-words' (1.1) is used for parsing shell commands. If user input or untrusted data is passed to shell command execution without proper validation, this could lead to command injection vulnerabilities, especially when combined with system command execution. Fix: Review all usages of shell-words in the codebase. Ensure that: 1) User input is properly validated and sanitized before being passed to shell-words, 2) Commands are executed with minimal privileges, 3) Consider using direct function calls instead of shell execution where possible.
• Medium · Potential USB device manipulation without validation — src/usb.rs, src/platform/pnp_detect_*.rs. The application monitors USB device connect/disconnect events and performs actions based on them. If USB device identification or matching logic is not robust, an attacker could potentially trigger unintended monitor switches by connecting arbitrary USB devices with similar identifiers. Fix: Implement strict USB device validation including: 1) Whitelist-based device matching (VID/PID), 2) Verify device class and subclass, 3) Log all USB events for audit purposes, 4) Add user confirmation for unexpected devices.
• Medium · DDC/CI protocol exploitation risk — src/display_control.rs, Cargo.toml (ddc dependencies). The application uses multiple DDC/CI libraries (ddc, ddc-hi, ddc-macos, ddc-i2c, ddc-winapi) to control displays. DDC/CI lacks authentication, and if the application processes untrusted display configuration data, it could be exploited to perform unauthorized display operations. Fix: 1) Restrict DDC/CI operations to specific, pre-configured monitors, 2) Validate all display parameters before sending DDC commands, 3) Implement rate limiting on DDC operations, 4) Run the application with minimal necessary privileges.
• Low · Configuration file security — src/configuration.rs, Cargo.toml (config = "0.15"). The application uses configuration files (based on 'config' crate with 'ini' feature). If configuration files contain sensitive data or are world-readable, local users could extract display setup information or other configuration details. Fix: 1) Ensure configuration files are created with restrictive permissions (0600), 2) Document that users should not store sensitive credentials in config files, 3) Consider using secure credential storage (keyring/keychain), 4) Validate all configuration values before use.
• Low · Logging sensitive information — src/logging.rs, Cargo.toml (log, simplelog). The application uses the 'log' and 'simplelog' crates. If USB device information, display configurations, or other potentially sensitive data is logged, it could be exposed in log files with insufficient access controls. Fix: 1) Review logging statements to avoid logging sensitive information like device serials or display configurations, 2) Ensure log files have restrictive permissions, 3) Implement log rotation, 4) Consider implementing sanitization of sensitive data before logging.
• Low · Platform-specific privilege escalation risks — src/platform/*, Cargo.toml (winapi, nvapi dependencies). The application handles platform-specific functionality (Windows, macOS, Linux) that may require elevated privileges for USB and display operations. Improper privilege handling could lead to local privilege escalation. Fix: 1) Document required privileges for each platform, 2) Request only minimal necessary privileges, 3) Validate that privilege levels are appropriate before performing operations, 4) On Linux, consider using udev rules instead of elevated privileges where possible.

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.