Burrow

Burrow is an independent open-source project. It bundles its own MIT engine — burrow-engine, a fork of the Mole (mo) CLI by tw93 — and is not affiliated with or endorsed by mole.fit (the official Mole for Mac app by mo's author); its own name, mark, palette, and copy are original.

If you like Mole and want to fund mo's development — buy mole.fit ($19).

Burrow puts everything your Mac needs in one free, native app: junk cleanup, dev-artifact purge, app uninstall with leftover removal, duplicate finding, safe maintenance, disk maps, and live system status — powered by a bundled, audited open-source engine (burrow-engine, a fork of Mole's mo), so there's nothing else to install. And it does what no other cleaner does: it keeps months of local metric history and runs a built-in MCP server, so AI agents like Claude Code, Codex, and Cursor can watch, query, and care for your Mac — every action consent-gated, audited, and reversible. Native on macOS, with a Windows preview under windows/.

Mac:

brew install --cask caezium/tap/burrow

Windows: download from releases

Contents

• Screenshots
• The tools
• Platforms
• Roadmap
• How Burrow compares to other tools
• Settings
• Permissions & Full Disk Access
• Requirements
• Install
• Security & trust
• Use it with your AI agent
• Develop & test
• Architecture
• Attribution & license

Screenshots

macOS

Windows preview

The tools

Burrow wraps a bundled, open-source Mole engine in a native desktop app: clean junk, purge dev artifacts, sweep leftover installers, uninstall apps, run safe maintenance, map your disk, and watch live system status — in one window. On top of that it adds things the CLI doesn't have: a long-running history of your machine's metrics in a local store and an MCP server so any AI agent (Claude Code, Cursor, Codex…) can ask "what's been happening on this machine."

macOS is the mature flagship. Windows currently has a native WinUI 3 / .NET 8 preview app, Windows telemetry/history, tray HUD, loopback HTTP, MCP stdio bridge, CI, tests, and unsigned release packaging.

Every scan offers a no-risk preview (--dry-run) first, a clear reclaimed-space summary when it finishes, and a Stop button to abort a running job.

What's on the Status dashboard

A live, glanceable read of your Mac's vitals, refreshed continuously:

• CPU — usage, load averages (1/5/15), core count, temperature
• Memory — used %, pressure (normal/warning/critical), swap
• GPU — name and utilisation (Apple Silicon via IOAccelerator)
• Disk — capacity and live read/write I/O rates
• Network — up/down throughput per interface
• Battery — percentage, health, cycle count, time remaining
• Health score — Mole's overall 0–100 rating, with a one-line reason
• Top processes — by CPU or memory, sortable and pinnable

Burrow's own extras

• History — long-range charts (5 m → 90 d) over a local SQLite history of every metric, plus peak-per-process tables. Nothing the CLI keeps.
• Activity — a running log of what Burrow has done (cleans, optimizes, scans) and the live status of anything in flight.
• Menu-bar HUD — health hero, metric tiles, top processes, and live job status, all from the menu bar (you can also run as a Dock app instead).
• MCP server — a stdio JSON-RPC server (burrow mcp / Burrow --mcp) plus an optional localhost HTTP API, so any AI agent can query your Mac's recent state. See Use it with your AI agent.

Platforms

Both apps live in this one repo, side by side, sharing this README, the landing site, and release documentation. The Windows preview currently includes a native shell, tool pages, local telemetry/history, loopback HTTP/MCP surfaces, tests, CI, and unsigned local packaging. See the Windows architecture notes and release notes.

Windows preview

The checked-in Windows app currently includes:

• A native WinUI 3 / .NET 8 shell with Dashboard, History, Activity, Analyze, Clean, Purge, Installers, Apps, Optimize, and Settings routes.
• Local Windows telemetry sampling for Dashboard, History, tray status, HTTP, and MCP.
• Local JSONL-backed history/activity storage.
• Optimize preview/confirm flows through Mole where available; the Windows Clean route is present but still a guarded pending stub until Mole Windows exposes a stable non-interactive cleanup contract for the GUI.
• Native Windows fallback flows for Analyze, Purge, installer cleanup, and app inventory where the Windows Mole branch is still interactive or lacks JSON.
• A tray icon, live tooltip, tray HUD, status menu, and quick navigation.
• A loopback-only HTTP API (/health, /info, /snapshot, /metrics) and a stdio MCP bridge with the read-only Burrow tools.
• Unit tests, Windows CI, local smoke-test helpers, and an unsigned release script that produces a setup executable, portable ZIP, hashes, and WinGet manifests.

Roadmap

The full board, with status and voting, lives at burrow.henryzh.dev/roadmap. Vote by upvoting an issue, or open a request.

Planned

• Signed & notarized macOS builds — A Developer ID signature so Gatekeeper trusts Burrow without the right-click → Open dance.
• In-app auto-update — Once builds are signed, silent background update checks with a one-click install (Sparkle).
• Windows preview → first stable — Data-loss and supply-chain hardening, parity, and test coverage before it loses the “preview” label. (#93)

Considering

• Persistent one-tap “run all” Tune-Up — A saved Smart-Care routine you trigger in one tap from the dashboard. (#77)

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.

How Burrow compares to other tools

A factual feature/scope comparison. The competitor columns are the macOS landscape; the Windows column reflects only the checked-in preview. mole.fit is from the original author of mo — buy it ($19) if you want that and to fund mo.

Settings

Everything is local and takes effect immediately unless noted:

Permissions & Full Disk Access

Cleaning system and app caches means reading TCC-protected folders, so macOS will prompt — once per folder — unless the app has Full Disk Access. Burrow handles this honestly:

• Before a flood-prone scan it shows a gate explaining the trade-off, with a one-click link to System Settings → Full Disk Access (grant once, no more prompts).
• Don't want to grant it? Scan with admin runs the same scan as root — root bypasses TCC, so it's a single password prompt instead of a flood.
• Burrow only ever reads sizes; it never opens that data itself, and the real cleanup always goes through macOS's own admin dialog.

Requirements

macOS

• macOS 14+
• No separate engine install. Burrow bundles its own MIT engine (burrow-engine) and runs it directly. (Building from source? The engine is staged from a git submodule; if it isn't present, Burrow falls back to a system mo — brew install mole.)

Windows preview

• Windows 10/11
• .NET 8 SDK for local build/test.
• Inno Setup only when running the unsigned release packaging script.

Install

macOS releases are currently unsigned. Each macOS path below clears the Gatekeeper quarantine for you. The full security/trust write-up — network, admin rights, and the trade-offs — is in SECURITY.md.

Homebrew (recommended)

brew install --cask caezium/tap/burrow   # the app + bundled engine (clears quarantine)

Direct download

Download Burrow-x.y.z.zip from Releases, unzip into /Applications, then:

xattr -cr /Applications/Burrow.app
open /Applications/Burrow.app

macOS build from source

brew install xcodegen mole
git clone https://github.com/caezium/Burrow.git && cd Burrow/macos
bash ../scripts/fetch-sentry.sh   # vendor Sentry.xcframework (it's a local framework, not an SPM dep)
xcodegen generate
xcodebuild -project Burrow.xcodeproj -scheme Burrow \
  -configuration Release -destination 'generic/platform=macOS' \
  -derivedDataPath build \
  CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO CODE_SIGNING_ALLOWED=NO build
cp -R build/Build/Products/Release/Burrow.app /Applications/
xattr -cr /Applications/Burrow.app
open /Applications/Burrow.app

Burrow lives in the menu bar (it's a menu-bar agent). Click the icon → Open Burrow — or turn the menu-bar icon off in Settings to run it as a Dock app.

Windows preview build

git clone https://github.com/caezium/Burrow.git
cd Burrow\windows
dotnet restore .\BurrowWin.sln
dotnet build .\BurrowWin.csproj -c Release -p:Platform=x64 -nr:false -v:minimal
dotnet test .\Tests\BurrowWin.Tests\BurrowWin.Tests.csproj -c Release -v:minimal

To create the checked-in unsigned preview artifacts locally:

.\scripts\build-release.ps1

That script builds the app, runs tests, publishes the WinUI payload, creates an unsigned Inno Setup installer, creates a portable ZIP fallback, writes SHA256SUMS.txt, and writes WinGet manifests. See windows/docs/release.md.

Security & trust

Burrow drives a bundled, open-source Mole engine (an MIT fork of mo). The honest privacy picture:

• No accounts, no ads. Your metrics, history, and file contents stay on your machine. The macOS app sends opt-out, anonymous usage analytics and crash reports (no files, paths, metrics, or stored IP — sizes/counts are bucketed); turn it off in Settings. Full list in TELEMETRY.md.
• No background root helper. When Clean/Optimize need admin rights, macOS's own dialog asks you and Burrow runs that one mo command, then exits — you approve every elevation.
• Local-only surfaces: the MCP/HTTP surfaces bind to loopback only (127.0.0.1) and history is stored locally. On Windows, the HTTP REST toggle disables REST endpoints but keeps the local /mcp bridge route available for stdio MCP clients. The macOS Updates tab runs brew outdated, the same check brew does for itself.
• Unsigned preview builds: macOS release zips and Windows preview artifacts are unsigned in the current repo state. Windows direct-download users should expect SmartScreen or stricter Application Control policy prompts.
• The full honest write-up, including macOS admin trade-offs and the "Scan with admin" option, is in SECURITY.md.

Use it with your AI agent

Burrow doubles as an MCP server over stdio, so any MCP-capable agent — Claude Code, Cursor, Codex, Cline, Zed, and others — can read your machine's recent state. Same server, same {command, args} shape everywhere.

Let your agent set it up

For macOS, paste this to your coding agent and it'll wire itself in:

Add the Burrow MCP server to my config so you can read my Mac's system history. It's a local stdio MCP server — run it as burrow mcp if the Homebrew shim is on my PATH, otherwise /Applications/Burrow.app/Contents/MacOS/Burrow with args ["--mcp"]. Add it under my MCP servers, reload, and confirm the tools burrow_snapshot, burrow_history, burrow_top_processes, burrow_process_usage, and burrow_info are available. Then tell me my Mac's current CPU and memory.

Or configure it manually

The config is the same JSON for every agent — only the file differs:

{
  "mcpServers": {
    "burrow": {
      "command": "/Applications/Burrow.app/Contents/MacOS/Burrow",
      "args": ["--mcp"]
    }
  }
}

If you installed via Homebrew, a burrow shim is on your PATH, so you can use command: "burrow", args: ["mcp"] instead of the bundle path. Reload the agent and ask in plain language.

Windows preview builds include the stdio bridge in source under windows/Tools/McpStdioBridge/ and in release artifacts as Assets\Mcp\burrow-mcp-stdio.exe.

Tools — 19 over MCP, read-only by default. The full reference, with when an agent should reach for each, is in docs/agent-tools.md. The essentials:

• Status & history — burrow_snapshot, burrow_history, burrow_top_processes, burrow_process_usage (rank by cpu_time/peak_cpu/avg_cpu/peak_mem), burrow_diff, burrow_disk_forecast, burrow_report
• Diagnose — burrow_doctor (Full Disk Access, memory pressure, disk headroom, SIP/Gatekeeper/FileVault/firewall, battery, high-CPU, display/volume/network), burrow_ports, burrow_info
• Disk & apps — burrow_analyze, burrow_list_apps, burrow_cleanup_history, burrow_deleted_files
• Maintain (gated) — burrow_clean, burrow_optimize, burrow_uninstall, burrow_purge, burrow_installer

Actuating tools preview (--dry-run) unless confirm:true and the matching Settings opt-in is enabled — an agent can always look, but only acts with your say-so.

Windows also keeps burrow_uninstall(action=...) as a compatibility tool for list, leftover-preview, and confirmed vendor-uninstaller launch workflows.

There's also an optional localhost REST API (127.0.0.1:9277 — /health, /info, /snapshot, /metrics) for dashboards or curl. On Windows, disabling REST in Settings does not close the loopback listener because the stdio MCP bridge still posts to /mcp.

Develop & test

macOS

cd macos        # the macOS app lives here (monorepo: macos/ + windows/)
bash ../scripts/fetch-sentry.sh   # vendor Sentry.xcframework (it's a local framework, not an SPM dep)
xcodegen generate
xcodebuild -project Burrow.xcodeproj -scheme Burrow \
  -configuration Debug -destination 'platform=macOS' test

The suite covers the parts that matter through public interfaces: DB roundtrip

• range + stride sampler + prune + corruption recovery, Store clamping/defaults, Maintenance prune, MCP tool routing + the semantic usage ranking, squarified treemap invariants, the Full Disk Access decision, and mo output parsing.

Windows preview

cd windows
dotnet restore .\BurrowWin.sln
dotnet build .\BurrowWin.csproj -c Release -p:Platform=x64 -nr:false -v:minimal
dotnet build .\Tests\BurrowWin.Tests\BurrowWin.Tests.csproj -c Release -nr:false -v:minimal
dotnet test .\Tests\BurrowWin.Tests\BurrowWin.Tests.csproj -c Release --no-build -v:minimal

For local GUI smoke checks:

.\run-local.ps1 -NoBuild -SmokeTest -Restart -RequireHealth -Route settings -TimeoutSeconds 60

Architecture

macOS

mo status --json   ──>  Sampler ──> SQLite (WAL) ──┬─> Status / History (charts)
                                                   ├─> HTTP QueryServer (:9277)
                                                   └─> burrow mcp (stdio) ─> Claude Code / Cursor / Codex
mo analyze --json  ──>  DiskScanner + squarified Treemap ──────> Analyze
mo clean / purge / installer / optimize ─> CommandRunner (streamed) ─> the tool tabs
mo uninstall --list ─>  Software (+ brew outdated for Updates)

One binary, two modes: default is the menu-bar GUI; burrow mcp (or Burrow --mcp) is the stdio MCP server (it forks before SwiftUI claims the process). The whole UI is one translucent window with a top-pill nav (Brand/Tool design system); Settings, History, and Activity are panes in that same window.

Windows preview

The Windows app is a WinUI 3 / .NET 8 project in windows/ using MVVM view models, service-layer Windows/Mole integration, local JSONL history, loopback HTTP, and a stdio MCP bridge. Mole remains the preferred engine path where it is safe and non-interactive; Windows-native fallbacks cover current gaps in the Windows Mole branch. See windows/docs/windows-architecture.md.

Attribution & license

MIT.

• Mole CLI (mo) is © tw93, MIT. Burrow bundles burrow-engine, an MIT fork of Mole pinned at its last MIT release, and runs that as its engine.
• Inspired by the mole.fit Mac app (same author as mo). Burrow is an independent reimplementation with its own brand — no assets, icons, copy, or trade dress are taken from mole.fit.
• The history-DB + MCP pattern shares lineage with the same author's Stats fork (caezium/stats@henry/history-mcp).
• Treemap layout: Bruls, Huijsen & van Wijk (2000), "Squarified Treemaps," re-implemented from scratch in Swift.

Contributing

Burrow is community-driven. The repo currently contains the macOS app in macos/ and the Windows preview in windows/. We welcome bug fixes, tests, documentation improvements, and focused improvements to the checked-in platform implementations.