Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .github/workflows/build-windows-installer.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
name: build-windows-installer

# Run this from the Actions tab ("Run workflow") if you have no Windows PC to build on.
# It runs the tests, builds FrameTweak.exe with PyInstaller, builds the Inno Setup installer,
# and attaches both as downloadable artifacts.
on:
workflow_dispatch:

jobs:
build:
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
cache: pip
cache-dependency-path: requirements-dev.txt
- name: Install dependencies
run: python -m pip install --disable-pip-version-check -r requirements-dev.txt
- name: Run tests
run: python -m pytest -q
env:
QT_QPA_PLATFORM: offscreen
- name: Build the app with PyInstaller
run: python -m PyInstaller --noconfirm --clean FrameTweak.spec
- name: Check the exe was built
shell: pwsh
run: |
if (-not (Test-Path dist\FrameTweak\FrameTweak.exe)) { throw "dist\FrameTweak\FrameTweak.exe was not built" }
- name: Install Inno Setup
run: choco install innosetup --no-progress -y
- name: Build the installer
shell: pwsh
run: |
& "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe" installer\FrameTweak.iss
if (-not (Test-Path dist-installer\FrameTweak-Setup.exe)) { throw "dist-installer\FrameTweak-Setup.exe was not built" }
- uses: actions/upload-artifact@v4
with:
name: FrameTweak-Setup
path: dist-installer/FrameTweak-Setup.exe
if-no-files-found: error
- uses: actions/upload-artifact@v4
with:
name: FrameTweak-portable
path: dist/FrameTweak
if-no-files-found: error
25 changes: 25 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
name: tests

# Runs the test suite on a real Windows machine, which is where FrameTweak is meant to run.
on:
push:
branches: [main]
pull_request:
workflow_dispatch:

jobs:
test:
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
cache: pip
cache-dependency-path: requirements-dev.txt
- name: Install dependencies
run: python -m pip install --disable-pip-version-check -r requirements-dev.txt
- name: Run tests
run: python -m pytest -q
env:
QT_QPA_PLATFORM: offscreen
10 changes: 10 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Python
__pycache__/
*.py[cod]
.pytest_cache/

# Created by Install-FrameTweak.bat / Build-FrameTweak.bat
.venv/
build/
dist/
dist-installer/
24 changes: 13 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,13 @@

| 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". |
| **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 (3 presets + custom, validated JSON import/export). History with before/after comparison. **No FPS is measured.** |
| **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** | Game Mode and the High performance power plan, each with what/why/drawbacks/admin/reversible/current value. |
| **Cleanup** | User temp files and crash dumps only. Analyze first, then confirm. Skips files modified in the last 24 h and locked files, never follows symlinks, refuses protected folders. Reports measured bytes removed. |
| **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
Expand Down Expand Up @@ -61,8 +61,8 @@ No Windows PC? Push to GitHub and run the **build-windows-installer** workflow;
## Architecture
```
main.py entry point (start-up errors -> native message box + log)
src/core/ sysinfo, winproc (the only subprocess launcher), applog, paths
src/tweaks/ engine.py (backup/apply/verify/rollback/undo) + catalog.py
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)
Expand All @@ -79,12 +79,14 @@ tests/ tools/ assets/ installer/ .github/workflows/
pip install -r requirements-dev.txt
python -m pytest -q
```
46 tests cover system-info fallbacks, backup/restore, the change engine (including failed writes, failed verification, corrupt backups), startup toggling against a fake registry, debloat classification and refusals, cleanup safety, 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 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 and headless UI tests | Run: 46 passed (Linux) |
| 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** |
Expand All @@ -93,15 +95,15 @@ Safe manual check on Windows: apply Game Mode from Tweaks and undo it, confirmin

## Known limitations
- Windows 10/11 only (other versions are flagged unsupported).
- Only two tweaks so far (Game Mode, High performance plan). Presets are therefore similar.
- 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.
- Cleanup scan runs on the UI thread; large temp folders may briefly pause the window.
- Unsigned installer: SmartScreen may warn.

