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/ValveSoftware/Proton 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 today
• 12 active contributors
• Distributed ownership (top contributor 36% of recent commits)
• Other licensed
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ 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 ValveSoftware/Proton repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ValveSoftware/Proton.

What it runs against: a local clone of ValveSoftware/Proton — 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 ValveSoftware/Proton | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch proton_11.0 exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

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

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

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

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

# 4. Critical files exist
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "configure.sh" \\
  && ok "configure.sh" \\
  || miss "missing critical file: configure.sh"
test -f "compatibilitytool.vdf.template" \\
  && ok "compatibilitytool.vdf.template" \\
  || miss "missing critical file: compatibilitytool.vdf.template"
test -f "default_pfx.py" \\
  && ok "default_pfx.py" \\
  || miss "missing critical file: default_pfx.py"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

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

Proton is a compatibility layer built on Wine that allows Windows-exclusive games to run natively on Linux through Steam Play. It bridges the Windows API and DirectX to Linux by translating system calls and graphics rendering, functioning as a drop-in replacement for native Linux game ports. Monorepo structure: Wine fork in wine/ directory, DXVK/proton-specific patches, Python bootstrap scripts (default_pfx.py, filelock.py), build orchestration via top-level Makefile and configure.sh that invoke Docker containers (docker/proton.Dockerfile.in), with template configuration in compatibilitytool.vdf.template for Steam integration.

Linux gamers using Steam who want to play Windows-only titles, and advanced users/contributors who need to debug compatibility issues, customize Wine versions for specific games, or submit compatibility reports and fixes.

Production-ready and actively maintained by Valve. The project has substantial infrastructure (Docker build system, extensive docs in docs/, issue templates), regular releases tracked on the wiki changelog, and broad industry adoption through Steam's built-in Proton distribution. Codebase is substantial (~113MB C++/C code) with professional-grade CI and release processes.

Low risk for users (pre-built binaries available), but moderate complexity for contributors: tight integration with Wine and DXVK submodules (tracked in .gitmodules) requires understanding multiple build systems; the SDK container approach (docker/) isolates build but obscures intermediate steps. Relies on maintaining compatibility with rapidly-evolving game titles and multiple GPU vendors (NVIDIA, AMD, Intel).

Actively maintained with ongoing Wine/DXVK updates, branch-based releases (current work on experimental versions visible in README), and continuous compatibility improvements. Issue templates for compatibility-report.md and whitelist-request.md indicate active triage of game compatibility issues.

Clone with: git clone --recurse-submodules https://github.com/ValveSoftware/Proton.git proton && cd proton. Update submodules when switching branches: git submodule update --init --recursive. Build with: make install (requires Docker or Podman installed and running).

Daily commands: make install compiles Proton in an SDK container and installs to Steam's Proton directory. For development: make build creates build artifacts, then symlink the output to ~/.steam/root/compatibilitytools.d/ and restart Steam to test. Intermediate steps logged to container stdout.

• Makefile — Primary build orchestration—defines all compilation targets, Wine integration, and the release artifact pipeline that every contributor must understand
• configure.sh — Configuration entry point that sets up build environment, validates dependencies, and configures Wine/Proton compilation flags
• compatibilitytool.vdf.template — Steam integration manifest—defines how Proton is registered with Steam Client and exposes the tool to end users
• default_pfx.py — Wine prefix initialization script that sets up the default Windows environment and compatibility layers for games
• README.md — Project scope and usage documentation—essential context on Proton's purpose as a Windows-to-Linux compatibility layer for Steam
• .gitmodules — Submodule dependencies (Wine, DXVK, etc.)—critical for understanding the multi-repo build system and component versions
• FEX_Config.json — FEX emulator configuration for ARM64 architecture support—defines CPU/ISA translation behavior for non-x86 targets

Add Support for a New Wine Component or Patch

1. Add the component as a git submodule in .gitmodules or clone into the appropriate directory under proton/ (.gitmodules)
2. Create or modify build rules in Makefile to compile the new component, setting appropriate CFLAGS/LDFLAGS (Makefile)
3. Update configure.sh to validate the component's dependencies and version requirements (configure.sh)
4. Integrate component output into default_pfx.py if it requires Windows-side setup or configuration (default_pfx.py)

