janitor-mcp
# janitor-mcp
Linux system health, orphan-process sweeper and transient cache cleaner for
agentic workspaces, exposed as a local MCP server (stdio, no network).
Reports RAM/swap/`/tmp` tmpfs pressure, detects orphaned development workers
(headless browsers, dead agent runners, detached compilers), sweeps them behind
an immutable protected denylist (SIGTERM → 3s → SIGKILL, `dry_run` by default)
and removes age-gated stale sockets and scratch caches.
## Run
```bash
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/python3 -m janitor.server # stdio MCP (same as the `janitor` script)
```
## Test
```bash
.venv/bin/pip install -e . pytest
.venv/bin/python3 -m pytest tests/ -q
bash scripts/check-file-size.sh
```
## Installed console shim
`~/.local/bin/janitor` points at the isolated runtime
`~/.local/share/janitor-mcp/runtime`, independent of this checkout. It is
registered as `janitor` in `~/.orquestra/mcps.json`; `orquestra --mcp-deploy`
compiles it into every harness config.
## Storage rule
Never create files in `/tmp/` (it is RAM-backed tmpfs here); all scratch must
live under `/var/tmp/testing/`.
## License
MIT — see [LICENSE](LICENSE).TDQS
Scored across 5 tools
Each tool has a fairly distinct role: health monitoring, orphan scanning, process termination, cache cleaning, and OOM inspection. The only mild overlap is between janitor_scan_orphans (read) and janitor_sweep_processes with target_type='orphans' (write), but the descriptions make the scan-vs-act split clear.
All five tools use a uniform janitor_ prefix followed by a snake_case verb_noun pattern (system_health, scan_orphans, sweep_processes, clean_caches, oom_inspect). The convention is consistent throughout with no style deviations.
Five tools is well-scoped for a system janitor: monitor, scan, terminate, clean, and inspect. Each tool earns its place with no redundant or filler operations.
The surface covers the core janitor lifecycle: observe health, find orphans, kill processes, clean caches, and assess OOM priority. Minor gaps exist, such as no general disk-usage reporting beyond tmpfs/swap or a way to list configured cache targets, but core workflows are covered.