Windows Medic

Windows Medic lets Claude Code find out why your Windows machine is slow and fix it safely.

A small background agent watches the machine. When CPU or memory pressure lasts, it records what was happening and which processes were responsible. Claude Code connects to Windows Medic over MCP and can then answer questions like these:

• Why is my machine slow? / What made it slow half an hour ago?

• What is using port 5173?

• Are there leftover dev servers or build processes eating memory?

• Explorer is frozen — can you restart it?

Every answer is built from captured evidence and names the exact processes involved. Every repair is explicit, checked against a protection policy before anything is touched, verified afterwards and recorded in an audit log.

Everything stays on your machine: no cloud service, no telemetry, no network access. Windows Medic has no tool that runs arbitrary commands, scripts or shell input.

Requirements

• Windows 11 (developed and tested on Windows 11)

• uv 0.12 or newer. uv downloads the Python version Windows Medic needs by itself.

• Claude Code, to use Windows Medic through Claude

No administrator rights are needed to install or run it.

Related MCP server: PC-Control MCP Server

Install

uv tool install git+https://github.com/karoly-pfaff/windows-medic
windows-medic install-agent
windows-medic doctor

• uv tool install puts the windows-medic commands on your PATH. If uv warns that its tool directory is not on PATH, run uv tool update-shell and open a new terminal.

• install-agent creates the data directory and a commented config.toml. It also registers a Task Scheduler task, WindowsMedic\Agent, which starts the agent at every logon, unelevated and without a window. It starts the agent right away.

• doctor checks the installation and says what to do about anything that is not right.

Connect Claude Code

windows-medic mcp-config

This prints the exact command for your installation. Run it once to register the server for all your projects:

claude mcp add windows-medic -- "C:\Users\<you>\AppData\Roaming\uv\tools\windows-medic\Scripts\windows-medic-mcp.exe"

Instead of registering it for every project, you can save the JSON block it prints as .mcp.json in one project. Then ask Claude something like "Why is my machine slow?".

Using it with Claude

Claude Code sees eight tools. Five of them only read:

Three change something. They are marked as destructive, and Claude Code asks for your permission before running them unless you have allowed them permanently:

What a repair will and will not do:

• Exact identity only. A repair names a process by PID and creation time, as a read tool reported it. If the PID now belongs to a different process, the repair is refused instead of hitting the wrong one.

• Protected processes are never touched. Critical Windows processes, Windows components, Windows Medic itself and anything you add to the protection list are refused before any system call. A tree that contains a protected process is refused as a whole.

• Verified. A repair counts as successful only once the process is observed to be gone, or the port free, or a new Explorer running. Survivors and processes that appeared in the meantime are reported.

• Audited. Every attempt is recorded, including refusals: windows-medic repairs lists them.

• Never automatic. Windows Medic diagnoses on its own but repairs only when asked.

Restarting DWM (the desktop compositor) makes the screen flicker and needs administrator rights. It is therefore off by default. If you turn it on with [repairs] high_risk_repairs_enabled = true, each restart asks for a UAC confirmation. Only approve a prompt for a restart you asked for; windows-medic doctor explains why.

Command line

The same capabilities are available without Claude:

windows-medic health                        # what the machine is doing right now
windows-medic diagnose --since-minutes 30   # why it is (or was) slow
windows-medic incidents --limit 10          # recorded pressure episodes, newest first
windows-medic inspect 1234                  # one process, its tree and protection
windows-medic port 5173                     # who owns a port
windows-medic terminate 1234 --create-time 2026-09-11T09:00:02+00:00 [--tree]
windows-medic clear-port 3000
windows-medic restart-component explorer
windows-medic repairs --limit 10            # the repair audit

terminate needs the exact creation time that inspect or diagnose prints. Every command supports --help.

How it works

• The agent samples the system every 2 seconds and the process list every 10 seconds (every 2 seconds while pressure builds up). It keeps a 30-minute rolling window in memory with hard size limits. On a typical workstation it uses well under 1 % CPU and about 50 MiB of memory.

• Incidents. CPU at 90 % or more for 20 seconds, or memory 90 % used or under 1.5 GiB free for 20 seconds, opens an incident. The incident keeps the samples from just before it started and the processes that contributed most, and is stored for 7 days. If monitoring stops in the middle of an incident (reboot, logoff), the incident is marked interrupted rather than left "ongoing".

• Diagnosis combines recent incidents, a fresh measurement and Windows' own "not responding" verdicts into ranked findings: CPU or memory pressure, resource hogs, hung windows and stale development process trees. Each finding states its evidence, what raised or lowered its confidence, and which repairs would apply. A process is called stale only on validated parent evidence, never because of its name.

Configuration

All settings have defaults and can be changed in %LOCALAPPDATA%\WindowsMedic\config.toml:

windows-medic config init     # write config.toml with every setting commented at its default
windows-medic config check    # show where settings come from and the values in force

For example:

[pressure]
cpu_percent = 85              # open a CPU incident at 85 % instead of 90 %

[protection]
additional_protected_names = ["backup-agent.exe"]   # never terminate these

[repairs]
high_risk_repairs_enabled = false                   # DWM restart through UAC

Every program reads the configuration when it starts. The CLI and the MCP server (which Claude Code starts per session) pick up a change by themselves. The agent needs a restart: run windows-medic uninstall-agent --stop and then windows-medic install-agent, or log off and on again. An invalid value stops the program at startup with a message naming the setting.

Files

Everything lives in %LOCALAPPDATA%\WindowsMedic (set WINDOWS_MEDIC_DATA_DIR to use another directory):

windows-medic status shows the locations, whether the agent is running and the latest records.

Update

windows-medic uninstall-agent --stop
uv tool upgrade windows-medic
windows-medic install-agent

Stopping the agent first lets uv replace its files. Your configuration and history are kept.

Uninstall

windows-medic uninstall-agent --stop                # remove the logon task, stop the agent
windows-medic uninstall-agent --stop --purge-data   # ... and delete Windows Medic's data
claude mcp remove windows-medic
uv tool uninstall windows-medic

--purge-data deletes only the files Windows Medic created. If the data directory also holds other files, they and the directory are kept.

Contributing

See CONTRIBUTING.md for the development setup, the engineering rules every change follows, the quality gate and how the code is organised.

License

MIT © Károly Pfaff