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/nomi-san/parsec-vdd 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 — Slowing — last commit 9mo ago

• Last commit 9mo ago
• 7 active contributors
• MIT licensed
• CI configured
• ⚠ Slowing — last commit 9mo ago
• ⚠ Single-maintainer risk — top contributor 93% 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 nomi-san/parsec-vdd repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nomi-san/parsec-vdd.

What it runs against: a local clone of nomi-san/parsec-vdd — 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 nomi-san/parsec-vdd | 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 ≤ 311 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "nomi-san/parsec-vdd(\\.git)?\\b" \\
  && ok "origin remote is nomi-san/parsec-vdd" \\
  || miss "origin remote is not nomi-san/parsec-vdd (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 "app/Program.cs" \\
  && ok "app/Program.cs" \\
  || miss "missing critical file: app/Program.cs"
test -f "app/Vdd/Controller.cs" \\
  && ok "app/Vdd/Controller.cs" \\
  || miss "missing critical file: app/Vdd/Controller.cs"
test -f "app/Device.cs" \\
  && ok "app/Device.cs" \\
  || miss "missing critical file: app/Device.cs"
test -f "app/Display.cs" \\
  && ok "app/Display.cs" \\
  || miss "missing critical file: app/Display.cs"
test -f "app/Config.cs" \\
  && ok "app/Config.cs" \\
  || miss "missing critical file: app/Config.cs"

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

Parsec-VDD is a standalone C# WPF application that manages virtual display creation and configuration on Windows 10+ using the Parsec Virtual Display Driver (built on IddCx API). It enables users to add up to 16 virtual displays per adapter with support for 4K resolution and 240Hz refresh rates, independent of the main Parsec streaming application. Monolithic WPF desktop app structure: app/ contains the main UI (MainWindow.xaml, Components/), business logic (Device.cs, Display.cs, Config.cs), VDD driver abstraction (app/Vdd/ with Core.cs as the entry point), and CLI support (CLI.cs). The core/ directory holds C++ header definitions (parsec-vdd.h) and a demo (vdd-demo.cc). Language localization via resource files in app/Languages/ (en.xaml, vi.xaml, zh.xaml).

System administrators and game streaming enthusiasts who need to create virtual displays on headless or remote Windows machines for streaming setups (Parsec Teams/Warp customers), particularly those managing multi-monitor configurations without physical hardware.

Actively developed and production-ready. The project has 142K lines of C# code, organized CI/CD pipelines (build.yml, publish.yml), and a mature release distribution model via GitHub Releases. No visible test suite in the repo structure suggests testing may be manual or external.

Single-maintainer risk (nomi-san) with potential Windows driver-level dependencies that could break between OS updates. The driver interaction layer (app/Vdd/Core.cs, app/Vdd/Controller.cs) depends on undocumented or Parsec-specific IO control codes, making the codebase fragile if Parsec changes internal APIs. No visible unit tests increase regression risk.

Active GitHub Actions CI/CD pipeline with build.yml and publish.yml workflows suggest ongoing releases. The README mentions version tracking and download statistics, indicating regular version bumps. Specific recent commits not visible in file list, but the publish workflow suggests automated release deployment.

Clone and build via Visual Studio: git clone https://github.com/nomi-san/parsec-vdd.git && cd app && dotnet build ParsecVDisplay.csproj (or open ParsecVDisplay.csproj in Visual Studio 2019+). The project is a .NET Framework WPF app, so ensure Windows SDK and .NET Framework developer tools are installed. Run via dotnet run or execute the built .exe from bin/Release/.

Daily commands: Open app/ParsecVDisplay.csproj in Visual Studio, build as Release, or use command line: cd app && dotnet build -c Release && bin/Release/ParsecVDisplay.exe. The app requires Windows 10+ and administrator privileges (see Properties/App.manifest). Must run connected to a Parsec session for full functionality.

• app/Program.cs — Application entry point; initializes the WPF app, CLI mode, and system tray integration—all contributors must understand the startup flow.
• app/Vdd/Controller.cs — Core abstraction for VDD device control (create, remove, update displays); essential for understanding how the app communicates with the virtual display driver.
• app/Device.cs — Manages enumeration and state of display devices; load-bearing for device discovery and display configuration logic.
• app/Display.cs — Data model representing a virtual display with resolution, position, and persistence; used throughout UI and backend logic.
• app/Config.cs — Persists application settings and display configurations to disk; critical for state management across sessions.
• app/MainWindow.xaml.cs — Primary UI controller for the display management interface; main interaction point for end users.
• core/parsec-vdd.h — C++ header defining the native VDD API that the C# wrapper uses; essential for understanding the native interop layer.

