headroom-pc 0.1.0__tar.gz

headroom_pc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jasdish Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

headroom_pc-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: headroom-pc
+Version: 0.1.0
+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: 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
+Requires-Dist: mcp<3,>=2.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mcp<3,>=2.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`. Python 3.11 or newer.
+
+**Exe.** `headroom.exe` and `Headroom-Setup` from [GitHub Releases](https://github.com/Jasdish-Singh/headroom/releases) once a release is published. Setup does not clean anything and does not register a logon task.
+
+**winget,** after the manifest is published:
+
+```powershell
+winget install JasdishSingh.Headroom
+```
+
+The URL and SHA256 in `packaging/winget` are still placeholders.
+
+**pip.** The PyPI name is `headroom-pc`.
+
+```powershell
+py -3.12 -m pip install "headroom-pc[tray,mcp]"
+headroom status
+```
+
+`tray` is the icon. `mcp` is the assistant server.
+
+## 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 changes face with the PC. 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.
+
+Moods, 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)

headroom_pc-0.1.0/README.md

@@ -0,0 +1,159 @@
+<!-- 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`. Python 3.11 or newer.
+
+**Exe.** `headroom.exe` and `Headroom-Setup` from [GitHub Releases](https://github.com/Jasdish-Singh/headroom/releases) once a release is published. Setup does not clean anything and does not register a logon task.
+
+**winget,** after the manifest is published:
+
+```powershell
+winget install JasdishSingh.Headroom
+```
+
+The URL and SHA256 in `packaging/winget` are still placeholders.
+
+**pip.** The PyPI name is `headroom-pc`.
+
+```powershell
+py -3.12 -m pip install "headroom-pc[tray,mcp]"
+headroom status
+```
+
+`tray` is the icon. `mcp` is the assistant server.
+
+## 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 changes face with the PC. 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.
+
+Moods, 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)

headroom_pc-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "headroom-pc"
+version = "0.1.0"
+description = "Always-on RAM and disk watcher for a Windows laptop, with history, file review, and allowlisted cleanup."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Jasdish Singh" }]
+keywords = ["windows", "memory", "disk", "cleanup", "monitor"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Win32 (MS Windows)",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows :: Windows 11",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Monitoring",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "psutil>=5.9.0",
+    "PyYAML>=6.0.1",
+]
+
+[project.optional-dependencies]
+tray = [
+    "pystray>=0.19.5",
+    "Pillow>=10.0.0",
+]
+mcp = [
+    "mcp>=2.0,<3",
+]
+dev = [
+    "pytest>=8.0",
+    "mcp>=2.0,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/Jasdish-Singh/headroom"
+Repository = "https://github.com/Jasdish-Singh/headroom"
+Issues = "https://github.com/Jasdish-Singh/headroom/issues"
+
+[project.scripts]
+headroom = "headroom.cli:main"
+headroom-pc = "headroom.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+headroom = ["py.typed", "pets/*.png", "profiles/*.rules"]
+"headroom.profiles" = ["*.rules"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "--tb=short"

headroom_pc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

headroom_pc-0.1.0/src/headroom/__init__.py

@@ -0,0 +1,3 @@
+"""Headroom watches RAM and disk, reviews files, and cleans only known-safe caches."""
+
+__version__ = "0.1.0"

headroom_pc-0.1.0/src/headroom/__main__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+
+from headroom.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

headroom_pc-0.1.0/src/headroom/alerts.py

@@ -0,0 +1,125 @@
+"""Thresholds for sustained RAM pressure and low free space.
+
+RAM must stay above the configured percent for the full sustained window.
+A single spike does not notify. Disk alerts fire when a watched drive crosses
+into a worse state, and they do not repeat while it stays there.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from headroom.config import Config
+from headroom.formatutil import format_bytes, format_duration, format_percent
+from headroom.probe import Sample
+
+_RANK = {"ok": 0, "warn": 1, "critical": 2}
+
+
+@dataclass
+class AlertState:
+    ram_high_since: float | None = None
+    ram_alerted: bool = False
+    disk_level: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Alert:
+    level: str
+    code: str
+    title: str
+    message: str
+
+
+def disk_pressure(free_bytes: int, config: Config) -> str:
+    """Return ``ok``, ``warn``, or ``critical``. Equal to a line is still ok."""
+    if free_bytes < config.disk_critical_free_bytes:
+        return "critical"
+    if free_bytes < config.disk_warn_free_bytes:
+        return "warn"
+    return "ok"
+
+
+def evaluate(sample: Sample, state: AlertState, config: Config, now: float) -> list[Alert]:
+    """Update ``state`` and return alerts that should be delivered now."""
+    alerts: list[Alert] = []
+    alerts.extend(_ram_alerts(sample, state, config, now))
+    alerts.extend(_disk_alerts(sample, state, config))
+    return alerts
+
+
+def _ram_alerts(
+    sample: Sample,
+    state: AlertState,
+    config: Config,
+    now: float,
+) -> list[Alert]:
+    percent = sample.memory.ram_percent
+    if percent > config.ram_percent:
+        if state.ram_high_since is None:
+            state.ram_high_since = now
+        elapsed = now - state.ram_high_since
+        if elapsed >= config.ram_sustained_seconds and not state.ram_alerted:
+            state.ram_alerted = True
+            window = format_duration(config.ram_sustained_seconds)
+            return [
+                Alert(
+                    level="warning",
+                    code="ram_sustained",
+                    title="Headroom: RAM is high",
+                    message=(
+                        f"RAM has stayed above {format_percent(config.ram_percent)} "
+                        f"for {window} (now {format_percent(percent)}). "
+                        "Run `headroom top` to see which processes are using it."
+                    ),
+                )
+            ]
+        return []
+    state.ram_high_since = None
+    state.ram_alerted = False
+    return []
+
+
+def _disk_alerts(sample: Sample, state: AlertState, config: Config) -> list[Alert]:
+    alerts: list[Alert] = []
+    seen: set[str] = set()
+    watched = set(config.drives)
+    for disk in sample.disks:
+        if disk.key not in watched or disk.key in seen:
+            continue
+        seen.add(disk.key)
+        level = disk_pressure(disk.free, config)
+        previous = state.disk_level.get(disk.key, "ok")
+        state.disk_level[disk.key] = level
+        if _RANK[level] <= _RANK[previous]:
+            continue
+        if level == "critical":
+            alerts.append(
+                Alert(
+                    level="critical",
+                    code="disk_critical",
+                    title=f"Headroom: {disk.key} is critically low",
+                    message=(
+                        f"{disk.key} has {format_bytes(disk.free)} free, under the "
+                        f"{format_bytes(config.disk_critical_free_bytes)} critical line. "
+                        "Run `headroom clean --dry-run` to preview safe cleanup."
+                    ),
+                )
+            )
+        elif level == "warn":
+            alerts.append(
+                Alert(
+                    level="warning",
+                    code="disk_low",
+                    title=f"Headroom: {disk.key} is low on space",
+                    message=(
+                        f"{disk.key} has {format_bytes(disk.free)} free, under the "
+                        f"{format_bytes(config.disk_warn_free_bytes)} warning line."
+                    ),
+                )
+            )
+    for key in list(state.disk_level):
+        if key not in seen and key in watched:
+            # The drive disappeared. Forget it so a later return can alert again.
+            del state.disk_level[key]
+    return alerts