Linux CPU performance policy is a mess. This project fixes it.
If you've ever tried to tune CPU performance on Linux, you know the feeling. You start with cpupower, discover it doesn't speak Intel HWP. You reach for intel_pstate sysfs paths, find they differ across kernel versions. You try tuned, which works until the daemon interferes with your custom governor. You try powertop, which writes to paths you didn't know existed and can't tell you what it changed.
The problem is structural. Linux CPU performance policy is fragmented across at least six kernel subsystems, each with its own sysfs interface, its own semantics, and its own opinions about what "performance" means.
# Six interfaces, zero coordination
/sys/devices/system/cpu/cpufreq/policy*/scaling_governor
/sys/devices/system/cpu/cpufreq/policy*/energy_performance_preference
/sys/devices/system/cpu/intel_pstate/no_turbo
/sys/devices/system/cpu/intel_pstate/max_perf_pct
/sys/class/thermal/thermal_zone*/trip_point_*/temp
/sys/devices/system/cpu/cpuidle/state*/disable
/sys/devices/system/cpu/smt/control
/dev/cpu/*/msr # raw registers — here be dragonsCPUOpt-Kernel approaches this differently. Instead of wrapping one interface or writing a daemon that fights with the kernel, it builds a unified capability map from whatever the running kernel actually exposes — and applies changes through a pipeline that is safe, reversible, and transparent by construction.
A safety-first pipeline, not a script
The architecture is layered deliberately. Every action flows through a pipeline where each stage can abort cleanly, and the user always has a preview before a single byte changes on disk.
The dry-run guarantee
Every profile application supports --dry-run --diff, which performs exactly zero filesystem modifications — including no snapshot creation — and prints a table of every write that would have happened. This isn't a courtesy flag. It's the primary interface for understanding what a profile does before committing to it.
# Preview the performance profile without touching anything
sudo cpuoptctl profile performance --dry-run --diff
# Output:
DRY RUN — no changes written
PATH CURRENT PROPOSED
policy0/energy_performance_preference balance_performance performance
policy0/scaling_governor powersave performance
policy4/energy_performance_preference balance_performance performance
intel_pstate/no_turbo 1 0
4 writes proposed, 0 writes executed.The sysfs root abstraction
Every path in the codebase is prefixed with a configurable --sysfs-root. The default is /, meaning real hardware. But passing a fixture directory redirects all sysfs access to a static file tree — no root, no real hardware, no kernel involvement.
This is one of the more underappreciated design decisions in the project. It means the entire discovery and profile logic is testable in CI without a privileged container, without mocking at the system call level, and without hardware in the loop. The fixture trees live under tests/fixtures/intel_hwp/ and faithfully model what a real Intel HWP system exposes.
"A sysfs abstraction that makes the whole tool testable without root isn't an implementation detail — it's the difference between a script that works on one machine and a tool that works on all of them."
Snapshot and restore
Before any apply run, the current value of every path that will be written is read and saved to last_state.json. The restore command replays those values in reverse. No daemon, no background service, no side channel — just a JSON file and a reverse traversal.
// ~/.local/share/cpuopt/last_state.json
{
"timestamp": "2026-06-28T10:32:00Z",
"profile_applied": "performance",
"writes": [
{
"path": "/sys/devices/system/cpu/cpufreq/policy0/energy_performance_preference",
"before": "balance_performance",
"after": "performance"
}
]
}What it actually does
The command surface is organized by intent: discover what the system exposes, get advice without writing anything, apply a profile, observe the result, and undo it cleanly.
Reads cpufreq, intel_pstate, thermal zones, idle states, and SMT topology from sysfs. Produces a structured capability map as JSON. Works on any kernel that exposes these paths.
Heuristic analysis of your current configuration with workload-aware profile suggestions. No writes, no changes — pure advisory output. Pass a workload hint to get a targeted recommendation.
performance, balanced, latency, quiet, ai-inference — each defined as a set of validated sysfs writes with documented tradeoffs. The explain command documents every change before you apply it.
Atomic pre-apply snapshot. The restore command replays the before state exactly. If the snapshot file is missing or corrupt, restore exits clearly rather than guessing.
Real-time telemetry loop: per-policy frequency, EPP, turbo status, thermal zone temperatures. Configurable interval. Output is structured enough to pipe into a dashboard.
Read-only MSR access via /dev/cpu/*/msr against a curated allowlist. Intel HWP request register, energy bias hint, package temperature. Zero writes to MSR — ever.
The safety model as a feature
Most CPU tools treat safety as a constraint — something that limits what they can do. CPUOpt-Kernel treats it as the product. The explicit list of things it will never do is as important as what it does.
| Action | CPUOpt-Kernel | cpupower | tuned | TLP |
|---|---|---|---|---|
| Dry-run / diff preview | ✓ | ✗ | ✗ | ✗ |
| Snapshot & restore | ✓ | ✗ | ✗ | ✗ |
| Workload-aware profiles | ✓ | ✗ | partial | ✗ |
| No raw MSR writes | ✓ | ✗ | ✓ | ✓ |
| No thermal bypass | ✓ | ✓ | ✗ | ✓ |
| Fixture-backed tests (no root) | ✓ | ✗ | ✗ | ✗ |
| JSON output | ✓ | ✗ | ✗ | ✗ |
| AMD amd-pstate | roadmap v0.2 | partial | partial | partial |
Getting started
# Install (Python 3.10+)
pip install cpuoptctl # or: pipx install cpuoptctl
# No root — inspect and advise
cpuoptctl doctor # what does your system expose?
cpuoptctl recommend # what profile fits your workload?
cpuoptctl recommend --workload llama-inference
# Root — apply profiles (snapshot taken automatically)
sudo cpuoptctl profile performance --dry-run --diff # preview
sudo cpuoptctl profile performance # apply
sudo cpuoptctl restore # undo
# Observe
sudo cpuoptctl monitor --interval 2Where this is going
The v0.1 Intel MVP validates the architecture. The real engineering work starts now. Three directions define the project's trajectory toward something genuinely novel in the Linux tooling space.
-
v0.1.0
Intel MVP — discover, profile, restore
Full Intel HWP / EPP support. Dry-run, snapshot, restore. Doctor, recommend, monitor. Fixture-backed test suite. This is the foundation everything else builds on.
-
v0.2.0
AMD amd-pstate + PyPI release
Guided mode, CPPC, EPP parity with Intel. Coverage gate in CI. Trusted publishing to PyPI so
pipx install cpuoptctljust works. This is when the project becomes accessible. -
v0.3.0
ARM SCMI & heterogeneous topology
big.LITTLE and DynamIQ cluster-aware profiles. This is what makes the project relevant to server ARM, embedded Linux, and the increasingly heterogeneous laptop architectures coming from Qualcomm and Apple-adjacent designs.
-
v0.4.0
Workload autodetection
Watch /proc/*/stat, cgroup accounting, and perf counters to classify the running workload in real time — then propose or automatically switch the profile. No other safe, sysfs-first CPU tool does this.
-
v1.0.0
systemd-cpuopt — first-class Linux service
D-Bus policy API, udev hotplug rules, OEM preset bundles, profile-as-code in TOML, community hardware registry fed by
discover --json. The systemd of CPU performance policy. This is where the LWN article gets written.
cpuoptctl discover --json on your hardware and opening a Discussion on GitHub with the output. This builds the hardware dataset that makes AMD and ARM backends possible. No code required.
Why this matters
The Linux CPU tooling landscape has been stuck for years. The tools that exist either require a daemon, write to paths they shouldn't, can't be previewed, can't be undone, or work on exactly one vendor's hardware. CPUOpt-Kernel is the first serious attempt to build a unified, safe, reversible CPU performance layer that treats the kernel interfaces as the actual API instead of routing around them.
The architecture is right. The safety philosophy is right. The sysfs root abstraction that makes it testable without root is genuinely clever systems engineering. What the project needs now is community: contributors who run hardware the Intel fixtures don't cover, engineers who've hit the same fragmentation problem and want a better tool, and systems programmers who want to help build the AMD and ARM backends.
If you've ever reached for cpupower, written a one-off shell script that cat'd something into a sysfs path and immediately forgotten what it did, or spent an afternoon fighting tuned profiles — this project is for you.