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/alvr-org/ALVR 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 1w ago
• 22+ active contributors
• MIT licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 52% 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 alvr-org/ALVR repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alvr-org/ALVR.

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

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

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

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "alvr/client_core/src/lib.rs" \\
  && ok "alvr/client_core/src/lib.rs" \\
  || miss "missing critical file: alvr/client_core/src/lib.rs"
test -f "alvr/client_openxr/src/lib.rs" \\
  && ok "alvr/client_openxr/src/lib.rs" \\
  || miss "missing critical file: alvr/client_openxr/src/lib.rs"
test -f "alvr/common/src/lib.rs" \\
  && ok "alvr/common/src/lib.rs" \\
  || miss "missing critical file: alvr/common/src/lib.rs"
test -f "alvr/adb/src/lib.rs" \\
  && ok "alvr/adb/src/lib.rs" \\
  || miss "missing critical file: alvr/adb/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 37 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~7d)"
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/alvr-org/ALVR"
  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).

ALVR (Air Light VR) is a wireless VR streaming solution that transmits SteamVR games from a PC to standalone VR headsets over Wi-Fi, implemented in Rust for the server-side streaming engine and C++ for client-side video decoding. It handles real-time video encoding, network packet scheduling, and low-latency input feedback across heterogeneous VR platforms (Quest, Pico, Vive, Vision Pro, etc.). Workspace monorepo (Cargo.toml, resolver = 2): alvr/server_core/ contains PC-side streaming engine, alvr/client_core/ wraps Android/C API via cbindgen.toml for JNI interop, alvr/packets/ defines wire protocol, alvr/sockets/ handles UDP transport, alvr/audio/, alvr/graphics/ are platform-specific subsystems. CLI/GUI launchers wrap these via FFI.

VR enthusiasts and headset owners (Quest 3, Pico 4, Vive Focus, etc.) who want to play SteamVR games wirelessly instead of through USB, plus developers contributing to the open-source streaming pipeline (primarily Rust engineers for server-core, C++ for Android client-core).

Actively maintained and production-ready; version 21.0.0-dev13 with multi-platform support across Windows/Linux servers and 8+ headset types, comprehensive CI/CD in .github/workflows/ (build.yml, rust.yml, prepare-release.yml), and an established user base via GitHub releases and store integration (Steam, Meta Quest store). Recent development indicates ongoing optimization and feature additions.

Moderate complexity risk: network codec tuning and headset hardware variance create subtle platform-specific bugs; monorepo spans Rust + C++ + shader languages (WGSL, HLSL, GLSL), increasing build/test surface. Dependency management across workspace members (alvr_client_core, alvr_server_core, alvr_packets) requires careful coordination. Single-maintainer risk mitigated by community contributions but release cycles suggest steady staffing.

Development toward v21.0.0 with focus on stability (edition = 2024, rust-version = 1.92). GitHub Workflows indicate active CI testing, dependabot updates, and coordinated releases. Presence of prepare-release.yml and CHANGELOG.md tracking suggest regular cadence; community Discord/Matrix channels suggest ongoing user support.

git clone https://github.com/alvr-org/ALVR.git
cd ALVR
cargo build --release
# For server GUI, consult alvr/launcher or platform-specific build in .github/workflows/build.yml

Daily commands: PC Server: cargo run --release -p alvr_server_launcher (check .github/workflows/build.yml for platform-specific flags). Client: Headset-side APK built via Android NDK + CMake or gradle wrapper (see .github/workflows/ for CI build steps). Development: cargo test --workspace for unit tests, cargo clippy --all-targets for linting per .cargo/config.toml.

