Skip to main content
Glama

Headroom

CI License: MIT Python 3.11+

A quiet watcher for the RAM and disk on your Windows PC.

Headroom sits in the tray, keeps a small history, and shows what is full. Cleanup is limited to an allowlist. Type YES to delete. Type MOVE to send a reviewed file to the Recycle Bin or to an archive folder.

Jasdish Singh. MIT, 2026.

What it does

  • Watches RAM, commit charge, page file, and free space.

  • Records history and a short report (disk trend, likely leaks, folders that grew).

  • Cleans only user_temp, windows_temp, chrome_cache, edge_cache, firefox_cache, thumbnail_cache, and recycle_bin. Config cannot add a path.

  • Reviews files, duplicate copies, old downloads, and startup programs.

  • Serves a page on 127.0.0.1 and a read-only desktop pet, Roomy.

  • Exposes a local MCP server. clean, move, and startup_disable return a plan. They do not change the PC.

Related MCP server: windirstat-mcp

Install

The command is headroom.

Exe. headroom-<version>-windows-x64.exe from GitHub Releases. It is one portable file. Save it as headroom.exe in a folder you keep.

winget, after the manifest is accepted:

winget install JasdishSingh.Headroom

pip. The PyPI name is headroom-pc. Python 3.11 or newer.

py -3.12 -m pip install "headroom-pc[tray]"
headroom status

tray adds the tray icon. The MCP server is always included.

Quick start

headroom status
headroom top
headroom clean --dry-run
headroom watch
headroom dashboard

headroom watch takes a sample immediately, then every 30 seconds (slower on battery, faster under pressure). headroom install starts it at sign-in. A second watch, dashboard, or pet does not start another copy.

headroom dashboard prints and opens http://127.0.0.1:<port>/?token=.... Before the first stored sample, the page shows the live reading.

Commands, defaults, and exit codes: docs/commands.md.

Roomy

Roomy is a small beige monitor. The cord is the tail. It walks a little and shows the PC's RAM usage in a speech bubble, like "RAM 62% used". It cannot clean, move, or delete.

headroom pet
headroom widget
headroom pet --skin midnight
headroom pet --skin tower --lite

headroom widget is the same pet. Click opens the dashboard. Drag remembers the spot. Right-click: dashboard, report, mute, hide, quit.

The dashboard has an on/off toggle for Roomy. It starts or stops the pet and remembers the choice across restarts, overriding widget.autostart.

Skins and the frame budget: docs/roomy.md.

MCP

headroom mcp is a stdio server on this PC. Point a client at the installed exe:

headroom.exe mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "headroom": {
      "command": "headroom.exe",
      "args": ["mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "headroom": {
      "command": "headroom.exe",
      "args": ["mcp"]
    }
  }
}

Codex and ChatGPT (config.toml):

[mcp_servers.headroom]
command = "headroom.exe"
args = ["mcp"]

With the pip package on PATH, the command is headroom and the argument is still mcp.

mcp-name: io.github.Jasdish-Singh/headroom

Quick start with AI

Paste this into Claude, ChatGPT, or Cursor after connecting the MCP server.

You have access to Headroom, a local tool that monitors and protects this PC's RAM and disk.

Start a full health check:
1. Call `status` and tell me current RAM, commit, page file and free disk space in plain English.
2. Call `top` and list the 5 biggest RAM users, saying whether each is normal or worth closing.
3. Call `analyze` and `scan` to find what's taking up disk space, grouped into important, safe to clean, and needs my review.
4. Call `dupes` and `startup_list`, and point out duplicate files and startup apps slowing my PC.
5. Call `changes` and `report` to tell me what changed recently and any trends to watch.

Finish with a short summary: my overall PC health (good / watch / act now), the top 3 things to do, and how much space or RAM each would free.

Rules: only read and explain. If cleanup helps, call `clean`, `move` or `startup_disable` only to show me a plan. Never delete, move or disable anything yourself. I'll approve inside Headroom.

The same text is docs/ai-starter-prompt.md and the MCP prompt health_check. Tool list: docs/commands.md.

More

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to scan a developer machine for disk space hogs, audit git worktrees for stale or orphaned ones, re-check individual findings, and run allowlisted cleanup actions as dry runs unless explicitly confirmed. Risky items are reported with warnings and refused by default.
      1,042 npm
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables an AI assistant to perform read-only scans of Windows drives and identify cleanup candidates, including caches, temporary files, and largest files.
      1
      1
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to analyze why a Windows drive is full, plan safe cleanup, and apply changes only within user-configured limits. All actions are recorded and reversible, and nothing can be permanently deleted.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to inspect, diagnose, and manage a local Windows PC through the Model Context Protocol, with 97 tools for task management, cleanup, hardware and security checks, administration, networking, and shell helpers.
      179 PyPI
      MIT