## Roadmap
Privacy and visual-effects tweaks; Edge startup/background behavior tweaks; AMD/Intel GPU sensors; light theme; code signing; optional external FPS-tool integration (opt-in).
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.
Expand Down
2 changes: 1 addition & 1 deletion installer/FrameTweak.iss
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
; Inno Setup 6 script. Installs per-user by default (no admin needed); user may choose all-users at the prompt.
[Setup]
AppName=FrameTweak
AppVersion=0.3.0
AppVersion=0.4.0
AppPublisher=FrameTweak
DefaultDirName={autopf}\FrameTweak
DefaultGroupName=FrameTweak
Expand Down
22 changes: 17 additions & 5 deletions src/cleanup/cleaner.py
Original file line number Diff line number Diff line change
@@ -1,23 +1,35 @@
"""Safe temp cleanup: allow-listed roots only, never follows symlinks, skips recent/locked files."""
import os, tempfile, time
from dataclasses import dataclass, field
from typing import Iterable, List
from typing import Iterable, List, Optional

PROTECTED_NAMES = {"downloads", "documents", "desktop", "pictures", "videos", "music", "onedrive"}

@dataclass
class Category:
id: str; name: str; path: str
default_selected: bool = True # False for caches whose removal has a visible cost (they rebuild on next use)
note: str = ""

@dataclass
class CleanResult:
bytes_removed: int = 0; files_removed: int = 0; skipped: int = 0
errors: List[str] = field(default_factory=list)

def categories() -> List[Category]:
cats = [Category("user_temp", "User temporary files", tempfile.gettempdir())]
local = os.environ.get("LOCALAPPDATA")
if local: cats.append(Category("crash_dumps", "Application crash dumps", os.path.join(local, "CrashDumps")))
REBUILD = "Rebuilt automatically; the first launch of each game may stutter or load slowly while shaders recompile."

def categories(local_appdata: Optional[str] = None, temp_dir: Optional[str] = None) -> List[Category]:
"""Fixed, allow-listed cleanup locations that exist on this PC. Paths can be injected for tests."""
local = local_appdata if local_appdata is not None else os.environ.get("LOCALAPPDATA")
cats = [Category("user_temp", "User temporary files", temp_dir or tempfile.gettempdir())]
if local:
j = lambda *p: os.path.join(local, *p)
cats += [Category("crash_dumps", "Application crash dumps", j("CrashDumps")),
Category("wer_reports", "Windows error reports (this user)", j("Microsoft", "Windows", "WER")),
Category("dx_shader_cache", "DirectX shader cache (rebuilds on next game launch)", j("D3DSCache"), False, REBUILD),
Category("nv_dx_cache", "NVIDIA DirectX shader cache (rebuilds on next game launch)", j("NVIDIA", "DXCache"), False, REBUILD),
Category("nv_gl_cache", "NVIDIA OpenGL shader cache (rebuilds on next game launch)", j("NVIDIA", "GLCache"), False, REBUILD),
Category("amd_dx_cache", "AMD shader cache (rebuilds on next game launch)", j("AMD", "DxCache"), False, REBUILD)]
return [c for c in cats if os.path.isdir(c.path)]

def validate_root(path: str, allowed: Iterable[str]) -> str:
Expand Down
48 changes: 48 additions & 0 deletions src/core/report.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
"""Plain-text system report the user can save and share. Built only from values FrameTweak actually read:
anything unreadable says 'Unavailable', and no FPS or performance numbers are ever invented."""
import os, time
from typing import Iterable, List, Optional, Tuple
from src.core import sysinfo
from src.tweaks import engine

APPLIED = {True: "Applied", False: "Not applied", None: "Unavailable"}
ON_OFF = {True: "On", False: "Off", None: "Unavailable"}

def tweak_status(tweaks: Iterable[engine.Tweak]) -> List[Tuple[str, str]]:
"""(tweak name, 'Applied' | 'Not applied' | 'Unavailable') by reading each setting right now."""
return [(t.name, APPLIED[engine.is_applied(t)]) for t in tweaks]

