Metadata-Version: 2.4
Name: headroom-pc
Version: 0.1.1
Summary: Always-on RAM and disk watcher for a Windows laptop, with history, file review, and allowlisted cleanup.
Author: Jasdish Singh
License: MIT
Project-URL: Homepage, https://github.com/Jasdish-Singh/headroom
Project-URL: Repository, https://github.com/Jasdish-Singh/headroom
Project-URL: Issues, https://github.com/Jasdish-Singh/headroom/issues
Keywords: windows,memory,disk,cleanup,monitor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3,>=2.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: PyYAML>=6.0.1
Provides-Extra: tray
Requires-Dist: pystray>=0.19.5; extra == "tray"
Requires-Dist: Pillow>=10.0.0; extra == "tray"
Provides-Extra: mcp
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

<!-- mcp-name: io.github.Jasdish-Singh/headroom -->

# Headroom

[![CI](https://github.com/Jasdish-Singh/headroom/actions/workflows/test.yml/badge.svg)](https://github.com/Jasdish-Singh/headroom/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/github/license/Jasdish-Singh/headroom)](https://github.com/Jasdish-Singh/headroom/blob/main/LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/Jasdish-Singh/headroom/blob/main/pyproject.toml)

**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](https://github.com/Jasdish-Singh). [MIT](LICENSE), 2026.

<p>
  <img alt="Roomy on a Windows desktop" src="https://raw.githubusercontent.com/Jasdish-Singh/headroom/main/docs/images/roomy-desktop.png" width="720">
</p>

## 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.

## Install

The command is `headroom`.

**Exe.** `headroom-<version>-windows-x64.exe` from [GitHub Releases](https://github.com/Jasdish-Singh/headroom/releases). It is one portable file. Save it as `headroom.exe` in a folder you keep.

**winget,** after the manifest is accepted:

```powershell
winget install JasdishSingh.Headroom
```

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

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

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

## Quick start

```powershell
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](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.

<p>
  <img alt="Roomy close up" src="https://raw.githubusercontent.com/Jasdish-Singh/headroom/main/docs/images/roomy-zoom.png" width="360">
</p>

```powershell
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](docs/roomy.md).

## MCP

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

```text
headroom.exe mcp
```

**Claude Desktop** (`claude_desktop_config.json`):

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

**Cursor** (`.cursor/mcp.json`):

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

**Codex and ChatGPT** (`config.toml`):

```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.

```text
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](docs/ai-starter-prompt.md) and the MCP prompt `health_check`. Tool list: [docs/commands.md](docs/commands.md).

## More

- [Commands](docs/commands.md)
- [Roomy](docs/roomy.md)
- [Plugins](docs/plugins.md)
- [Build](docs/develop.md)
- [Publishing](docs/PUBLISHING.md)
