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/FEX-Emu/FEX 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 the board

• Last commit 1d ago
• 8 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• CI configured
• Tests present

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

What it runs against: a local clone of FEX-Emu/FEX — 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 FEX-Emu/FEX | 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 ≤ 31 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "FEX-Emu/FEX(\\.git)?\\b" \\
  && ok "origin remote is FEX-Emu/FEX" \\
  || miss "origin remote is not FEX-Emu/FEX (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 "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "CodeEmitter/CodeEmitter/Emitter.h" \\
  && ok "CodeEmitter/CodeEmitter/Emitter.h" \\
  || miss "missing critical file: CodeEmitter/CodeEmitter/Emitter.h"
test -f "External/SoftFloat-3e/include/SoftFloat-3e/softfloat.h" \\
  && ok "External/SoftFloat-3e/include/SoftFloat-3e/softfloat.h" \\
  || miss "missing critical file: External/SoftFloat-3e/include/SoftFloat-3e/softfloat.h"
test -f ".github/workflows/ccpp.yml" \\
  && ok ".github/workflows/ccpp.yml" \\
  || miss "missing critical file: .github/workflows/ccpp.yml"
test -f "Data/ThunksDB.json" \\
  && ok "Data/ThunksDB.json" \\
  || miss "missing critical file: Data/ThunksDB.json"

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

FEX is a high-performance usermode x86/x86-64 emulator for ARM64 Linux that translates and executes x86 binaries natively on Arm64 processors. It bridges the gap between x86 applications (including Windows games via Wine/Proton) and ARM64 hardware, with forward-compatible API calls to host libraries (OpenGL, Vulkan) and an experimental code cache to reduce runtime overhead. Monolithic single-repo structure: CodeEmitter/ contains VIXL-based ARM64 code generation (ALUOps.inl, ASIMDOps.inl, SystemOps.inl), src/ (inferred) contains the core x86 decoder and interpreter, Data/ holds configuration templates (AppConfig/client.json, CI thunks definitions), Scripts/ has deployment tooling (InstallFEX.py). CMake build system with target toolchains for aarch64, mingw, x86_32.

ARM64 Linux users (Pi enthusiasts, Snapdragon device owners, Apple Silicon users) who want to run x86 desktop applications and games; game developers and emulation enthusiasts contributing performance optimizations; system integrators embedding FEX into custom distributions or handheld gaming devices.

Actively developed and production-ready: 12M+ lines of C++ and Assembly, comprehensive CI/CD with multiple GitHub Actions workflows (ccpp.yml, glibc_fault.yml, wine_build, steamrt4 testing), supports official distributions (Ubuntu 22.04+, Fedora, Arch), and includes user-facing FEXConfig GUI. Recent activity evident in per-app configuration system and code cache features, but still experimental in some subsystems.

Moderate complexity risk: 7.8M+ lines of C++, heavy Assembly dependencies (4.3M lines), requires careful x86 ISA semantics implementation with potential for subtle correctness bugs across multiple CPU features. Dependency on external tools (Zydis for disassembly, VIXL for code generation) and RootFS artifacts adds deployment friction; single domain (x86→ARM64 translation) means architectural changes affect entire codebase.

Active work on memory model emulation tuning (per-app config system), code cache stabilization, Wine/Proton integration (wine_build workflows, steamrt4 testing), and CI expansion (glibc_fault.yml indicates malloc/glibc compliance testing). GitHub workflows show recent focus on mingw cross-compilation and vixl_simulator verification.

git clone --recursive https://github.com/FEX-Emu/FEX.git
cd FEX
mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=../Data/CMake/toolchain_aarch64.cmake
make -j$(nproc)
sudo make install

Or use the Ubuntu PPA: curl --silent https://raw.githubusercontent.com/FEX-Emu/FEX/main/Scripts/InstallFEX.py | python3

Daily commands:

1. Install FEX as above. 2. Download/generate x86-64 RootFS: FEXRootFSFetcher or manual setup (wiki.fex-emu.com). 3. Run x86 binary: FEX /path/to/x86/binary or configure per-app in FEXConfig GUI. For Wine games: FEX + Wine/Proton under the RootFS.