Add a new display resolution preset

1. Define the preset resolution in the Display.cs data model as a static constant or enum value (app/Display.cs)
2. Add a UI button or dropdown option in MainWindow.xaml that invokes the preset (app/MainWindow.xaml.cs)
3. Call Controller.Create() with the preset dimensions and call Config.Save() to persist (app/Vdd/Controller.cs)
4. Add localized labels for the preset in each language file (en.xaml, vi.xaml, zh.xaml) (app/Languages/en.xaml)

Add a new CLI command

1. Parse the command name and arguments in CLI.cs using the existing argument splitting pattern (app/CLI.cs)
2. Implement the business logic using Controller and Device methods (app/Vdd/Controller.cs)
3. Return output via Console.WriteLine or throw a descriptive error using Errors.cs (app/Vdd/Errors.cs)
4. Document the command in VDD_CLI_USAGE.md (docs/VDD_CLI_USAGE.md)

Add a new UI settings page

1. Create a new XAML file inheriting from CustomPage.xaml in the app root or Components folder (app/Components/CustomPage.xaml.cs)
2. Bind UI controls to properties in the code-behind, reading/writing via Config.cs (app/Config.cs)
3. Add navigation to the new page from MainWindow.xaml.cs using frame or tab control (app/MainWindow.xaml.cs)
4. Add localized labels for all controls in en.xaml, vi.xaml, and zh.xaml (app/Languages/en.xaml)

Add error handling for a new VDD failure mode

1. Define the error code constant in Errors.cs and add a mapping to human-readable message (app/Vdd/Errors.cs)
2. Update Controller.cs to check for the error code after native VDD calls (app/Vdd/Controller.cs)
3. Display the error message to the user via Helper.ShowErrorDialog() in the UI layer (app/Helper.cs)