Enable Proton for a New Target Architecture (e.g., ARM64)

1. Update FEX_Config.json to define CPU translation rules, ISA targets, and emulation behavior for the new architecture (FEX_Config.json)
2. Modify configure.sh to detect target architecture and apply architecture-specific compiler flags (configure.sh)
3. Update Makefile build rules to compile for multiple architectures and create separate release artifacts (Makefile)
4. Create or update docker/proton.Dockerfile.in with multi-stage builds for cross-compilation toolchains (docker/proton.Dockerfile.in)

Add or Update Debugging Documentation

1. For Windows-side debugging, add Visual Studio Debugger configuration examples to docs/DEBUGGING-WINDOWS.md (docs/DEBUGGING-WINDOWS.md)
2. For Linux-side debugging, add GDB/LLDB commands and Wine-specific debugging environment variables to docs/DEBUGGING-LINUX.md (docs/DEBUGGING-LINUX.md)
3. Reference the updated debugging guides in README.md and update the changelog on the wiki (README.md)

Improve Game Compatibility or Report an Issue

1. Use .github/ISSUE_TEMPLATE/compatibility-report.md to file a new issue with game title, error logs, and Proton version (.github/ISSUE_TEMPLATE/compatibility-report.md)
2. If a workaround requires configuration, add a note to default_pfx.py or create a per-game override in the Wine prefix (default_pfx.py)
3. Document the fix in docs/REBASING_TIPS.md if it involves Wine patches or component updates (docs/REBASING_TIPS.md)

• Wine — Core compatibility layer translating Windows API calls to Linux syscalls; only viable open-source solution at scale
• Proton (Wine fork + patches + components) — Extends Wine with gaming-specific fixes (DXVK for Vulkan, ESYNC for synchronization, etc.) tuned for Steam titles
• FEX-Emu (x86→ARM64 translation) — Enables Proton on ARM64 targets by translating x86/x64 game code without recompilation
• DXVK (DirectX→Vulkan translation) — GPU compatibility layer converting DirectX 9-12 calls to Vulkan for cross-platform graphics on Linux
• Make + Bash scripts — Portable build system for multi-platform cross-compilation without Python/Rust dependency overhead
• Docker — Reproducible, isolated build environments for consistent artifact generation across developer machines
• Git submodules — Pin exact versions of Wine, DXVK, and other components; support fast parallel builds with shared object caches

• Monolithic Wine fork vs. upstream Wine with plugin system

  • Why: Gaming requires aggressive, low-latency patches incompatible with upstream Wine stability guarantees
  • Consequence: Rebasing work is intensive; enables shipping fixes within weeks instead of months

• Static binary packaging vs. system library dependencies

  • Why: Avoid version conflicts with host glibc/LLVM; ensure consistent performance across SteamOS and user distros
  • Consequence: Larger artifact size; simplifies deployment but increases CI build time

• FEX-Emu for ARM64 vs. native ARM64 Wine

  • Why: Most games remain x86/x64; emulation provides immediate compatibility without developer rewrites
  • Consequence: ~20–30% performance overhead on ARM; acceptable trade-off vs. zero ARM64 game support

• Per-game configuration via compatdata vs. global settings

  • Why: Games have wildly different requirements; per-game tuning (ESYNC, staging patches, DXVK versions) is essential
  • Consequence: Users must manage compatibility configs; enables Steam to surface community-tested settings

• Ship Proton from Steam client vs. require manual user build

  • Why: 99.9% of users lack build expertise; Steam distribution is the only viable path to adoption
  • Consequence: Valve must maintain binary release cadence; open-source version is for power users and developers

• Does not support non-Steam games directly (must be launched via Steam Play or manually configured)
• Does not replicate Windows system libraries beyond Wine's scope (no .NET Framework, no DirectX SDK tools)
• Does not provide live patching or zero-downtime updates (requires Steam restart)
• Does not handle DRM/anti-cheat systems—delegates to individual game vendors
• Does not optimize for games already ported natively to Linux (treats them as Windows executables)
• Does not support 32-bit x86 games on native ARM64 (only x64→ARM64 via FEX)

