burrow-system-tools

# Burrow system tools

Burrow runs a local MCP server over the user's Mac: live + historical system
state (read-only) and gated maintenance. The governing habit is **diagnose
first** — when a question is about *this machine*, or you spot a system symptom
mid-task, reach for the read-only tools, name the cause, *then* propose a fix.
Read-only tools never change anything, so there's no reason to hesitate.

## Diagnose first (read-only — always safe)

- **burrow_doctor** — one-call health sweep: engine present, Full Disk Access,
  memory pressure, disk headroom, SMART disk health, Time Machine backup age,
  recent decode errors. **Start here for any vague "something's wrong / is my
  Mac healthy?"** — it tells you which area to drill into. It does **not**
  report SIP / Gatekeeper / FileVault / firewall over MCP (only the GUI fills
  those in), so for "is my Mac secure?" read them from the shell rather than
  claiming the tool checked them.
- **burrow_snapshot** — current vitals (CPU, memory, disk, network, temperature,
  top processes, a 0–100 health score). For "what's happening right now".
- **burrow_top_processes** — top CPU *right now*. For "what's using my CPU / why
  is it hot or loud?"
- **burrow_process_usage** — ranks over a *window* by cpu_time / peak_cpu /
  avg_cpu / peak_mem. Prefer this for "all day / since this morning / what's
  draining my battery?"
- **burrow_history** / **burrow_diff** — a trend over time, or what changed since
  a point ("it got slow in the last hour").
- **burrow_disk_forecast** — "when will my disk fill up?" (pointless once the
  disk is already full — go straight to analyze). **burrow_analyze
  <path>** — "what's eating space in <folder>?" Supports `depth` (descend
  into the largest subdirectories in one call), `limit`, and `min_size` — e.g.
  `depth: 2, min_size: 104857600` maps hotspots without a call per directory.
  Scanning a home folder or ~/Library can take minutes: pass the most specific
  path you can.
- **burrow_ports** — "what's listening / what's on port 3000?" (pid + owner).
- **burrow_cleanup_history** / **burrow_deleted_files** — what Burrow has cleaned,
  and exactly which files it removed.
- **burrow_list_apps** — installed apps + the exact names uninstall accepts (call
  this before any uninstall). **burrow_info** — whether Burrow is even recording
  data (use when results look empty or stale).
- **Reclaim candidates** (read-only, report-only — they find things worth
  deleting but never delete): **burrow_dupes** `paths` (duplicate files),
  **burrow_photos** `path` (visually near-duplicate images), **burrow_orphans**
  `path` (files belonging to no installed app), **burrow_sentinel** (apps
  sitting in the Trash whose leftovers you could sweep), **burrow_slim_check**
  `binary` (how much thinning a fat binary would reclaim), **burrow_net**
  (which app is moving bytes right now), **burrow_rules_dryrun** `dir` (what a
  community rules directory would target).
- **burrow_anomalies** — processes whose last-24h CPU has regressed against
  *their own* 14-day baseline. Reach for it when the user says something feels
  off but nothing looks obviously high: this is per-process, so a program that
  always sits at 40% isn't flagged and one that went 2% → 15% is.
- **burrow_agent_audit** — what agents (including you, earlier) have already run
  through this server: the tool, the exact arguments, dry-run or real, and the
  outcome. Check it before repeating a cleanup, and whenever you're not sure a
  call went through.

## Then act (gated — preview by default)

Maintenance tools mutate the system. They run **dry-run by default**; a real run
needs `confirm: true` *and* the user's Settings opt-in, so a confirmed call may
still be refused and reported as blocked. **Always show the dry-run preview and
get the user's explicit go before passing `confirm: true`** — never assume a real
run will execute.

- **burrow_clean** / **burrow_optimize** — remove caches/logs/junk / run safe
  maintenance. The clean scan can take minutes on a full disk; a result with
  `timed_out: true` means the run was killed, not that nothing needed cleaning.
- **burrow_uninstall** — remove apps + leftovers (to Trash unless `permanent`;
  resolve names via `burrow_list_apps` first; it aborts unless the matcher hits
  exactly the apps you named).
- **burrow_purge** / **burrow_installer** — preview-only over MCP (dev build
  artifacts / leftover installers); the real run is interactive in the app.

## Resources, prompts, and long scans

Burrow also exposes its read-only answers as **resources**, which you can attach
instead of re-calling a tool: `burrow://doctor`, `burrow://snapshot/latest`,
`burrow://ports`, `burrow://info`, `burrow://forecast/disk`,
`burrow://cleanup/history`, `burrow://cleanup/deleted-files`,
`burrow://agent-audit`, `burrow://anomalies`, `burrow://report/weekly`, plus
`burrow://history/{minutes}`, `burrow://processes/{metric}` and
`burrow://report/{days}`. Each read says how long it stays fresh — five seconds
for a live snapshot, a minute for a digest — so re-read rather than trusting a
minutes-old attachment.

Its **prompts** (`diagnose_slow_mac`, `reclaim_disk_space`,
`explain_last_cleanup`, `investigate_process`, `pre_uninstall_check`) encode the
tool orderings that avoid wrong answers — worth offering when the user's request
matches one.

Slow scans (`burrow_analyze` on a big folder, `burrow_clean`, `burrow_dupes`)
may come back as a **task handle** instead of a result if your client supports
the tasks extension. Poll `tasks/get` until it reaches a terminal status rather
than assuming the call failed.

## Be proactive

The biggest win is catching problems the user hasn't mentioned. If, mid-task, you
hit or notice a system symptom — a build failing because the disk is nearly full,
a process pinning the CPU, a port already in use — **pause, run the relevant
read-only tool, tell the user what you found, and offer the fix.** That's the
behavio