Skip to content

About

FrameTweak is an all-in-one Windows optimization tool designed to boost gaming performance, improve FPS, reduce system lag, and debloat Windows by removing unnecessary apps and background processes. With a modern interface and easy-to-use tweaks, FrameTweak helps you create a faster, cleaner, and smoother PC experience.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

FrameTweak

A transparent, reversible Windows 10/11 gaming optimizer and debloater. Every change is explained before it happens, individually approved, backed up, verified afterwards, and undoable. FrameTweak measures your PC honestly: it never invents FPS numbers, temperatures or "boost" percentages.

Status: alpha. Built and unit-tested on Linux. The Windows-specific code (registry, powercfg, Store-app removal, installer scripts) has not yet been run on a real Windows PC. See Verification status. Use at your own risk and read each confirmation dialog.

Screenshots

Dashboard Monitoring
Dashboard Monitoring
Gaming: diagnostics Gaming: profiles
Diagnostics Profiles
Tweaks Debloat
Tweaks Debloat
Cleanup
Cleanup

What it does

Area What you get
Dashboard Live CPU/RAM/disk gauges; Windows version, CPU, GPU, RAM, disk, power plan, Game Mode, startup count; recent actions. Unreadable values show "Unavailable". Export report saves a plain-text summary (system, tweak status, recent actions) you can attach to a bug report or keep as a before/after record.
Monitoring Live CPU, RAM and disk charts and top memory users. Samples only while the page is visible.
Gaming 10-second measured diagnostic (CPU/RAM/disk, top processes, display resolution and refresh rate, NVIDIA GPU via nvidia-smi, sensors when exposed). Findings cite their evidence and avoid definitive "bottleneck" claims. Profiles (4 presets + custom, validated JSON import/export). History with before/after comparison. No FPS is measured.
Startup Lists Run-key and Startup-folder entries with status. Enable/disable through StartupApproved (what Task Manager uses): backed up, verified, undoable. Nothing is deleted.
Debloat Detects installed Store apps and offers removal of a curated allow-list only (23 optional Microsoft apps such as Weather, News, Solitaire, Clipchamp, Copilot). Security, Store, Xbox/gaming and system components are blocked. One confirmation lists exactly what will be removed; each removal is verified. Removal is not auto-reversible (reinstall from the Microsoft Store).
Tweaks 9 individually applied, reversible tweaks in four groups, each shown with what/why/drawbacks/admin/reversible/current value and an Applied / Not applied status, plus Undo all (one confirmation listing exactly what is restored). Gaming: Game Mode, High performance power plan, Game DVR background capture off, Game Bar controller-button/tips off. Input: mouse pointer acceleration off, Sticky Keys / Filter Keys pop-ups off (only the shortcut flag is cleared, your other accessibility flags are kept). Visuals: transparency effects off. Privacy: advertising ID off, Windows suggestions and tips off. All are current-user (HKCU) settings and need no administrator rights.
Cleanup A fixed list of temp and cache folders: user temp files, crash dumps, this user's Windows error reports, and the DirectX / NVIDIA / AMD shader caches (shader caches start unselected: they rebuild automatically, but games can stutter on their next launch). Analyze first, then confirm. Scanning and cleaning run in the background so the window stays responsive. Skips files modified in the last 24 h and locked files, never follows symlinks, refuses protected folders. Reports measured bytes removed.
Logs / Settings Local log viewer; persisted monitoring interval and window size.

Safety principles

  • Analyze first, change nothing until you approve.
  • One shared engine for every change: read → back up → apply → re-read to verify → roll back on failure → log. If a backup fails, nothing changes.
  • No security features are touched: Defender, Windows Update, firewall, drivers and recovery are out of scope.
  • No wildcard deletion, no downloaded scripts, no shell strings. All subprocesses go through src/core/winproc.py (argument lists, CREATE_NO_WINDOW, timeouts), and a test forbids starting subprocesses anywhere else.
  • Imported profiles are data, validated against a strict schema and never executed.
  • Local-first: no account, no telemetry, no network needed after installation.
  • Honest limits: Microsoft Edge is deliberately not removable (it provides WebView2, which other apps depend on, and Windows has no supported removal path).

Install (Windows 10/11)

  1. Download/extract the project.
  2. Double-click Install-FrameTweak.bat. No admin needed; internet is needed once for dependencies. It checks Windows and Python 3.10+ (64-bit), creates a project-local .venv, installs requirements.txt, verifies the install, and creates a FrameTweak desktop shortcut that launches the app directly (no console window).
  3. Start FrameTweak from the desktop shortcut.