Submodule initialization is mandatory — git clone without --recurse-submodules will fail silently at build time. Docker/Podman must be running and rootless mode recommended per docs (affects file permissions). The SDK container builds are stateful; changing branches requires git submodule update --init --recursive to avoid stale cached builds. Build artifacts land in a container-managed location; make install expects Steam to be properly initialized (looks for standard ~/.steam paths). Wine prefix creation (WINEPREFIX) happens lazily on first game launch, not during Proton build.

• Wine (Windows Emulation Native Environment) — Proton's entire purpose is wrapping and improving Wine; understanding Wine's syscall translation and DLL loading is essential to debugging Proton compatibility
• DirectX-to-Vulkan translation (DXVK/D9VK) — Games use DirectX (proprietary Windows API) but Linux only has Vulkan; DXVK is the bridge layer that must translate GPU calls, making it critical for 3D game compatibility
• WINEPREFIX (Windows Prefix) — Proton isolates each game in a virtual Windows filesystem (WINEPREFIX); understanding prefix creation, registry initialization, and library overrides is necessary for debugging game launch failures
• Containerized builds (Docker/Podman SDK) — Proton uses hermetic SDK containers to ensure reproducible builds across distros; contributors must understand container layer management and mount points to debug build failures
• ABI compatibility and syscall interception — Proton patches Wine to intercept Windows system calls and translate them to Linux equivalents; understanding calling conventions and x86-64 ABI is essential for understanding dispatch overhead
• FEX (Fast Emulation eXchange) — Proton uses FEX to run x86 games on ARM64 Linux; FEX_Config.json controls performance/accuracy tradeoffs, critical for Apple Silicon support
• Vulkan Surface/Swapchain management — Games render via DirectX but final output goes through Vulkan on Linux; Proton must manage window surfaces, vsync, and framebuffer presentation correctly to avoid tearing/stuttering

• ValveSoftware/wine — Valve's Wine fork underlying Proton; contains Windows API translation layer that Proton tracks as a submodule
• doitsujin/dxvk — DirectX-to-Vulkan translation library; critical DXVK submodule providing GPU compatibility for DirectX 9-12 games
• lutris/lutris — Alternative game launcher that bundles Proton and custom Wine builds; competes for same use-case (Windows games on Linux) with different UX
• GloriousEggroll/proton-ge-custom — Community fork of Proton with experimental patches and newer Wine versions; demonstrates how Proton's modularity enables third-party builds
• ValveSoftware/steam-runtime — Dependency runtime for Proton; provides isolated libc and libraries ensuring Proton compatibility across diverse Linux distros

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 GitHub Actions CI workflow for Docker image builds

The repo contains three Dockerfile templates (proton.Dockerfile.in, proton-llvm.Dockerfile.in, llvm-mingw.Dockerfile.in) in docker/ but no automated CI to validate they build successfully on pull requests. This prevents catching Docker build failures early and would ensure contributors don't break the build infrastructure.

