winget install --id=WinTune.WinTune -e WinTune is a native, CLI-first Windows performance doctor. Measure CPU, memory, disk, processes, startup, services, and power — then explain bottlenecks and apply safe fixes with confirmation. No Electron, no registry cleaner, no scareware.
Native Windows performance diagnostics. Measure bottlenecks. Explain impact. Apply safe fixes.
WinTune is a native, terminal-first Windows performance doctor written in C. It inspects your machine using official Windows APIs, explains what it finds in plain language, and applies only safe, reversible changes after you approve them.
WinTune System Scan
OS: Windows 11 Pro x64
Host: DESKTOP-9KD2
Uptime: 3d 04h
Power: Balanced (AC)
CPU:
Usage: 7.7%
Logical processors: 32
Memory:
Used: 21.6 GB / 63.9 GB (33.8%)
Disk:
C:\ 272.8 GB free / 892.8 GB (30.6% free)
Active time: 4%
Top Processes by Memory:
PID Process Memory Private
13136 Cursor.exe 1.1 GB 1.1 GB
24628 Discord.exe 606.7 MB 533.5 MB
Recommendations:
[WT-POWER-001] Use a higher-performance power plan while plugged in
Severity: low | Risk: low | Confidence: 85% | reversible
Why: On AC power with the 'Balanced' plan. While plugged in, the High
performance plan can improve responsiveness for heavy workloads.
Action: wintune power --set performance
wintune.exe, no runtime to install.WinTune is not a fake "PC cleaner", registry-tweaking booster, debloater,
antivirus replacement, FPS optimizer, or RAM cleaner. It never disables
security tools, deletes system files, or promises magical speedups. See
docs/safety.md.
docs/shells.md. WinTune itself is always wintune.exe
(not a Linux ELF).Requirements: CMake 3.24+ and the MSVC C toolchain (Visual Studio 2022 Build Tools or newer).
| Terminal | Command |
|---|---|
| PowerShell | .\scripts\build.ps1 |
| CMD | scripts\build.cmd |
| Git Bash | ./scripts/build |
| WSL | ./scripts/build (calls Windows PowerShell via interop) |
Do not run ./scripts/build.ps1 from Git Bash or WSL — .ps1 is PowerShell;
Bash will fail on param( with a syntax error. Use ./scripts/build instead.
PowerShell (from the repo root):
.\scripts\build.ps1 # Debug (default)
.\scripts\build.ps1 -Config Release
Git Bash / WSL (from the repo root):
./scripts/build # recommended
./scripts/build -Config Release
./scripts/test -Config Release
./scripts/lint
./build/Release/wintune.exe help
CMD:
scripts\build.cmd
The executable is produced at build\Debug\wintune.exe (or Release when
built with -Config Release).
Full shell matrix (build, test, package, release, running wintune.exe):
docs/shells.md.
Testing (unit + full CLI smoke): docs/testing.md.
cmake -S . -B build
cmake --build build --config Debug
Other scripts (same names in Bash without .ps1):
| Bash | PowerShell |
|---|---|
./scripts/test | .\scripts\test.ps1 |
./scripts/smoke | .\scripts\smoke.ps1 |
./scripts/clean | .\scripts\clean.ps1 |
./scripts/package | .\scripts\package.ps1 |
./scripts/lint | .\scripts\lint.ps1 |
./scripts/release | .\scripts\release.ps1 |
GitHub Actions runs on every push and pull request to main:
/W4 with warnings as errors (/WX)scripts/test.ps1scripts/smoke.ps1 -SkipSlow (full command surface)Releases: push a semver tag to publish a portable ZIP to GitHub Releases:
git tag v0.1.0
git push origin v0.1.0
Local equivalents:
.\scripts\lint.ps1
.\scripts\package.ps1 -Config Release -Arch x64 -Zip
.\scripts\release.ps1 -Version 0.2.0
# Git Bash / WSL
./scripts/lint
./scripts/package -Config Release -Arch x64 -Zip
./scripts/release -Version 0.2.0
Packaging details: docs/packaging.md.
Shell matrix: docs/shells.md.
The release artifact WinTune-x.y.z-win-x64.zip is not a GUI app. Do not
double-click wintune.exe — it prints help and exits, so the window closes
immediately.
To run WinTune from the ZIP:
C:\Tools\WinTune). Check ARCH.txt
matches your PC (x64 vs arm64).Add-To-Path.cmd, then open a new terminal so
wintune is on PATH.Launch-WinTune.cmd for an interactive prompt with the
full CLI, or double-click wintune.exe for the built-in menu, or
Start-Tray.cmd for the system tray icon, or.\wintune.exe doctor
.\wintune.exe scan
.\wintune.exe help
# Git Bash
./wintune.exe doctor
./wintune.exe scan --json
At the wintune> prompt you can type any command and options (e.g.
scan --samples 3, top --watch, startup --include-tasks).
Read QUICKSTART.txt in the ZIP for a short guide.
wintune help # usage
wintune version # version info
wintune scan # full local scan (implemented)
wintune top # top processes by memory (implemented)
wintune top --limit 20 # show more rows
wintune top --watch # live refresh in place (q or Ctrl+C to quit)
wintune recommend # explainable recommendations, no changes (implemented)
wintune doctor # scan + recommendations + summary (implemented)
wintune startup # startup entries (registry + folders) (implemented)
wintune services # service state, start type, PID (implemented)
wintune power # current plan + recommendation (implemented)
wintune tui # live terminal dashboard (implemented)
Mutating commands always confirm first (or take --yes), require admin only
when the change does, and write rollback metadata where practical:
wintune power # show current plan, source, recommendation
wintune power --set performance # switch to an existing scheme (balanced|performance|saver|ultimate)
wintune apply WT-POWER-001 # apply a recommendation by id
wintune apply WT-STARTUP-DISABLE "HKCU\Run:App" # disable startup entry
wintune apply WT-TASK-DELAY "task:\Vendor\App" --seconds 30
wintune startup disable "" # toggle a startup entry (StartupApproved flag; reversible)
wintune startup enable ""
wintune services restart # stop+start a service (admin; critical services refused)
wintune rollback list # list saved rollback records
wintune rollback apply # undo a recorded change
wintune report # write a performance report (text or JSON)
wintune report # text report to stdout
wintune report --format json # JSON report to stdout
wintune report --json # same as --format json
wintune report --output report.txt # write text report to a file
wintune report --format json --output report.json
The text report adds bottlenecks, risk notes, and pointers to startup /
services beyond the basic scan summary. JSON uses the same schema as
wintune scan --json.
Rollback records are stored under %LOCALAPPDATA%\WinTune\rollback. Power-plan
switches and startup toggles are fully reversible via rollback apply.
tui)wintune tui # live CPU/RAM/disk/network + processes
wintune tui --interval 2000 # refresh every 2 seconds (default 1000 ms)
wintune tui --no-color # disable ANSI colors
wintune tui --no-unicode # ASCII bars/borders
wintune tui --safe-terminal # conservative: ASCII + no color (SSH/unknown)
Keys: q quit (also Esc/Ctrl+C), r refresh, o overview, d disk,
m memory, n network, p power, s services, ? help. The dashboard is
read-only and always restores the terminal (cursor + main screen) on exit. It
requires an interactive terminal; in a non-interactive session it exits with a
hint to use scan or top --watch.
startup and services are read-only inventories:
wintune startup --include-services # also list auto-start services
wintune startup --json
wintune services --auto # filters: --auto --running --stopped --failed
wintune services --failed # auto-start services that are stopped
wintune services --json
Common options for scan/top today:
wintune scan --interval 1000 # CPU sampling interval (ms)
wintune top --limit 15 # number of rows
wintune top --watch # live monitor (default 1000 ms)
wintune top --watch --interval 2000 # refresh every 2 seconds
top --watch refreshes the table in place without entering the full TUI. It
requires an interactive terminal; in a non-interactive/piped session it prints
a single snapshot instead. The cursor is always restored on exit.
Full command reference: docs/cli.md.
scan, top, recommend, doctor, power, and rollback list support
--json, emitting only JSON on stdout so output can be piped and parsed safely.
Use --output to write to a file instead (UTF-8, no BOM):
wintune scan --json
wintune scan --json --output report.json
wintune top --json --limit 20
wintune recommend --json
The scan document has a stable shape:
{
"version": "0.1.0",
"timestamp_utc": "2026-06-11T08:00:13Z",
"system": { "available": true, "os": "Windows 11 Pro", "arch": "x64", "hostname": "...", "uptime_ms": 0 },
"cpu": { "available": true, "logical_processors": 32, "total_usage_percent": 14.1 },
"memory": { "available": true, "total_bytes": 0, "available_bytes": 0, "used_bytes": 0, "used_percent": 35.3 },
"disk": { "available": true, "volumes": [ { "root": "C:\\", "total_bytes": 0, "free_bytes": 0, "free_percent": 30.5 } ], "active_available": true, "active_percent": 4.0 },
"power": { "available": true, "plan": "Balanced", "plan_name": "Balanced", "on_ac": true, "battery_percent": null },
"processes": { "available": true, "top": [ { "pid": 0, "name": "...", "working_set_bytes": 0, "private_bytes": 0, "read_bytes": 0, "write_bytes": 0, "cpu_percent": null } ] },
"recommendations": [
{ "id": "WT-POWER-001", "title": "...", "severity": "low", "risk": "low", "reason": "...", "action": "wintune power --set performance", "requires_admin": false, "rollback_available": true, "confidence_percent": 85 }
]
}
Each section carries an available flag so partial failures are visible
rather than fatal. cpu_percent is null until per-process CPU lands in a
later phase. Recommendations are deterministic and explainable; pass
--no-recommendations to scan to omit them.
WinTune works through the Windows OpenSSH Server as a normal terminal program.
One-shot commands (ssh host "wintune scan --json") are non-interactive: no
ANSI on stdout, no confirmation prompts (use --yes for mutating commands).
JSON output includes a session object (interactive, remote, elevated).
ssh user@windows-host "wintune scan"
ssh user@windows-host "wintune scan --json"
ssh user@windows-host "wintune doctor --json"
ssh user@windows-host "wintune top --watch" # single snapshot over one-shot SSH
ssh -t user@windows-host "wintune tui --safe-terminal"
See docs/ssh.md.
--yes is passed.--yes.Full details: docs/safety.md.
WinTune v0.2.0 ships Phases 0–21 (CLI/TUI, service, packaging, tray, and end-user release polish). Optional follow-ups (winget publish, Authenticode in CI) are documented but not required to use the tool.
| Phase | Scope | Status |
|---|---|---|
| 0 | Skeleton: build, help, version, logging, errors | Done |
| 1 | Basic metrics: scan, top (CPU, memory, disk, processes) | Done |
| 2 | JSON output for scan / top (--json, --output) | Done |
| 3 | top --watch live refresh | Done |
| 4 | Recommendation engine, recommend, doctor | Done |
| 5 | startup, services | Done |
| 6 | tui dashboard | Done |
| 7 | Safe apply actions: power --set, apply, startup toggle, service restart, rollback | Done |
| 8 | report (text + JSON, --output) | Done |
| 9 | SSH hardening (session detection, safe-terminal, JSON session metadata) | Done |
| 10 | ETW boot/login analysis (boot analyze, boot trace, startup --measured) | Done |
| 11 | Background agent / Windows Service (service install, --via-service) | Done |
| 12 | Scheduled tasks + startup depth (tasks, --include-tasks, delay) | Done |
| 13 | Windows Update & reboot readiness (updates, WT-UPDATE-*) | Done |
| 14 | Restart Manager integration (blockers, WT-BLOCKER-001) | Done |
| 15 | Metrics depth (per-process CPU, disk rates, multi-sample scan) | Done |
| 16 | Apply actions v2 + rollback completeness | Done |
| 17 | Fleet / automation hardening | Done |
| 18 | Packaging + ARM64 (package.ps1, --log-file, dual-arch releases) | Done |
| 19 | Optional tray / native GUI (never Electron) | Done |
| 20 | TUI polish & UX | Done |
| 21 | Distributable executable (end-user release) | Done |
v1 (Phases 0–9) and v2+ roadmap through Phase 21 are complete. Details:
docs/roadmap.md.
Commands that are recognized but not yet implemented print a clear notice and exit non-zero.
--json and --output work for scan, top, recommend, doctor, power,
rollback list, and report.top --watch is live when stdin and stdout are both interactive; it falls
back to a single snapshot over piped/one-shot SSH (silent fallback with
--json).--safe-terminal
semantics) for interactive PTY sessions.scan, top, and tui.scan and top; very
short-lived processes may be missed.power --set switches only to power schemes that already exist on the
machine (it never creates custom plans); the previous scheme is captured for
rollback, including custom plans.apply uses a central action map for power, startup disable/delay, and task
disable/delay. Memory/disk/CPU/boot/update recommendations remain advisory.
See docs/apply.md.startup enable/disable toggles the Windows StartupApproved flag (the same
one Task Manager uses) and never deletes the underlying Run value or startup
file. HKLM-scoped entries (HKLM\Run, common Startup folder) require admin.
Startup "impact" uses heuristics by default; wintune startup --measured
correlates entries with Windows boot/login metrics when available (may require
elevation). Boot analysis reads the Diagnostic-Performance event log — on some
systems that returns access denied without an elevated shell; scan/doctor/report
continue without boot data, while boot analyze asks for admin. See
docs/boot.md. Scheduled task inspection is
available via wintune tasks list and wintune startup --include-tasks.
See docs/tasks.md.services restart requires elevation and refuses a denylist of
critical/security services to avoid destabilizing Windows.tui dashboard is read-only and keyboard-driven (no mouse). Network
throughput is computed from interface byte-counter deltas between refreshes.
Applying changes from the dashboard is intentionally not supported.DESIGN.md — complete feature catalogdocs/architecture.md — how the codebase is layereddocs/safety.md — what WinTune will and will not dodocs/cli.md — command referencedocs/tui.md — terminal dashboarddocs/ssh.md — remote usagedocs/boot.md — boot/login analysis (Phase 10)docs/tasks.md — scheduled tasks and startup delay (Phase 12)docs/updates.md — Windows Update and reboot readiness (Phase 13)docs/blockers.md — Restart Manager and reboot blockers (Phase 14)docs/metrics.md — what is measured and howdocs/ci.md — GitHub Actions, lint, and releasesdocs/packaging.md — portable ZIP, PATH helper, optional installerdocs/release-checklist.md — pre-tag release checklistdocs/signing.md — optional Authenticode guidancedocs/winget.md — draft winget package (optional publish)docs/roadmap.md — phased delivery planReleased under the MIT License. See LICENSE.