def _memory(total: Optional[int], free: Optional[int]) -> str:
return "Unavailable" if total is None or free is None else f"{sysinfo.fmt_bytes(free)} free of {sysinfo.fmt_bytes(total)}"

def build_report(s: sysinfo.SystemSnapshot, tweaks: List[Tuple[str, str]], actions: List[str], now: Optional[float] = None) -> str:
u = lambda x: x if x not in (None, "") else "Unavailable"
when = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(now if now is not None else time.time()))
cores = f" ({s.cpu_cores} threads)" if s.cpu_cores else ""
lines = ["FrameTweak system report", f"Generated: {when}", "Values FrameTweak could not read are shown as Unavailable. No FPS is measured.", "",
"System",
f" Windows: {u(s.windows)}" + ("" if s.supported or not s.windows else " (unsupported version)"),
f" CPU: {u(s.cpu)}{cores}",
f" GPU: {u(s.gpu)}",
f" RAM: {_memory(s.ram_total, s.ram_available)}",
f" Disk: {_memory(s.disk_total, s.disk_free)}",
f" Power plan: {u(s.power_plan)}",
f" Game Mode: {ON_OFF[s.game_mode]}", "", "Tweaks"]
lines += [f" {name}: {state}" for name, state in tweaks] or [" None available"]
lines += ["", "Recent actions (from the local log)"]
lines += [f" {a}" for a in actions] or [" None recorded yet"]
if s.notes: lines += ["", "Notes"] + [f" {n}" for n in s.notes]
lines += ["", "Review this file before sharing it: it can include app names from your startup and debloat actions."]
return "\n".join(lines) + "\n"

def save_report(text: str, directory: str) -> str:
"""Write the report as a new file in `directory` (never overwrites) and return its path."""
os.makedirs(directory, exist_ok=True)
stamp = time.strftime("%Y%m%d-%H%M%S")
for n in range(100):
path = os.path.join(directory, f"FrameTweak-report-{stamp}{'' if n == 0 else f'-{n}'}.txt")
try:
with open(path, "x", encoding="utf-8") as f: f.write(text)
return path
except FileExistsError: continue
raise OSError("Could not choose a free report file name")
7 changes: 6 additions & 1 deletion src/profiles/store.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,16 @@
import json, os, re, tempfile
from typing import List

KNOWN = {"game_mode": "Enable Windows Game Mode", "power_high": "Use the High performance power plan"}
# Tweaks a profile may contain (id -> name; names must match the Tweaks catalog, a test checks that).
KNOWN = {"game_mode": "Enable Windows Game Mode", "power_high": "Use the High performance power plan",
"game_dvr_off": "Turn off Game DVR background capture", "gamebar_quiet": "Stop the controller button and tips from opening Game Bar",
"mouse_accel_off": "Turn off mouse pointer acceleration", "sticky_keys_prompts_off": "Stop the Sticky Keys and Filter Keys pop-ups"}
PRESETS = {
"Balanced": {"tweaks": ["game_mode"], "notes": "Game Mode only; leaves your power plan alone."},
"Gaming": {"tweaks": ["game_mode", "power_high"], "notes": "Game Mode and the High performance power plan. Uses more power."},
"Low Background Activity": {"tweaks": ["game_mode"], "notes": "Game Mode, then use the Startup page and close background apps yourself. FrameTweak never auto-closes processes."},
"Competitive": {"tweaks": ["game_mode", "power_high", "game_dvr_off", "gamebar_quiet", "mouse_accel_off", "sticky_keys_prompts_off"],
"notes": "For fast-paced games: less Game Bar activity, no pointer acceleration and no Sticky Keys pop-ups, on top of Game Mode and High performance. Uses more power; the mouse and keyboard changes need a sign-out to take effect."},
}
EXE = re.compile(r"^[A-Za-z0-9._ -]{1,64}\.exe$")

Expand Down
Loading
Loading