• WPF (C# / XAML) — Cross-platform GUI framework for Windows; native .NET integration and data binding simplify the display management UI.
• P/Invoke (Native Interop) — Required to call the native Parsec VDD driver DLL; provides low-level control over virtual display creation.
• WMI (Windows Management Instrumentation) — Standard Windows API for querying device and display information; avoids reinventing device enumeration.
• JSON (Config Persistence) — Human-readable format for storing display configurations; simple serialization and no database dependency.
• System Tray Integration — Allows the app to run in the background and respond to power events without a visible window.

• Standalone C# wrapper instead of Parsec client integration

  • Why: Provides independence from the main Parsec application and allows granular VDD control.
  • Consequence: Duplicates some VDD logic but gains flexibility; requires users to manage the app separately from Parsec.

• P/Invoke instead of a managed C++/CLI layer

  • Why: Simpler deployment and fewer dependencies; direct DLL binding.
  • Consequence: Error handling and interop must be manually managed; less type safety for native calls.

• JSON file storage instead of registry or database

  • Why: User-portable config and easier debugging.
  • Consequence: No built-in transaction safety; requires external locking for concurrent access.

• Three separate language XAML files instead of a resource manager

  • Why: XAML-native localization is straightforward for small projects.
  • Consequence: Scales poorly beyond 3 languages; duplication of keys across files.

• Does not provide a Linux/macOS port; Windows-only virtual display driver.
• Does not replace the Parsec streaming client; VDD is a lower-layer abstraction.
• Does not offer real-time 3D rendering; purely a display enumeration and configuration tool.
• Does not handle GPU-specific optimizations; defers to the native VDD driver.
• Does not manage network streaming or game streaming protocols; those remain Parsec client responsibilities.

The driver must be installed separately (not bundled in app)—add/remove virtual display operations fail silently if Parsec VDD driver is not present or outdated. IOCTL codes in Core.cs are magic numbers; changing them breaks driver communication. Displays must be pinged periodically via Controller.cs or they auto-disconnect after ~1 second—no persistent storage on driver side. The app requires admin privileges (manifest enforces this) but WPF may require specific Registry permissions for some config scenarios. No direct display mode changing; the app relies on users calling Win32 Display API separately (ChangeDisplaySettingsEx), which is documented but not automated.

• Indirect Display Driver (IddCx) — IddCx is the Windows API that Parsec VDD builds on; understanding its capabilities and constraints directly impacts what display configurations the app can create and manage.
• IOCTL (Input/Output Control) Codes — The app communicates with the VDD driver entirely via IOCTL commands marshaled in Core.cs; misunderstanding IOCTL struct packing or codes breaks all driver interactions.
• P/Invoke (Platform Invoke) — The C# app calls Windows kernel APIs (DeviceIoControl, EnumDisplayDevices) via P/Invoke declarations; incorrect marshaling causes crashes or silent failures.
• WPF Data Binding & XAML — The UI in MainWindow.xaml and Components/ relies on WPF's data binding model; changes to display state must trigger PropertyChanged notifications or UI won't update.
• Display Mode (Resolution, Refresh Rate, Color Depth) — Virtual displays are created with a specific mode; the app doesn't set modes directly but must expose the Win32 Display API (ChangeDisplaySettingsEx) for users or provide a managed wrapper.
• Heartbeat/Ping Keep-Alive Pattern — Virtual displays auto-disconnect after ~1 second without periodic pings; the Controller.cs heartbeat loop is critical to display persistence and requires careful thread synchronization.
• Tray Icon / System Tray Integration — The app uses Windows system tray for background operation (Tray.cs); understanding tray lifecycle and message pump integration is needed for headless or unattended scenarios.

• DesktopEditionWin/usbmmidd_v2 — Alternative Indirect Display Driver (IddCx) implementation for virtual displays on Windows; useful reference for IOCTL patterns and IddCx API usage
• MolotovCherry/Virtual-Display-Driver — Open-source virtual display driver project; educational reference for lower-level driver implementation that Parsec VDD likely mirrors
• Parsec-Cloud-Preparation-Tool/Parsec-Cloud-Preparation-Tool — Companion tool for Parsec server setup; may use overlapping VDD initialization logic or config schemas
• moonlight-stream/moonlight-qt — Alternative game streaming client that may benefit from or use virtual display drivers for similar remote gaming scenarios
• ratibor78/virtualDisplayDriver — Older IddCx-based virtual display driver; historical reference for driver evolution and API stability concerns

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 unit tests for Vdd/Core.cs and Vdd/Controller.cs

The core VDD functionality in app/Vdd/ has no corresponding test files. These modules handle critical driver operations (device creation, display management, error handling). Adding unit tests would improve reliability, catch regressions, and serve as documentation for the VDD API contract.

• [ ] Create app/Vdd/Tests/ directory with CoreTests.cs and ControllerTests.cs
• [ ] Test key methods in Core.cs (initialization, device enumeration, display creation)
• [ ] Test error handling paths in Controller.cs with Errors.cs enum values
• [ ] Add test project to ParsecVDD.csproj and integrate with build.yml CI workflow
• [ ] Verify tests run in GitHub Actions (add test step to .github/workflows/build.yml)

Add comprehensive CLI documentation and examples in docs/

docs/VDD_CLI_USAGE.md exists but the app/CLI.cs implementation is not reflected in user-facing documentation. Contributors and users lack clear examples of CLI argument parsing, flags, and output behavior. This would reduce support questions and improve discoverability.

• [ ] Review app/CLI.cs to extract all supported command-line arguments and flags
• [ ] Expand docs/VDD_CLI_USAGE.md with sections: Basic Usage, Advanced Examples, Exit Codes, Troubleshooting
• [ ] Add example commands for common workflows (create display, list devices, remove display)
• [ ] Document the relationship between CLI.cs parsing and app/Config.cs configuration
• [ ] Add a CLI section to README.md with quick reference

Add integration tests for Display.cs device lifecycle and MirrorWindow.cs window management

app/Display.cs and app/MirrorWindow.cs handle critical UI and display lifecycle logic but lack automated tests. These modules interact with Windows display APIs and window management, making them prone to subtle bugs. Integration tests would verify display creation/destruction and mirror window behavior across restarts.

• [ ] Create app/Tests/DisplayLifecycleTests.cs to test Display.cs methods: create, remove, refresh, enumerate
• [ ] Create app/Tests/MirrorWindowTests.cs to verify MirrorWindow.cs window creation and property synchronization
• [ ] Add setup/teardown in tests to handle mock Windows display APIs or use a test harness
• [ ] Test error scenarios from app/Vdd/Errors.cs to ensure graceful handling
• [ ] Integrate into build.yml with a dedicated test job that runs before publish

• Add unit tests for app/Vdd/Core.cs IOCTL marshaling—currently untested; mock the driver interface to validate struct packing and error code parsing for the major IOCTL operations.
• Create automated tests for app/Config.cs serialization/deserialization—test edge cases like missing settings files, corrupted JSON, and version migrations to prevent user config loss.
• Document the VDD driver setup and IOCTL contract in docs/ (beyond PARSEC_VDD_SPECS.md)—add a developer guide explaining IOCTL codes, required driver version, and troubleshooting steps for driver communication failures.

The Parsec Virtual Display Driver application has moderate security concerns primarily in kernel-mode driver interaction, update mechanisms, and privilege management. The codebase lacks visible input validation patterns, cryptographic verification for updates, and proper privilege escalation controls. As a system-level driver application, this requires heightened security standards. Critical recommendations include: (1) implement update signature verification, (2) add comprehensive input validation, (3) audit kernel/driver interactions for safety, (4) enforce UAC properly, and (5) conduct security review of P/Invoke declarations. No hardcoded secrets or obvious injection vulnerabilities were detected from the provided file structure, but actual code review is necessary.

• High · Potential Unsafe Driver/Kernel Code Interaction — app/Vdd/Controller.cs, app/Vdd/Core.cs, core/parsec-vdd.h. The codebase interacts with a Virtual Display Driver (VDD) through core components (parsec-vdd.h, vdd-demo.cc, Core.cs). Kernel-mode driver interactions can be exploited if not properly validated. The Vdd/Controller.cs likely contains unvalidated parameter passing to the driver. Fix: Implement strict input validation and sanitization for all parameters passed to the VDD. Use secure driver communication patterns, validate return codes, and ensure proper error handling. Consider code review by kernel security specialists.
• High · Automatic Update Mechanism Without Integrity Verification — app/Updater.cs. The Updater.cs component handles application updates. Without evidence of signature verification or hash validation, this could be vulnerable to man-in-the-middle attacks or unauthorized code execution if the update source is compromised. Fix: Implement cryptographic signature verification for all downloaded updates. Use HTTPS with certificate pinning. Verify SHA-256 hashes of binaries before execution. Consider using Windows Update services or signed packages.
• Medium · Admin Privilege Requirement Not Clearly Validated — app/App.xaml.cs, app/Properties/App.manifest, app/Program.cs. The application appears to require admin privileges (indicated by admin.png resource and potential driver installation needs), but there's no visible UAC prompt validation or privilege level checks before executing privileged operations. Fix: Explicitly check for admin privileges at startup. Request UAC elevation only for operations that require it. Document privilege requirements clearly. Implement principle of least privilege - only elevate when necessary.
• Medium · Potential Unsafe COM/Interop Calls — app/Vdd/Core.cs. WPF application with driver interaction (Core.cs) may contain P/Invoke or COM interop calls. Without proper declaration and validation, this can lead to buffer overflows or privilege escalation. Fix: Audit all P/Invoke declarations for correct signatures. Use SafeHandle wrappers for native handles. Validate all native return values. Consider using managed alternatives where possible.
• Medium · Insufficient Input Validation in CLI — app/CLI.cs. The CLI.cs component handles command-line arguments which are often a vector for injection attacks. No obvious sanitization pattern is visible in the file structure. Fix: Implement comprehensive input validation for all CLI parameters. Use allowlists for accepted values. Sanitize parameters before passing to system calls or driver operations. Log suspicious inputs.
• Low · Missing HTTPS Enforcement for Remote Resources — README.md, app/Updater.cs. The README contains tracking pixel and GitHub asset URLs. If Updater.cs fetches resources over HTTP, this could be vulnerable to MITM attacks. Fix: Enforce HTTPS for all remote resource fetches. Use certificate pinning for critical update checks. Validate all external content origins.
• Low · No Visible Secret Management — app/App.config, app/Config.cs, .gitignore. Configuration files (App.config, Config.cs) may contain sensitive data without encryption. No .gitignore patterns explicitly excluding sensitive files are visible. Fix: Encrypt sensitive configuration values at rest. Use secure credential storage (Windows Credential Manager). Never commit secrets to version control. Review .gitignore for comprehensive coverage.

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.