Other scripts: Launch-FrameTweak.bat (manual launch), Uninstall-FrameTweak.bat (removes the shortcut and optionally .venv/build output; keeps %APPDATA%\FrameTweak settings, logs and backups unless you choose to delete them), Build-FrameTweak.bat.

From source:

py -3.12 -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python main.py

Build a standalone .exe

Build-FrameTweak.bat runs the tests, then builds dist\FrameTweak\FrameTweak.exe with PyInstaller (FrameTweak.spec, windowed, with icon) and, if Inno Setup 6 is installed, dist-installer\FrameTweak-Setup.exe. If the exe exists, the installer script uses it and Python is not needed. No Windows PC? Push to GitHub and run the build-windows-installer workflow; it attaches the installer as a downloadable artifact.

Architecture

main.py                  entry point (start-up errors -> native message box + log)
src/core/                sysinfo, winproc (the only subprocess launcher), applog, paths, report
src/tweaks/              engine.py (backup/apply/verify/rollback/undo/undo-all), regtweaks.py (validated HKCU tweaks), catalog.py
src/startup/             inspect_startup.py, manage.py
src/debloat/             appx.py (curated allow-list, deny patterns, verified removal)
src/cleanup/             cleaner.py (allow-listed roots, age gate, symlink-safe)
src/gaming/              diagnostics.py (measurements + evidence-based findings)
src/profiles/            store.py (validated profiles, history, comparison)
src/backup/              store.py (atomic JSON backups)
src/monitoring/          live.py (psutil sampling)
src/ui/                  PySide6 pages; worker.py runs blocking work off the UI thread
tests/  tools/  assets/  installer/  .github/workflows/

Testing

pip install -r requirements-dev.txt
python -m pytest -q

The tests cover system-info fallbacks, backup/restore, the change engine (including failed writes, failed verification, corrupt backups, multi-value rollback, undo-all), every registry tweak against a fake registry (including tampered backups and wrong value types), startup toggling against a fake registry, debloat classification and refusals, cleanup safety and the cleanup categories, the exported report, profile validation/import/export, diagnostics analysis, subprocess hygiene, icon assets, the background worker, window smoke tests, and static checks of the .bat scripts. Destructive operations are always mocked; tests never touch real system settings.

The tests GitHub Actions workflow runs the suite on a real Windows runner for every push and pull request; the build-windows-installer workflow (run it manually from the Actions tab) runs the tests, builds the exe and installer and attaches them as downloads.

Verification status

Status
Unit tests (logic, engine, tweaks, cleanup, report) Run: 86 passed (Linux). Two headless Qt smoke tests need PySide6 and were skipped where the latest changes were written, so run python -m pytest -q (or the CI workflow) to confirm the UI pages.
Registry, powercfg, Get/Remove-AppxPackage, display API, nvidia-smi Written, mocked in tests, not run on Windows
.bat installer/launcher/uninstaller/build scripts Statically checked only, not run on Windows
PyInstaller exe, Inno Setup installer, desktop shortcut, "no console window" behavior Not built or run

Safe manual check on Windows: apply Game Mode from Tweaks and undo it, confirming in Settings → Gaming; disable and restore one startup entry and confirm in Task Manager → Startup; remove a harmless app like Weather and confirm it is gone.

Known limitations

  • Windows 10/11 only (other versions are flagged unsupported).
  • Tweak gains vary and are often small; FrameTweak never measures FPS, so use the before/after diagnostics to check what changed on your PC.
  • The mouse and keyboard tweaks write the current-user settings Windows reads at sign-in, so they usually take effect after you sign out and back in.
  • GPU stats need NVIDIA + nvidia-smi; AMD/Intel show Unavailable. CPU temperature is usually not exposed by Windows.
  • No FPS measurement; that needs an external tool and is out of scope.
  • Changing all-users (HKLM) startup entries requires running FrameTweak as administrator.
  • Unsigned installer: SmartScreen may warn.

Roadmap

More privacy and visual-effects tweaks; Edge startup/background behavior tweaks; a one-click restore point before debloating (needs administrator); AMD/Intel GPU sensors; light theme; code signing; optional external FPS-tool integration (opt-in).

Disclaimer

FrameTweak changes Windows settings and can uninstall apps. It is provided as-is, without warranty. Create a restore point and read each confirmation. It does not guarantee any FPS improvement.

License

MIT (see LICENSE).

About

FrameTweak is an all-in-one Windows optimization tool designed to boost gaming performance, improve FPS, reduce system lag, and debloat Windows by removing unnecessary apps and background processes. With a modern interface and easy-to-use tweaks, FrameTweak helps you create a faster, cleaner, and smoother PC experience.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages