{"id":51165591,"url":"https://github.com/caezium/Burrow","last_synced_at":"2026-07-07T22:00:48.023Z","repository":{"id":362453748,"uuid":"1254978612","full_name":"caezium/Burrow","owner":"caezium","description":"🐹 A free, open-source, native macOS GUI for the Mole CLI (mo): clean, uninstall, optimize, analyze disk, and watch live status. Plus long-range history + an MCP server for AI agents. Coming to Windows","archived":false,"fork":false,"pushed_at":"2026-07-07T16:37:55.000Z","size":65868,"stargazers_count":870,"open_issues_count":16,"forks_count":144,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-07-07T17:03:53.048Z","etag":null,"topics":["cleaner","disk-usage","macos","mcp","menubar","mole","open-source","swift","swiftui","system-monitor","windows","winui3"],"latest_commit_sha":null,"homepage":"https://burrow.henryzh.dev","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caezium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.html","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T08:37:49.000Z","updated_at":"2026-07-07T15:05:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"940da1a1-f208-496a-87a4-51041be9da02","html_url":"https://github.com/caezium/Burrow","commit_stats":null,"previous_names":["caezium/burrow"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/caezium/Burrow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caezium%2FBurrow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caezium%2FBurrow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caezium%2FBurrow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caezium%2FBurrow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caezium","download_url":"https://codeload.github.com/caezium/Burrow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caezium%2FBurrow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35243953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cleaner","disk-usage","macos","mcp","menubar","mole","open-source","swift","swiftui","system-monitor","windows","winui3"],"created_at":"2026-06-26T19:00:22.712Z","updated_at":"2026-07-07T22:00:48.014Z","avatar_url":"https://github.com/caezium.png","language":"Swift","funding_links":[],"categories":["Cleanup \u0026 Uninstall","MCP 服务器精选列表"],"sub_categories":["Text","📁 文件系统与存储"],"readme":"\u003e Burrow is an independent open-source project. It bundles its own MIT engine —\n\u003e `burrow-engine`, a fork of the [Mole](https://github.com/tw93/Mole) (`mo`) CLI\n\u003e by tw93 — and is **not affiliated with or endorsed by\n\u003e [mole.fit](https://mole.fit/)** (the official Mole for Mac app by `mo`'s\n\u003e author); its own name, mark, palette, and copy are original.\n\u003e\n\u003e If you like Mole and want to fund `mo`'s development — **buy mole.fit ($19)**.\n\n# Burrow\n\n**A free, open-source GUI for the [Mole](https://github.com/tw93/Mole) (`mo`) engine — now bundled in the app, so there's nothing else to install. Clean, uninstall, optimize, analyze disk, and watch live system status, plus long-range history and local MCP access for AI agents. Native on macOS, with a Windows preview implemented under [`windows/`](windows/).**\n\n![macOS 14+](https://img.shields.io/badge/macOS-14%2B-black)\n![Windows 10/11 — beta](https://img.shields.io/badge/Windows-10%2F11%20·%20beta-blue)\n![License: MIT](https://img.shields.io/badge/License-MIT-blue)\n\n\nMac:\n```sh\nbrew install --cask caezium/tap/burrow\n```\n\nWindows: download from [releases](https://github.com/caezium/Burrow/releases)\n\n## Contents\n\n- [Screenshots](#screenshots)\n- [The tools](#the-tools)\n- [Platforms](#platforms)\n- [Roadmap](#roadmap)\n- [How Burrow compares to other tools](#how-burrow-compares-to-other-tools)\n- [Settings](#settings)\n- [Permissions \u0026 Full Disk Access](#permissions--full-disk-access)\n- [Requirements](#requirements)\n- [Install](#install)\n- [Security \u0026 trust](#security--trust)\n- [Use it with your AI agent](#use-it-with-your-ai-agent)\n- [Develop \u0026 test](#develop--test)\n- [Architecture](#architecture)\n- [Attribution \u0026 license](#attribution--license)\n\n## Screenshots\n\n### macOS\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Status — live CPU, memory, GPU, disk, network, and battery\" src=\"docs/assets/shot-status.png\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg alt=\"History — long-range charts over a local SQLite metric history\" src=\"docs/assets/shot-history.png\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Analyze — squarified treemap of your whole disk\" src=\"docs/assets/shot-analyze.png\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg alt=\"Clean — hub for caches, dev build junk, and leftover installers\" src=\"docs/assets/shot-clean.png\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Clean — scanning, with a live reclaimable total\" src=\"docs/assets/shot-clean-running.png\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg alt=\"Clean — scan complete, reclaimable space found\" src=\"docs/assets/shot-clean-result.png\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Optimize — maintenance running\" src=\"docs/assets/shot-optimize-running.png\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg alt=\"Optimize — maintenance complete, areas refreshed\" src=\"docs/assets/shot-optimize-done.png\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Software — installed apps with search, sort, and multi-select uninstall\" src=\"docs/assets/shot-apps.png\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg alt=\"Software — Homebrew app updates\" src=\"https://github.com/user-attachments/assets/8c3fa0bd-ba08-4dff-af5c-b0213b8adb69\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Settings\" src=\"https://github.com/user-attachments/assets/a642c5eb-6959-4b7a-a29a-de9bb9f0edb3\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Activity — a running log of cleans, optimizes, and scans, plus anything in flight\" src=\"https://raw.githubusercontent.com/caezium/Burrow/main/docs/assets/shot-activity.png\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eExplain with AI — point an MCP-capable agent (Claude Code, or a local model via LM Studio) at Burrow and ask your Mac in plain language.\u003c/em\u003e\n  \u003cbr\u003e\n  \u003cimg alt=\"Explain with AI — burrow_snapshot analyzed in plain language\" src=\"https://raw.githubusercontent.com/caezium/Burrow/main/docs/assets/shot-ai.png\"\u003e\n  \u003cem\u003eWhen doing other tasks with AI Agents, if they find something irregular with your system, for example low disk space, they will have the tools to automatically disect the problem, and perform secure cleanups for you proactively and autonomously, without you having to ask.\u003c/em\u003e\n  \u003cbr\u003e\n  \u003cimg width=\"1177\" height=\"887\" alt=\"image\" src=\"https://github.com/user-attachments/assets/e067a39f-808b-41a8-ac02-9dd19cabf929\" /\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"320\" alt=\"Menu-bar HUD — health, metric tiles, top processes, and live job status\" src=\"https://github.com/user-attachments/assets/105ef0ca-b970-4eec-8604-db21f458b816\"\u003e\n\u003c/p\u003e\n\n\n### Windows preview\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Windows preview — Status overview with health, CPU, memory, GPU, disk, network, and fan cards\" src=\"docs/assets/shot-windows-status-overview.png\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Windows preview — Status battery and process table\" src=\"docs/assets/shot-windows-status-processes.png\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Windows preview — History charts for CPU, memory, disk, and network\" src=\"docs/assets/shot-windows-history.png\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Windows preview — Analyze treemap for disk usage\" src=\"docs/assets/shot-windows-analyze.png\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg alt=\"Windows preview — Apps uninstall inventory sorted by size\" src=\"docs/assets/shot-windows-apps.png\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## The tools\n\nBurrow wraps a bundled, open-source Mole engine in a native desktop app: clean\njunk, purge dev artifacts, sweep leftover installers, uninstall apps, run safe\nmaintenance, map your disk, and watch live system status — in one window. On top\nof that it adds things the CLI doesn't have: a **long-running history** of your\nmachine's metrics in a local store and an **MCP server** so any AI agent (Claude\nCode, Cursor, Codex…) can ask \"what's been happening on this machine.\"\n\n**macOS** is the mature flagship. **Windows** currently has a native WinUI 3 /\n.NET 8 preview app, Windows telemetry/history, tray HUD, loopback HTTP, MCP\nstdio bridge, CI, tests, and unsigned release packaging.\n\n\n| Tool | What it does | `mo` command |\n|---|---|---|\n| **Status** | Live dashboard with per-metric sparklines and a sortable/pinnable process table. | `mo status --json` |\n| **Clean** | Preview what's reclaimable, then clean for real — categorized cache/log/leftover removal. | `mo clean` |\n| **Purge** | Reclaim space from dev projects: `node_modules`, build dirs, `target/`, `__pycache__`, and more. | `mo purge` |\n| **Installers** | Find and remove leftover `.dmg`/`.pkg` installer files in bulk. | `mo installer` |\n| **Optimize** | One-tap safe maintenance: rebuild caches, repair metadata, flush DNS, restart Dock/Finder. | `mo optimize` |\n| **Software** | Installed-app list with search/sort (size, name, recent, source) and multi-select uninstall; a Homebrew **Updates** tab. | `mo uninstall --list`, `brew outdated` |\n| **Analyze** | Squarified treemap of your disk; drill into any folder, reveal in Finder. | `mo analyze --json` |\n\nEvery scan offers a **no-risk preview** (`--dry-run`) first, a clear\n**reclaimed-space summary** when it finishes, and a **Stop** button to abort a\nrunning job.\n\n### What's on the Status dashboard\n\nA live, glanceable read of your Mac's vitals, refreshed continuously:\n\n- **CPU** — usage, load averages (1/5/15), core count, temperature\n- **Memory** — used %, pressure (normal/warning/critical), swap\n- **GPU** — name and utilisation (Apple Silicon via IOAccelerator)\n- **Disk** — capacity and live read/write I/O rates\n- **Network** — up/down throughput per interface\n- **Battery** — percentage, health, cycle count, time remaining\n- **Health score** — Mole's overall 0–100 rating, with a one-line reason\n- **Top processes** — by CPU or memory, sortable and pinnable\n\n### Burrow's own extras\n\n- **History** — long-range charts (5 m → 90 d) over a local SQLite history of\n  every metric, plus peak-per-process tables. Nothing the CLI keeps.\n- **Activity** — a running log of what Burrow has done (cleans, optimizes,\n  scans) and the live status of anything in flight.\n- **Menu-bar HUD** — health hero, metric tiles, top processes, and live job\n  status, all from the menu bar (you can also run as a Dock app instead).\n- **MCP server** — a stdio JSON-RPC server (`burrow mcp` / `Burrow --mcp`) plus\n  an optional localhost HTTP API, so any AI agent can query your Mac's recent\n  state. See [Use it with your AI agent](#use-it-with-your-ai-agent).\n\n\n## Platforms\n\n| | macOS | Windows |\n|---|---|---|\n| Status | **Stable** — flagship | **Preview** — checked in under `windows/` |\n| Engine | bundled MIT engine (a fork of `mo`, Go CLI); falls back to a system `mo` | bundled Mole/PowerShell engine plus Windows fallbacks where needed |\n| UI | SwiftUI, translucent menu-bar app | WinUI 3 / .NET 8 |\n| Install | `brew install --cask caezium/tap/burrow` | build from source; unsigned preview artifacts via `windows/scripts/build-release.ps1` |\n| Source | [`macos/`](macos/) | [`windows/`](windows/) |\n\nBoth apps live in this one repo, side by side, sharing this README, the landing\nsite, and release documentation. The Windows preview currently includes a native\nshell, tool pages, local telemetry/history, loopback HTTP/MCP surfaces, tests,\nCI, and unsigned local packaging. See the [Windows architecture notes](windows/docs/windows-architecture.md)\nand [release notes](windows/docs/release.md).\n\n### Windows preview\n\nThe checked-in Windows app currently includes:\n\n- A native WinUI 3 / .NET 8 shell with Dashboard, History, Activity, Analyze,\n  Clean, Purge, Installers, Apps, Optimize, and Settings routes.\n- Local Windows telemetry sampling for Dashboard, History, tray status, HTTP,\n  and MCP.\n- Local JSONL-backed history/activity storage.\n- Optimize preview/confirm flows through Mole where available; the Windows Clean\n  route is present but still a guarded pending stub until Mole Windows exposes a\n  stable non-interactive cleanup contract for the GUI.\n- Native Windows fallback flows for Analyze, Purge, installer cleanup, and app\n  inventory where the Windows Mole branch is still interactive or lacks JSON.\n- A tray icon, live tooltip, tray HUD, status menu, and quick navigation.\n- A loopback-only HTTP API (`/health`, `/info`, `/snapshot`, `/metrics`) and a\n  stdio MCP bridge with the read-only Burrow tools.\n- Unit tests, Windows CI, local smoke-test helpers, and an unsigned release\n  script that produces a setup executable, portable ZIP, hashes, and WinGet\n  manifests.\n\n## Roadmap\n\n\u003c!-- ROADMAP:BEGIN generated by scripts/site-release.py — edit docs/roadmap.json instead --\u003e\nThe full board, with status and voting, lives at **[burrow.henryzh.dev/roadmap](https://burrow.henryzh.dev/roadmap.html)**. Vote by upvoting an issue, or [open a request](https://github.com/caezium/Burrow/issues/new/choose).\n\n**Planned**\n\n- Signed \u0026 notarized macOS builds — A Developer ID signature so Gatekeeper trusts Burrow without the right-click → Open dance.\n- In-app auto-update — Once builds are signed, silent background update checks with a one-click install (Sparkle).\n- Windows preview → first stable — Data-loss and supply-chain hardening, parity, and test coverage before it loses the “preview” label. ([#93](https://github.com/caezium/Burrow/issues/93))\n\n**Considering**\n\n- Persistent one-tap “run all” Tune-Up — A saved Smart-Care routine you trigger in one tap from the dashboard. ([#77](https://github.com/caezium/Burrow/issues/77))\n\n_Recently shipped: Bundled MIT engine — no separate `mo` install, Process inspector + CPU watchdog, Get Online connectivity companion, Security-aware Doctor, No-freeze live dashboard — see the [changelog](https://burrow.henryzh.dev/releases.html)._\n\u003c!-- ROADMAP:END --\u003e\n\n\n\u003ca href=\"https://www.star-history.com/?repos=caezium%2FBurrow\u0026type=timeline\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=caezium/Burrow\u0026type=timeline\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=caezium/Burrow\u0026type=timeline\u0026legend=top-left\" /\u003e\n   \u003cimg height=\"350\" alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=caezium/Burrow\u0026type=timeline\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n\n## How Burrow compares to other tools\n\nA factual feature/scope comparison. The competitor columns are the **macOS**\nlandscape; the Windows column reflects only the checked-in preview.\n**mole.fit** is from the original author of `mo` — buy it ($19) if you want that\nand to fund `mo`.\n\n|  | Burrow (macOS) | Burrow (Windows preview) | mole.fit | CleanMyMac | Pearcleaner | `mo` / ncdu |\n|---|:---:|:---:|:---:|:---:|:---:|:---:|\n| Price | Free | Free | $19 once | Subscription | Free | Free |\n| Open source | MIT | MIT | – | – | ✅ | ✅ (`mo`) |\n| Signed / notarized | No — unsigned current release | No — unsigned preview | ✅ | ✅ | ✅ | n/a |\n| Junk cleanup | ✅ | partial - Clean route pending | ✅ | ✅ | – | ✅ (`mo`) |\n| Dev-artifact purge | ✅ | ✅ | ✅ | partial | – | ✅ (`mo`) |\n| Leftover-installer sweep | ✅ | ✅ | ✅ | ✅ | – | ✅ (`mo`) |\n| Uninstall + leftovers | ✅ | ✅ | ✅ | ✅ | ✅ *(focus)* | ✅ (`mo`) |\n| Disk treemap | ✅ | ✅ | ✅ | ✅ | – | ncdu *(TUI)* |\n| Live system monitor | ✅ | ✅ | ✅ | partial | – | – |\n| Long-term metric history | ✅ | ✅ *(JSON)* | – | – | – | – |\n| MCP / agent API | ✅ | ✅ | – | – | – | – |\n| GUI | ✅ | ✅ | ✅ | ✅ | ✅ | – *(terminal)* |\n\n## Settings\n\nEverything is local and takes effect immediately unless noted:\n\n| Setting | What it controls |\n|---|---|\n| **History retention** | How long metric history is kept (1 day → 1 year); older rows are pruned hourly. |\n| **Vacuum after large prunes** | Reclaim DB file space after a big prune (off by default). |\n| **Sampling rate** | How often Burrow runs `mo status --json` (5 s → 5 min). |\n| **App language** | Follow the system, or force English / 简体中文 / 繁體中文 *(relaunch)*. |\n| **Menu-bar icon** | Show the menu-bar item, or run as a regular Dock app instead. |\n| **MCP / agent access** | Copyable stdio config + the tool list for Claude Code, Cursor, Codex, Cline, and any MCP client. |\n| **Local HTTP query server** | Optional loopback REST endpoints + port for dashboards/curl. On Windows, disabling this keeps the local `/mcp` bridge available for stdio MCP. |\n| **Mole engine** | Shows the engine version Burrow is running, with a one-click **Update Mole**. |\n\n## Permissions \u0026 Full Disk Access\n\nCleaning system and app caches means reading TCC-protected folders, so macOS\nwill prompt — once per folder — unless the app has **Full Disk Access**. Burrow\nhandles this honestly:\n\n- Before a flood-prone scan it shows a gate explaining the trade-off, with a\n  one-click link to **System Settings → Full Disk Access** (grant once, no more\n  prompts).\n- Don't want to grant it? **Scan with admin** runs the same scan as root —\n  root bypasses TCC, so it's a single password prompt instead of a flood.\n- Burrow only ever reads sizes; it never opens that data itself, and the real\n  cleanup always goes through macOS's own admin dialog.\n\n## Requirements\n\n### macOS\n\n- **macOS 14+**\n- **No separate engine install.** Burrow bundles its own MIT engine\n  (`burrow-engine`) and runs it directly. _(Building from source? The engine is\n  staged from a git submodule; if it isn't present, Burrow falls back to a\n  system `mo` — `brew install mole`.)_\n\n### Windows preview\n\n- **Windows 10/11**\n- **.NET 8 SDK** for local build/test.\n- **Inno Setup** only when running the unsigned release packaging script.\n\n## Install\n\n\u003e macOS releases are currently unsigned. Each macOS path below clears the\n\u003e Gatekeeper quarantine for you. The full security/trust write-up — network,\n\u003e admin rights, and the trade-offs — is in **[SECURITY.md](SECURITY.md)**.\n\n### Homebrew (recommended)\n\n```bash\nbrew install --cask caezium/tap/burrow   # the app + bundled engine (clears quarantine)\n```\n\n### Direct download\n\nDownload `Burrow-x.y.z.zip` from\n[Releases](https://github.com/caezium/Burrow/releases), unzip into\n`/Applications`, then:\n\n```bash\nxattr -cr /Applications/Burrow.app\nopen /Applications/Burrow.app\n```\n\n### macOS build from source\n\n```bash\nbrew install xcodegen mole\ngit clone https://github.com/caezium/Burrow.git \u0026\u0026 cd Burrow/macos\nbash ../scripts/fetch-sentry.sh   # vendor Sentry.xcframework (it's a local framework, not an SPM dep)\nxcodegen generate\nxcodebuild -project Burrow.xcodeproj -scheme Burrow \\\n  -configuration Release -destination 'generic/platform=macOS' \\\n  -derivedDataPath build \\\n  CODE_SIGN_IDENTITY=\"\" CODE_SIGNING_REQUIRED=NO CODE_SIGNING_ALLOWED=NO build\ncp -R build/Build/Products/Release/Burrow.app /Applications/\nxattr -cr /Applications/Burrow.app\nopen /Applications/Burrow.app\n```\n\nBurrow lives in the menu bar (it's a menu-bar agent). Click the icon → **Open\nBurrow** — or turn the menu-bar icon off in Settings to run it as a Dock app.\n\n### Windows preview build\n\n```powershell\ngit clone https://github.com/caezium/Burrow.git\ncd Burrow\\windows\ndotnet restore .\\BurrowWin.sln\ndotnet build .\\BurrowWin.csproj -c Release -p:Platform=x64 -nr:false -v:minimal\ndotnet test .\\Tests\\BurrowWin.Tests\\BurrowWin.Tests.csproj -c Release -v:minimal\n```\n\nTo create the checked-in unsigned preview artifacts locally:\n\n```powershell\n.\\scripts\\build-release.ps1\n```\n\nThat script builds the app, runs tests, publishes the WinUI payload, creates an\nunsigned Inno Setup installer, creates a portable ZIP fallback, writes\n`SHA256SUMS.txt`, and writes WinGet manifests. See\n[`windows/docs/release.md`](windows/docs/release.md).\n\n## Security \u0026 trust\n\nBurrow drives a bundled, open-source Mole engine (an MIT fork of `mo`). The honest privacy picture:\n\n- **No accounts, no ads.** Your metrics, history, and file contents stay on\n  your machine. The macOS app sends opt-out, anonymous usage analytics and crash\n  reports (no files, paths, metrics, or stored IP — sizes/counts are\n  bucketed); turn it off in Settings. Full list in **[TELEMETRY.md](TELEMETRY.md)**.\n- **No background root helper.** When Clean/Optimize need admin rights, macOS's\n  own dialog asks you and Burrow runs that one `mo` command, then exits — you\n  approve every elevation.\n- **Local-only surfaces:** the MCP/HTTP surfaces bind to loopback only\n  (`127.0.0.1`) and history is stored locally. On Windows, the HTTP REST toggle\n  disables REST endpoints but keeps the local `/mcp` bridge route available for\n  stdio MCP clients. The macOS Updates tab runs `brew outdated`, the same check\n  `brew` does for itself.\n- **Unsigned preview builds:** macOS release zips and Windows preview artifacts\n  are unsigned in the current repo state. Windows direct-download users should\n  expect SmartScreen or stricter Application Control policy prompts.\n- The full honest write-up, including macOS admin trade-offs and the \"Scan with\n  admin\" option, is in **[SECURITY.md](SECURITY.md)**.\n\n## Use it with your AI agent\n\nBurrow doubles as an [MCP](https://modelcontextprotocol.io) server over stdio,\nso **any MCP-capable agent** — Claude Code, Cursor, Codex, Cline, Zed, and\nothers — can read your machine's recent state. Same server, same `{command, args}`\nshape everywhere.\n\n### Let your agent set it up\n\nFor macOS, paste this to your coding agent and it'll wire itself in:\n\n\u003e Add the **Burrow** MCP server to my config so you can read my Mac's system\n\u003e history. It's a local stdio MCP server — run it as `burrow mcp` if the\n\u003e Homebrew shim is on my PATH, otherwise\n\u003e `/Applications/Burrow.app/Contents/MacOS/Burrow` with args `[\"--mcp\"]`. Add it\n\u003e under my MCP servers, reload, and confirm the tools `burrow_snapshot`,\n\u003e `burrow_history`, `burrow_top_processes`, `burrow_process_usage`, and\n\u003e `burrow_info` are available. Then tell me my Mac's current CPU and memory.\n\n### Or configure it manually\n\nThe config is the same JSON for every agent — only the file differs:\n\n```json\n{\n  \"mcpServers\": {\n    \"burrow\": {\n      \"command\": \"/Applications/Burrow.app/Contents/MacOS/Burrow\",\n      \"args\": [\"--mcp\"]\n    }\n  }\n}\n```\n\n| Agent | Where it goes |\n|---|---|\n| **Claude Code** | `~/.claude/settings.json` — or `claude mcp add burrow -- /Applications/Burrow.app/Contents/MacOS/Burrow --mcp` |\n| **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project) |\n| **Codex** | add a `[mcp_servers.burrow]` entry in `~/.codex/config.toml` |\n| **Cline / Zed / other** | the client's \"MCP servers\" / `mcpServers` config |\n\nIf you installed via Homebrew, a `burrow` shim is on your PATH, so you can use\n`command: \"burrow\", args: [\"mcp\"]` instead of the bundle path. Reload the agent\nand ask in plain language.\n\nWindows preview builds include the stdio bridge in source under\n`windows/Tools/McpStdioBridge/` and in release artifacts as\n`Assets\\Mcp\\burrow-mcp-stdio.exe`.\n\n**Tools** — 19 over MCP, read-only by default. The full reference, with **when an\nagent should reach for each**, is in **[docs/agent-tools.md](docs/agent-tools.md)**.\nThe essentials:\n\n- **Status \u0026 history** — `burrow_snapshot`, `burrow_history`, `burrow_top_processes`,\n  `burrow_process_usage` (rank by `cpu_time`/`peak_cpu`/`avg_cpu`/`peak_mem`),\n  `burrow_diff`, `burrow_disk_forecast`, `burrow_report`\n- **Diagnose** — `burrow_doctor` (Full Disk Access, memory pressure, disk headroom,\n  SIP/Gatekeeper/FileVault/firewall, battery, high-CPU, display/volume/network),\n  `burrow_ports`, `burrow_info`\n- **Disk \u0026 apps** — `burrow_analyze`, `burrow_list_apps`, `burrow_cleanup_history`,\n  `burrow_deleted_files`\n- **Maintain (gated)** — `burrow_clean`, `burrow_optimize`, `burrow_uninstall`,\n  `burrow_purge`, `burrow_installer`\n\nActuating tools preview (`--dry-run`) unless `confirm:true` **and** the matching\nSettings opt-in is enabled — an agent can always look, but only acts with your say-so.\n\nWindows also keeps `burrow_uninstall(action=...)` as a compatibility tool for\nlist, leftover-preview, and confirmed vendor-uninstaller launch workflows.\n\nThere's also an optional localhost REST API (`127.0.0.1:9277` — `/health`,\n`/info`, `/snapshot`, `/metrics`) for dashboards or curl. On Windows, disabling\nREST in Settings does not close the loopback listener because the stdio MCP\nbridge still posts to `/mcp`.\n\n## Develop \u0026 test\n\n### macOS\n\n```bash\ncd macos        # the macOS app lives here (monorepo: macos/ + windows/)\nbash ../scripts/fetch-sentry.sh   # vendor Sentry.xcframework (it's a local framework, not an SPM dep)\nxcodegen generate\nxcodebuild -project Burrow.xcodeproj -scheme Burrow \\\n  -configuration Debug -destination 'platform=macOS' test\n```\n\nThe suite covers the parts that matter through public interfaces: DB roundtrip\n+ range + stride sampler + prune + corruption recovery, Store clamping/defaults,\nMaintenance prune, MCP tool routing + the semantic usage ranking, squarified\ntreemap invariants, the Full Disk Access decision, and `mo` output parsing.\n\n### Windows preview\n\n```powershell\ncd windows\ndotnet restore .\\BurrowWin.sln\ndotnet build .\\BurrowWin.csproj -c Release -p:Platform=x64 -nr:false -v:minimal\ndotnet build .\\Tests\\BurrowWin.Tests\\BurrowWin.Tests.csproj -c Release -nr:false -v:minimal\ndotnet test .\\Tests\\BurrowWin.Tests\\BurrowWin.Tests.csproj -c Release --no-build -v:minimal\n```\n\nFor local GUI smoke checks:\n\n```powershell\n.\\run-local.ps1 -NoBuild -SmokeTest -Restart -RequireHealth -Route settings -TimeoutSeconds 60\n```\n\n## Architecture\n\n### macOS\n\n```\nmo status --json   ──\u003e  Sampler ──\u003e SQLite (WAL) ──┬─\u003e Status / History (charts)\n                                                   ├─\u003e HTTP QueryServer (:9277)\n                                                   └─\u003e burrow mcp (stdio) ─\u003e Claude Code / Cursor / Codex\nmo analyze --json  ──\u003e  DiskScanner + squarified Treemap ──────\u003e Analyze\nmo clean / purge / installer / optimize ─\u003e CommandRunner (streamed) ─\u003e the tool tabs\nmo uninstall --list ─\u003e  Software (+ brew outdated for Updates)\n```\n\nOne binary, two modes: default is the menu-bar GUI; `burrow mcp` (or `Burrow\n--mcp`) is the stdio MCP server (it forks before SwiftUI claims the process).\nThe whole UI is one translucent window with a top-pill nav (`Brand`/`Tool`\ndesign system); Settings, History, and Activity are panes in that same window.\n\n### Windows preview\n\nThe Windows app is a WinUI 3 / .NET 8 project in [`windows/`](windows/) using\nMVVM view models, service-layer Windows/Mole integration, local JSONL history,\nloopback HTTP, and a stdio MCP bridge. Mole remains the preferred engine path\nwhere it is safe and non-interactive; Windows-native fallbacks cover current\ngaps in the Windows Mole branch. See\n[`windows/docs/windows-architecture.md`](windows/docs/windows-architecture.md).\n\n## Attribution \u0026 license\n\n[MIT](LICENSE).\n\n- **Mole CLI** (`mo`) is © [tw93](https://github.com/tw93/Mole), MIT. Burrow\n  bundles **`burrow-engine`**, an MIT fork of Mole pinned at its last MIT\n  release, and runs that as its engine.\n- Inspired by the **mole.fit** Mac app (same author as `mo`). Burrow is an\n  independent reimplementation with its own brand — no assets, icons, copy, or\n  trade dress are taken from mole.fit.\n- The history-DB + MCP pattern shares lineage with the same author's\n  [Stats fork](https://github.com/caezium/stats) (`caezium/stats@henry/history-mcp`).\n- Treemap layout: Bruls, Huijsen \u0026 van Wijk (2000), \"Squarified Treemaps,\"\n  re-implemented from scratch in Swift.\n\n## Contributing\n\nBurrow is community-driven. The repo currently contains the macOS app in\n[`macos/`](macos/) and the Windows preview in [`windows/`](windows/). We welcome\nbug fixes, tests, documentation improvements, and focused improvements to the\nchecked-in platform implementations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaezium%2FBurrow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaezium%2FBurrow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaezium%2FBurrow/lists"}