• Cargo.toml — Workspace root defining all member crates, shared dependencies, and version strategy (21.0.0-dev13); every contributor must understand the monorepo structure here
• alvr/client_core/src/lib.rs — Core client-side VR streaming logic bridging C FFI, connection, audio, video decoding, and statistics; essential for understanding how the headset receives and processes streams
• alvr/client_openxr/src/lib.rs — OpenXR runtime integration and main application loop for Android VR headsets; critical entry point for headset-side rendering and input handling
• alvr/common/src/lib.rs — Shared types, logging, version management, and primitives used across all crates; foundation for inter-process communication and error handling
• alvr/adb/src/lib.rs — ADB (Android Debug Bridge) integration for deploying and managing the client on Quest and Pico devices; critical for CI/CD and developer workflows
• alvr/dashboard/src/dashboard/components/about.rs — Dashboard UI entry point showing the desktop management interface; represents the server-side control surface
• .github/workflows/build.yml — CI/CD pipeline for cross-platform builds (Windows, Linux, Android); defines how releases are automated and validated

Add support for a new VR headset vendor or OpenXR extension

1. Define new OpenXR extension bindings in a new file under alvr/client_openxr/src/extra_extensions/ (e.g., my_vendor_tracking.rs) (alvr/client_openxr/src/extra_extensions/my_vendor_tracking.rs)
2. Register the extension in the mod.rs file and expose methods to the main library (alvr/client_openxr/src/extra_extensions/mod.rs)
3. Integrate extension data flow into the main stream/interaction loop (e.g., update pose tracking, expose new input) (alvr/client_openxr/src/interaction.rs)
4. Add vendor-specific types and constants to alvr/common/src/inputs.rs if new input events are needed (alvr/common/src/inputs.rs)
5. Update CI/CD if platform-specific compilation flags are required (.github/workflows/build.yml)

Add a new video codec or improve decoding pipeline

1. Extend the VideoDecoder enum and decoder module to support new codec (e.g., AV1, VP9) (alvr/client_core/src/video_decoder/mod.rs)
2. Implement platform-specific decoder (e.g., Android MediaCodec support for new format) (alvr/client_core/src/video_decoder/android.rs)
3. Update connection handshake to negotiate codec capabilities with server (alvr/client_core/src/connection.rs)
4. Add codec config to session schema (likely in alvr/session module, not shown in file list but referenced in Cargo.toml) (alvr/common/src/lib.rs)
5. Add test case or benchmark for decode performance (alvr/client_core/src/video_decoder/mod.rs)

Add a new dashboard UI component or settings panel

1. Create a new React/TypeScript component file under alvr/dashboard/src/dashboard/components/ (alvr/dashboard/src/dashboard/components/my_settings.rs)
2. Register the component in the main dashboard layout or navigation (alvr/dashboard/src/dashboard/src/dashboard/mod.rs)
3. Define backend API routes or state management to handle user settings (likely in server_io or session crates) (alvr/dashboard/Cargo.toml)
4. Add user-facing documentation and help text strings to localization or embedded constants (alvr/common/src/lib.rs)

Troubleshoot client-server connection issues or add new network diagnostics

1. Check connection handshake and version negotiation logic (alvr/client_core/src/connection.rs)
2. Review socket-level packet loss, latency, and bandwidth logging (alvr/client_core/src/sockets.rs)
3. Add new diagnostic metric to ClientStatistics struct (alvr/client_core/src/statistics.rs)
4. Expose diagnostics via C FFI for dashboard consumption (alvr/client_core/src/c_api.rs)
5. Visualize metrics in the dashboard debug panel (alvr/dashboard/src/dashboard/components/debug.rs)

Codec compatibility: Android MediaCodec implementations vary by device and Android version; same bitrate/profile may fail on some Pico models but work on Quest. Latency tuning: Network buffer sizes in alvr_sockets are experimentally tuned; cargo defaults may not be optimal for 5GHz Wi-Fi vs. 2.4GHz. C/Rust interop: cbindgen.toml must regenerate bindings if alvr_client_core/src/c_api.rs changes; mismatch causes JNI crashes. Audio sync: alvr_audio requires native PulseAudio libs on Linux (not vendored); missing libraries cause silent failure. Shader compilation: WGSL shaders in alvr/graphics are runtime-compiled; syntax errors only emerge at stream start on some platforms. Edition 2024: Rust 1.92+ required (in Cargo.toml); older toolchains silently fail on edition parsing.

• H.264/HEVC hardware encoding (MediaCodec) — ALVR relies on GPU-accelerated video codecs to stream 90 FPS over Wi-Fi without CPU bottleneck; understanding MediaCodec quirks on Android variants is essential for debugging client crashes
• UDP packet fragmentation and reassembly — ALVR's alvr_packets protocol must split large video frames into UDP datagrams and reconstruct them on the client; packet loss directly causes visual artifacts and requires custom retry logic
• OpenXR tracking and input model — Client-side headsets report 6DOF head pose and controller state via OpenXR (or native APIs); ALVR's alvr_client_core must translate this to SteamVR format, and misalignment causes nausea
• JNI (Java Native Interface) for Rust-Android FFI — ALVR's client app is Java/Kotlin on Android but core logic is Rust; alvr_client_core/src/c_api.rs and cbindgen.toml are the bridge—mistakes crash the headset app
• Network latency budget and frame timing — VR requires motion-to-photon latency <20ms; ALVR's encoding, transmission, and decoding pipeline must be carefully pipelined—overshooting causes motion sickness and is why frame pacing in alvr_server_core is critical
• WGSL/HLSL shader compilation and graphics abstraction — ALVR's alvr/graphics targets both Windows (HLSL via DirectX/D3D12) and Linux (WGSL via Vulkan); shader divergence is a common source of platform-specific visual bugs
• Tokio async/await for real-time networking — ALVR server must multiplex tracking input, video encoding, and network I/O without blocking; Tokio's executor model is core to achieving sub-frame latencies, and deadlocks or CPU starvation here cause streaming hiccups

• monado-org/monado — OpenXR runtime that ALVR targets on some Android platforms; understanding its input/tracking model clarifies ALVR's client-side requirements
• SilentCathedral/openvr-customizations — Companion project for SteamVR integration; ALVR depends on SteamVR driver compatibility tested here
• joglframework/jogl — Graphics binding layer; ALVR's graphics subsystem may share rendering concepts for cross-platform headset output
• Valve/openvr — SteamVR SDK that ALVR server-side links against; protocol changes in OpenVR require ALVR updates
• polygraphene/ALVR — Original ALVR fork predecessor; useful for understanding design decisions and legacy headset support

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 alvr_client_core audio and video decoder modules

The client_core crate handles critical audio and video decoding paths (alvr/client_core/src/audio.rs, alvr/client_core/src/video_decoder/android.rs). Currently there are no visible test files in the repository structure. Adding integration tests would catch regressions in platform-specific codec handling and improve confidence in cross-platform streaming quality.

• [ ] Create alvr/client_core/tests/ directory with integration test suite
• [ ] Add tests for video_decoder module covering Android hardware decoder initialization and frame processing
• [ ] Add tests for audio module covering platform-specific (Windows/Linux) audio pipeline setup
• [ ] Wire tests into CI via .github/workflows/rust.yml to run on pull requests

Add networking protocol validation tests for alvr_packets and alvr_sockets

The networking layer (alvr/packets and alvr/sockets crates) is critical for the streaming protocol. There's no visible test directory for packet serialization/deserialization or socket communication edge cases. Adding tests would catch protocol incompatibilities before release and ensure headset-PC communication reliability.

• [ ] Create alvr/packets/tests/ directory for packet format validation tests
• [ ] Add tests covering packet serialization roundtrips for all major packet types
• [ ] Create alvr/sockets/tests/ directory for socket connection scenarios (timeout, disconnection, reconnection)
• [ ] Add fuzzing or property-based tests for malformed packet handling

Create missing platform-specific CI workflows for macOS and Linux audio backend validation

The audio crate has platform-specific implementations (alvr/audio/src/windows.rs and alvr/audio/src/linux.rs) but .github/workflows/ shows no dedicated audio testing workflow. The main rust.yml workflow likely doesn't validate platform-specific audio compilation. Adding platform matrices would catch audio backend regressions early.

• [ ] Extend .github/workflows/rust.yml or create new audio-backend.yml with matrix strategy for [ubuntu-latest, windows-latest]
• [ ] Add compile check and test steps for alvr_audio crate with --features to isolate platform builds
• [ ] Ensure PipeWire/ALSA (Linux) and WinAudio (Windows) dependencies are properly validated in CI
• [ ] Document required system dependencies for audio testing in CONTRIBUTING.md

• Add unit tests for alvr/packets/src/ wire protocol serialization/deserialization; currently no #[cfg(test)] blocks visible, leaving packet format at risk of regression during refactors.
• Document the codec negotiation handshake in alvr/client_core/src/connection.rs with inline code comments and a design doc; new contributors can't easily understand why certain h.264 profiles are rejected on Pico.
• Extend alvr/audio/src/ with a macOS backend (currently Windows/Linux only per the file structure); this unblocks macOS users and would be ~200 LOC given existing patterns.

• High · Outdated Rust Edition Declaration — Cargo.toml (workspace.package). The Cargo.toml specifies edition = "2024" which does not exist. The latest stable Rust edition is 2021. This will cause build failures and prevents proper compilation with security checks. Fix: Update edition to "2021" to use the latest stable edition with security improvements and proper toolchain support.
• High · Missing Dependency Vulnerability Scanning — .github/workflows/build.yml, .github/workflows/rust.yml. No evidence of cargo-audit, cargo-deny, or similar dependency vulnerability scanning tools in the CI/CD pipeline (build.yml, rust.yml). Dependencies are pulled from external sources without automated security checks. Fix: Implement automated dependency vulnerability scanning using cargo-audit or cargo-deny in CI/CD pipelines. Add these checks to GitHub Actions workflows.
• High · Network Streaming Without Visible Security Validation — alvr/client_core/src/sockets.rs, alvr/client_core/src/connection.rs. ALVR is a VR streaming application that transmits video and audio over Wi-Fi. The codebase structure (client_core/sockets.rs, connection.rs) suggests network communication, but without examining the actual implementation, encryption and authentication mechanisms cannot be verified from the static file listing. Fix: Ensure all network communications use TLS 1.3+, implement certificate pinning, and verify that authentication is enforced before any data transmission. Conduct a detailed code review of socket and connection handling.
• Medium · Strip Disabled in Release Profile — Cargo.toml (profile.release). The release profile configuration sets 'strip = false', which means debug symbols are retained in release binaries. This can expose sensitive information and increase binary size. Fix: Set 'strip = true' in the release profile to remove debug symbols and reduce attack surface in production binaries.
• Medium · Limited Debug Information in Distribution Build — Cargo.toml (profile.release). The distribution profile uses 'debug = "limited"' in the release profile, which may not provide sufficient debugging capabilities while still retaining some symbolic information. This is a trade-off but could be optimized. Fix: Consider using 'debug = "none"' for the distribution profile to completely remove debug symbols, or document why limited debugging is necessary.
• Medium · C API Surface Without Visible Security Boundaries — alvr/client_core/src/c_api.rs, alvr/client_openxr/src/c_api.rs. Multiple C API files (client_core/src/c_api.rs, client_openxr/src/c_api.rs) suggest FFI exposure to C/C++ code. Without examining implementation details, potential issues include buffer overflows, unsafe pointer handling, or missing input validation. Fix: Conduct a thorough security audit of all C API bindings, implement strict input validation, use safe wrapper types, and document all unsafe code blocks with security justifications.
• Medium · Audio Processing Without Visible Security Controls — alvr/audio/src/. Audio modules (alvr/audio/src/windows.rs, alvr/audio/src/linux.rs) may process untrusted network audio data. No evidence of input validation or bounds checking is visible. Fix: Implement strict input validation for audio data, enforce buffer size limits, and add overflow protections. Test with malformed audio inputs.
• Low · Missing SECURITY.md File — Repository root. No SECURITY.md file is evident in the repository root. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file outlining responsible disclosure procedures, contact information, and expected response times for security reports.
• Low · Potential Hardcoded Configuration — alvr/client_core/src/storage.rs. Storage module (alvr/client_core/src/storage.rs) may contain hardcoded paths or default values that could bypass security controls. Fix: Review storage.rs to ensure no hardcoded paths, API endpoints, or credentials exist. Use environment-based configuration

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.