Autonomous, measurement-driven system performance tuning.
FPSMaxxing is an open-source Rust control plane for using an AI coding agent or LLM - such as Claude, Codex, or another MCP client - to improve gaming FPS, frame pacing, system latency, thermals, power efficiency, and compute throughput through bounded, reversible experiments.
Important
FPSMaxxing is currently an architecture scaffold. It does not perform real hardware writes, overclock a GPU, edit BIOS settings, or modify the Windows Registry yet.
Existing tools already know how to control parts of a PC:
- Process Lasso manages process priorities, CPU sets, affinities, and power profiles.
- Fan Control manages fan curves and thermal response.
- PresentMon measures frame times, latency, and rendering performance.
- LibreHardwareMonitor reads clocks, temperatures, fan speeds, loads, and power.
- NVML and AMD SMI expose supported GPU telemetry and controls.
- Windows APIs expose power policy and documented Registry settings.
FPSMaxxing is intended to connect those control planes to a reproducible research loop:
observe → propose → validate → snapshot → apply → benchmark → keep or rollback
The LLM proposes an experiment. Deterministic policy, broker, provider, watchdog, and measurement components decide whether the experiment is allowed and whether its measured result should be retained.
- The model is never the root process. Privileged changes pass through a small Rust broker.
- Capabilities, not shell commands. Agents call typed operations with bounded parameters.
- Every write is leased. Changes require a snapshot, verification probe, deadline, and rollback path.
- One owner per knob. Conflicting tuning applications cannot fight over the same setting.
- Measurement beats folklore. Changes survive only when repeated workload tests show a practical improvement.
- Fast loops stay local. Drivers and dedicated tools control millisecond-to-second behavior; the LLM operates at experiment cadence.
| Area | Initial provider | Intended use |
|---|---|---|
| Process scheduling | Process Lasso | CPU affinity, CPU sets, priorities, process power profiles |
| Frame performance | PresentMon | FPS, frame time, latency, GPU telemetry |
| Hardware telemetry | LibreHardwareMonitor bridge | Temperatures, clocks, loads, power, fan RPM |
| Fan control | Fan Control | Complete, reviewed thermal profiles |
| NVIDIA GPU | NVML | Supported clock and power-limit operations |
| AMD GPU | AMD SMI | Supported telemetry and control operations |
| Windows power | Native Windows APIs | Cloned power schemes and processor policy |
| Registry | Curated catalog | Documented, typed, versioned, reversible settings only |
BIOS changes, voltage changes, raw MSR/PCI/EC access, firmware flashing, and arbitrary Registry paths are explicitly outside the first release.
The repository currently includes:
- A Rust 2024 Cargo workspace
- Shared capability and provider contracts
- A provider SDK lifecycle
- A working mock sidecar with snapshot/apply/verify/rollback tests
- Scaffolds for the gateway, privileged broker, watchdog, experiment runner, and CLI
- OSS governance, security policy, issue templates, and CI
- An organized documentation index with architecture, plans, threat model, and provider guides
Try the safe scaffold:
cargo test --workspace
cargo run -p fpsmaxxing-cli -- doctor
cargo run -p fpsmaxxing-mock-providerLLM / MCP client
│
▼
Rust gateway ──► policy engine ──► privileged broker ──► provider sidecars
▲ │
│ ▼
telemetry normalizer ◄──────────── independent watchdog
│
▼
experiment journal and benchmark decision gate
Start with the documentation index. The core references are the architecture, implementation plan in Markdown or HTML, threat model, and agent instructions.
That is the intended workflow. A Claude or Codex agent should be able to inspect available capabilities, propose a bounded change, run a controlled game or benchmark workload, and keep the change only when frame time, latency, thermals, and correctness remain within policy. That closed loop is planned but not implemented yet.
FPSMaxxing will not expose arbitrary voltage or register writes. Planned GPU operations use supported vendor APIs, query device limits first, require rollback, and run under an independent thermal watchdog. Persistent or high-risk operations require explicit approval.
Not initially. Consumer BIOS settings are vendor-specific and can make a machine unbootable. Server firmware may eventually be supported through Redfish and boot recovery, but firmware autonomy is deliberately deferred.
No. It is an orchestration and measurement layer. Where a stable third-party control plane exists, FPSMaxxing should integrate with it instead of reimplementing its hardware logic.
No. Registry and power changes must come from a curated catalog containing the supported Windows versions, exact value type, permitted values, verification method, risk class, and rollback procedure.
Read CONTRIBUTING.md and the current implementation plan before starting a provider. Security-sensitive changes require tests for denial, timeout, lease expiry, verification failure, and rollback.
Do not open public issues for vulnerabilities that could enable arbitrary privileged execution or unsafe hardware writes. Follow SECURITY.md.
Licensed under the Apache License 2.0.