• [ ] Create .github/workflows/docker-build.yml to run docker build on each Dockerfile template for PRs
• [ ] Add build matrix for the three Dockerfile variants in docker/context
• [ ] Validate that patches in docker/context/*.patch apply cleanly during CI
• [ ] Document the Docker build process in docker/README.md with CI badge

Add validation tests for compatibilitytool.vdf.template

The compatibilitytool.vdf.template file is critical for Steam integration but has no validation. A malformed VDF template would break Proton's registration with Steam. Adding tests would catch syntax errors and schema violations before release.

• [ ] Create a Python test script (tests/test_vdf_template.py) to parse and validate compatibilitytool.vdf.template syntax
• [ ] Validate required fields like 'install_dir', 'from_oslist', 'to_oslist' are present
• [ ] Add GitHub Actions workflow (.github/workflows/validate-vdf.yml) to run VDF validation on every PR
• [ ] Add documentation in docs/ about VDF template requirements for maintainers

Create comprehensive debugging guide index in docs/

The repo has docs for specific debugging scenarios (DEBUGGING-LINUX.md, DEBUGGING-WINDOWS.md) but no overview document linking them together. Contributors adding new debugging scenarios have no clear place to document them, and users don't know what debugging docs exist.

• [ ] Create docs/DEBUGGING.md as a master index linking to DEBUGGING-LINUX.md, DEBUGGING-WINDOWS.md, and other debug docs
• [ ] Add sections for common debugging workflows (crashes, performance, audio, controllers) with cross-references to existing docs
• [ ] Reference CONTROLLERS.md, THREAD_PRIORITY.md, PRIME.md in the index since they're debugging-adjacent
• [ ] Add troubleshooting template in .github/ISSUE_TEMPLATE/ referencing the debugging guide for better issue reports

• Add integration test suite in tests/ directory: currently no obvious test harness visible in file list; create pytest fixtures to validate that a compiled Proton can launch a minimal DirectX 11 stub executable, ensuring build pipeline correctness before release.
• Expand docs/DEBUGGING-WINDOWS.md with screenshots for GDB attachment workflow: currently has placeholder image references (docs/img/vs_*.png) but GDB+gdbserver steps missing; document how to attach gdb to running game process via SSH to diagnose crashes.
• Create docs/BUILDING_ON_UNSUPPORTED_DISTROS.md: Makefile assumes Docker/Podman; add guide for manual compilation on Alpine/musl libc, documenting missing pkg-config variables and cross-compile flags required for non-glibc systems.

The Proton compatibility tool repository demonstrates reasonable security posture for an open-source compatibility layer. Primary concerns revolve around supply chain security (submodule management), Python script safety, and documentation gaps. No obvious hardcoded secrets or credentials were identified in the file structure. The codebase lacks explicit security policies and documentation, which is typical but should be addressed. Docker infrastructure appears minimally configured with limited attack surface. Recommendations focus on strengthening dependency management, securing Python script execution, and establishing formal security disclosure policies.

• Medium · Potential Third-Party Dependency Risks in Submodules — .gitmodules. The repository uses .gitmodules for managing submodules (Wine and additional components). Submodules can introduce supply chain risks if not properly pinned to specific commits or if they reference external repositories that may be compromised. No visibility into dependency versioning or lock files was provided. Fix: Ensure all submodules are pinned to specific commit hashes rather than branches. Implement automated dependency scanning for known CVEs in Wine and related components. Consider using git submodule integrity checks in CI/CD pipeline.
• Medium · Docker Build Context Potentially Exposed — docker/context/. The docker/context directory contains patch files (.patch extension) for LLVM components. While the .gitkeep suggests controlled content, the presence of build context files alongside Dockerfiles increases the risk of accidentally committing sensitive build artifacts or intermediate files. Fix: Add docker/context/* to .gitignore except for explicitly needed files. Implement Docker layer scanning in CI/CD. Review patch files for embedded credentials or sensitive data before committing.
• Low · Python Script Security - File and Process Handling — default_pfx.py, filelock.py, fonts/scripts/merge.py. The presence of Python scripts (default_pfx.py, filelock.py, fonts/scripts/merge.py) without visible security controls could introduce risks if they process untrusted input or handle privileged operations. Python scripts are common attack vectors for privilege escalation in compatibility tools. Fix: Implement input validation and sanitization in all Python scripts. Avoid using subprocess with shell=True. Apply principle of least privilege. Conduct security code review of file operation and process handling. Use static analysis tools like bandit on Python code.
• Low · Missing SECURITY.md or Security Policy — Repository root. The repository lacks a SECURITY.md file or documented security policy for vulnerability disclosure. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with instructions for responsible vulnerability disclosure, contact information for security issues, and security update policies.
• Low · Hardcoded Configuration in Template Files — compatibilitytool.vdf.template, FEX_Config.json. The compatibilitytool.vdf.template and FEX_Config.json files may contain default configurations. If these include insecure defaults or paths, they could create security issues in deployed instances. Fix: Review default configurations for security implications. Document any required security adjustments. Avoid hardcoding sensitive paths or credentials in templates. Use environment variables for runtime configuration.
• Low · Documentation of Debugging Tools Without Security Guidance — docs/DEBUGGING-WINDOWS.md, docs/DEBUGGING-LINUX.md. The DEBUGGING-WINDOWS.md and DEBUGGING-LINUX.md files document debugging procedures but may not emphasize security implications of running games with debugging enabled or exposing debug symbols. Fix: Add security warnings to debugging documentation about the risks of enabling debug features. Document proper isolation practices when debugging untrusted game code. Emphasize disabling debug features in production environments.

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.