• CMakeLists.txt — Root build configuration defining the entire project structure, dependencies, and compilation flags for the x86/x86-64 emulator on ARM64.
• CodeEmitter/CodeEmitter/Emitter.h — Core ARM64 code emission abstraction that translates x86 instructions to native ARM64 machine code—essential for understanding the JIT compilation pipeline.
• External/SoftFloat-3e/include/SoftFloat-3e/softfloat.h — Floating-point emulation library interface used throughout the emulator for accurate x86 FPU behavior on ARM64.
• .github/workflows/ccpp.yml — Primary CI/CD pipeline defining build, test, and artifact generation workflows that validate all pull requests and releases.
• Data/ThunksDB.json — Configuration database for library forwarding (thunks) that redirects x86 API calls to ARM64 host libraries, critical for performance optimization.
• Data/CMake/toolchain_aarch64.cmake — ARM64 cross-compilation toolchain configuration that enables building the emulator on and for ARM64 Linux targets.

Add Support for a New ARM64 Instruction in the Emitter

1. Define the instruction encoding in the appropriate .inl file (e.g., ALUOps.inl for arithmetic) (CodeEmitter/CodeEmitter/ALUOps.inl)
2. Declare the public method in the Emitter header (CodeEmitter/CodeEmitter/Emitter.h)
3. Use Vixl utilities if needed for encoding validation (CodeEmitter/CodeEmitter/VixlUtils.inl)
4. Add a test case in the CI workflow (.github/workflows/ccpp.yml)

Add a New Library Thunk for API Forwarding

1. Register the library and target functions in the thunk database (Data/ThunksDB.json)
2. Create an application config if needed for specific behavior (Data/AppConfig/client.json)
3. Verify with CI integration tests (.github/workflows/ccpp.yml)

Add Support for a New Target Platform/Toolchain

1. Create a new toolchain file in Data/CMake/ (Data/CMake/toolchain_aarch64.cmake)
2. Update the root CMakeLists.txt to include the new toolchain (CMakeLists.txt)
3. Add a corresponding CI workflow to test on the new platform (.github/workflows/ccpp.yml)

Implement a New Floating-Point Operation

1. Add the operation implementation in External/SoftFloat-3e/src/ (External/SoftFloat-3e/src/extF80_add.c)
2. Declare the function in the public header (External/SoftFloat-3e/include/SoftFloat-3e/softfloat.h)
3. Update CMakeLists.txt in the SoftFloat module (External/SoftFloat-3e/CMakeLists.txt)

• ARM64 JIT Code Emission (Vixl-based) — Converts x86/x86-64 instructions on-the-fly to native ARM64 machine code for minimal overhead and maximum compatibility with ARMv8.0+ hardware.
• SoftFloat-3e Library — Provides accurate software floating-point emulation (80-bit extended precision, 128-bit IEEE 754) required for x86 FPU compatibility on ARM64.
• Library Thunking & API Forwarding — Redirects x86 API calls (OpenGL, Vulkan, etc.) directly to ARM64 host libraries, reducing emulation overhead and improving performance.
• Per-App Configuration System — Allows fine-grained tuning (e.g., disabling memory model emulation) to maximize performance per application without global overhead.
• CMake Cross-Compilation — Enables flexible build targeting across ARM64, x86-64, x86-32, and MinGW toolchains from a single build definition.

• Software floating-point (SoftFloat) instead of ARM NEON/SVE FPU

  • Why: Ensures 100% x86 FPU semantic compatibility including edge cases, NaN handling, and extended precision.
  • Consequence: Floating-point operations are slower than direct ARM FPU; mitigated by caching and selective forwarding.

• Full x86 memory model emulation (optional but default)

  • Why: Guarantees correct behavior for low-level memory-ordering-dependent code (e.g., lock-free algorithms).
  • Consequence: Higher CPU overhead; apps can disable via per-app config if memory model compliance is not required.

• Usermode-only emulation (no kernel emulation)

  • Why: Simplifies architecture and reduces complexity by letting the native Linux kernel handle system calls.
  • Consequence: Cannot run bare-metal code or non-Linux x86 binaries; good fit for typical applications.

• On-demand JIT compilation vs. ahead-of-time compilation

  • Why: Simplifies code distribution and avoids pre-compilation overhead; experimental code cache layer reduces in-game stuttering.
  • Consequence: Initial execution has slight overhead; cache hits after warm-up.

• Does not emulate the x86 kernel or system call layer (usermode only).
• Does not support bare-metal or UEFI x86 code.
• Does not run non-Linux x86 operating systems or Windows natively (works with Wine/Proton for Windows binaries).
• Does not provide real-time or deterministic performance guarantees.

1. RootFS requirement: FEX needs a prepared x86-64 Linux rootfs (downloaded or manually built) — binaries cannot run without this. 2. Recursive submodules: --recursive clone flag is critical; missing submodules (likely VIXL, Zydis) breaks build. 3. Toolchain selection: CMake requires explicit -DCMAKE_TOOLCHAIN_FILE= to target aarch64 on x86 hosts or vice versa; default assumes native build. 4. Memory model complexity: Per-app configuration (AppConfig/*.json) disables expensive memory model emulation by default for performance—incorrect settings cause silent correctness regressions in multi-threaded code.

• Dynamic Binary Translation (DBT) / JIT — FEX's core: x86 instructions are decoded and translated to ARM64 at runtime; understanding when/how translation happens affects performance optimization strategies
• ARM64 ISA / AArch64 Instructions — Target architecture for all CodeEmitter .inl files; new contributors must understand ARM64 register model, addressing modes, and SIMD capabilities to implement x86→ARM64 mappings correctly
• x86 ISA Semantics (32-bit & 64-bit) — Source architecture being emulated; correctness of ALUOps, LoadstoreOps, SystemOps depends on deep knowledge of x86 flags, segmentation, memory model, interrupts, and privilege levels
• SIMD / NEON / SVE (Arm Scalable Vector Extension) — ASIMDOps.inl and SVEOps.inl map x86 SSE/AVX to ARM NEON/SVE; critical for multimedia, game engines, and scientific code performance
• Code Cache / Instruction Cache — Experimental feature mentioned in README to reduce runtime overhead and in-game stuttering; understanding cache invalidation and eviction strategy affects FEX's responsiveness on constrained ARM devices
• Syscall Forwarding / Thunking — Data/CI/{FEXLinuxTestsThunks,GLThunks,VulkanThunks}.json files define which x86 syscalls/library calls forward to ARM64 host libraries; reduces emulation cost for I/O and graphics APIs
• Cross-Compilation Toolchains (aarch64, mingw, x86_32) — Data/CMake/toolchain_*.cmake files configure builds for multiple targets; FEX maintainers must manage ABI compatibility and libc differences across platforms, affecting RootFS and deployment strategy

• qemu/qemu — Canonical usermode x86 emulator for Linux (qemu-user); FEX is a faster, ARM64-focused alternative with Wine/Proton integration
• box64/box64 — Another x86-64 emulator for ARM64, written in C with lower-level syscall handling; direct competitor targeting similar use cases
• google/vixl — ARM code generation library that FEX depends on (CodeEmitter/ directly wraps it); understanding VIXL is essential for ISA extensions
• zyantific/zydis — x86/x86-64 disassembler/decoder library integrated into FEX; used for instruction decoding before translation
• ValveSoftware/Proton — Wine fork used to run Windows games under FEX; FEX CI explicitly tests Proton compatibility (wine_build, steamrt4 workflows)

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 comprehensive CI workflow for SVE (Scalable Vector Extension) instruction coverage

The repo has SVEOps.inl in CodeEmitter but no dedicated CI workflow testing SVE instructions. Given that FEX targets ARM64 and SVE is a critical ARM64 feature, a dedicated workflow (.github/workflows/sve_instructions.yml) would catch regressions in SVE code emission and ensure compatibility across different ARM64 implementations that may or may not support SVE.

• [ ] Create .github/workflows/sve_test.yml that builds FEX with SVE support enabled
• [ ] Add test cases in CodeEmitter/ that validate SVEOps.inl instruction encoding correctness
• [ ] Reference existing patterns from .github/workflows/vixl_simulator.yml and instcountci.yml
• [ ] Document expected SVE instruction patterns in Data/CI/ configuration

Create unit tests for CodeEmitter instruction validation across all operation types

CodeEmitter has ALUOps.inl, ASIMDOps.inl, BranchOps.inl, LoadstoreOps.inl, ScalarOps.inl, and SystemOps.inl but there's no evidence of dedicated unit tests validating the correctness of emitted ARM64 machine code. This is critical since incorrect code emission would silently break emulation.

• [ ] Create tests/CodeEmitterTests/ directory structure
• [ ] Add test files validating each .inl file: test_alu_ops.cpp, test_asim_ops.cpp, test_branch_ops.cpp, etc.
• [ ] Use CodeEmitter/CodeEmitter/Emitter.h to emit instructions and validate against expected machine code bytes
• [ ] Reference Buffer.h for instruction buffer management in tests
• [ ] Integrate tests into CMakeLists.txt build system

Document and expand AppConfig system with per-architecture configuration support

Data/AppConfig/ has client.json and steamwebhelper.json but lacks documentation on the configuration schema and no support for architecture-specific settings (32-bit vs 64-bit, SVE vs non-SVE ARM64). This limits the per-app tuning mentioned in the README.

• [ ] Create docs/AppConfig-Schema.md documenting the JSON schema with all valid keys, types, and defaults
• [ ] Add schema validation tool in Data/AppConfig/ (e.g., config_validator.py) referenced in CI
• [ ] Extend Data/CMake/version_to_variables.cmake to include architecture variant detection for config loading
• [ ] Add example configs for common use cases (e.g., Data/AppConfig/examples/game-with-sve.json)
• [ ] Reference in .github/workflows/pr-code-format.yml to validate config files in PRs

• Add unit tests for CodeEmitter/CodeEmitter/ScalarOps.inl floating-point edge cases (denormals, NaN handling, rounding modes) — currently no dedicated test file visible; impacts scientific/game physics correctness.
• Document the x86 ISA coverage matrix in docs/ (which instructions are implemented vs. stubbed in each .inl file) — source outline exists but no coverage checklist; contributors can't easily identify missing opcodes.
• Extend Data/CI/VulkanThunks.json and GLThunks.json with additional extension definitions (e.g., EXT_sparse_texture, EXT_debug_marker) — current thunk files likely incomplete; blocks vendor-specific graphics features in games.

The FEX emulator codebase demonstrates a reasonable security posture for a complex emulation project. Primary concerns are: (1) dynamic code generation in the emitter components which requires careful input validation, (2) reliance on legacy external libraries like SoftFloat-3e that may have unpatched vulnerabilities, and (3) incomplete security configurations in CI/CD workflows. The project lacks visible automated dependency scanning and secret detection mechanisms. Recommendations include implementing stricter SBOM (Software Bill of Materials) tracking, adding security scanning tools to the build pipeline, and hardening the dynamic code generation components with additional validation. No hardcoded credentials or injection vulnerabilities are apparent from the static file structure analysis, which is positive.

• Medium · External SoftFloat-3e Library Dependency — External/SoftFloat-3e/. The codebase includes External/SoftFloat-3e as a git submodule dependency. SoftFloat is a legacy floating-point emulation library that may contain unpatched vulnerabilities. Regular security audits and updates of this dependency are critical, especially since it handles arithmetic operations that could be exploited. Fix: 1. Regularly check for security advisories on SoftFloat-3e. 2. Consider updating to the latest version. 3. Implement dependency scanning in CI/CD pipeline (not visible in current workflows). 4. Document the rationale for using this specific library version.
• Medium · Potential Unsafe Dynamic Code Emission — CodeEmitter/CodeEmitter/. The CodeEmitter component generates ARM64 code dynamically from x86 instructions. This involves runtime code generation which could be exploited if input validation is insufficient. The ALUOps, BranchOps, LoadstoreOps, and SystemOps emitters directly manipulate instruction buffers. Fix: 1. Implement strict validation of all x86 instruction inputs before code generation. 2. Use Control Flow Guard (CFG) and other mitigations for generated code. 3. Implement bounds checking in Buffer.h operations. 4. Add fuzzing tests for the code emitter with malformed inputs.
• Medium · Missing Security Headers in CI/CD Workflows — .github/workflows/. GitHub Actions workflows (.github/workflows/) lack visible security configurations such as OIDC token restrictions, artifact retention policies, and explicit permissions declarations. This could allow overly permissive actions. Fix: 1. Add explicit 'permissions' field to all workflow files with minimal required permissions. 2. Use OIDC tokens for cloud authentication instead of long-lived secrets. 3. Implement branch protection rules. 4. Review and restrict third-party action usage.
• Low · Unverified Submodule Dependencies — .gitmodules. The .gitmodules file references external repositories. Without verification mechanisms, there's a theoretical risk of dependency confusion or supply chain attacks if remote repositories are compromised. Fix: 1. Pin specific commit hashes for all submodules. 2. Implement git commit signature verification. 3. Use a dependency verification tool. 4. Document the rationale for each external dependency.
• Low · Configuration Files in Version Control — CMakeSettings.json, Data/AppConfig/client.json. CMakeSettings.json and Data/AppConfig/client.json are stored in version control. While these appear to be build configurations rather than secrets, they could inadvertently contain sensitive information in the future. Fix: 1. Establish a policy to never commit sensitive data. 2. Use CMake variables or environment variables for sensitive configurations. 3. Implement pre-commit hooks to scan for secrets using tools like TruffleHog. 4. Document configuration management best practices.
• Low · Docker Image Security Consideration — Data/Dockerfile, .github/workflows/. A Dockerfile exists (Data/Dockerfile) but no security scanning configuration is visible in the CI/CD pipelines. Docker images could contain vulnerable dependencies without being detected. Fix: 1. Add Docker image scanning to CI/CD (trivy, grype, etc.). 2. Use minimal base images (alpine, distroless). 3. Implement multi-stage builds. 4. Scan for vulnerable packages regularly. 5. Establish image signing policies.

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.