burrow

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 one bundled engine binary (burrow-engine, FSL-1.1 — see Attribution) whose commands mirror Mole's mo, so there's nothing else to install. 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 — actions are consent-gated and audited, and Trash-based removals remain recoverable until the Trash is emptied. Permanent deletion requires separate consent and cannot be undone. 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

Explain 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.

When 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.

Windows preview

Windows TypeScript rewrite: An initial Electron + React implementation that follows the current macOS UI is available in windows/typescript/. It includes live telemetry, local history, reviewed artifact/installer recycling, disk analysis, and read-only duplicate detection. The existing WinUI preview remains alongside it. See the migration status for capability gaps and Windows validation requirements.

The tools

Burrow wraps its bundled burrow-engine binary 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.
• Signed native updates — Sparkle checks a signed feed and presents its native update UI; archives and the feed are both Ed25519-signed, and nothing downloads or installs automatically. A real 0.11.0-to-0.11.1 update completed without Terminal or Homebrew and relaunched the notarized app successfully. (#281)

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.computer/roadmap. Vote by upvoting an issue, or open a request.

Building

• A single interface for machine care and agent work, Burrow grew tool by tool. The next pass designs it as one product: one navigation model, one task hierarchy, and a clear place for the agent surfaces that arrived late.

Planned

• Windows preview → first stable, Data-loss and supply-chain hardening, parity, and test coverage before it loses the “preview” label. (#93)
• Uninstall that never quietly does nothing, A handful of Homebrew apps use a cask token that differs from the display name, so a name-based lookup resolves most apps and misses the exceptions. Uninstall gets exact resolution and a visible result either way.

Considering

• Persistent one-tap “run all” Tune-Up, A saved Smart-Care routine you trigger in one tap from the dashboard. (#77)
• Faster, deeper Analyze, Better navigation through very large trees, quicker re-render on drill-down, and caching so a second scan of the same volume is close to instant.

Recently shipped: Developer ID signed & Apple-notarized macOS releases, Signed Sparkle feed + updater foundation, Stable Full Disk Access identity across updates, Bundled MIT engine, no separate mo install, Process inspector + CPU watchdog, 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 engine (burrow-engine, one FSL-1.1 binary) and runs it directly. (Building from source? The engine is staged from the public macos/vendor/burrow-engine submodule, with no GitHub read token required. Without an initialized engine submodule, Burrow falls back to a system mo — brew install mole — with mo's own argv conventions.)

Windows preview

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

Install

Burrow 0.11.0 is the first Developer ID-signed and Apple-notarized release. New official macOS tags must pass signing, notarization, ticket stapling, and Gatekeeper assessment before they can publish. Version 0.10.5 used an ad-hoc signature rather than Developer ID and was not notarized; older archives also predate the current distribution guarantee. The full security/trust write-up is in SECURITY.md.

Homebrew (recommended)

brew install --cask caezium/tap/burrow   # the app + bundled engine

The live cask installs the signed and notarized build, preserves quarantine so Gatekeeper can validate Apple's ticket, and contains no postflight bypass or unsigned-build warning. It is marked auto_updates true because Sparkle owns in-app updates.

Direct download

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

open /Applications/Burrow.app

Keep the downloaded app's quarantine metadata intact: Gatekeeper uses it to verify the stapled notarization ticket. If you're intentionally installing an archived 0.10.5-or-earlier build, right-click the app and choose Open; those builds predate the notarization ticket.

macOS build from source

brew install xcodegen
git clone https://github.com/caezium/Burrow.git && cd Burrow
bash scripts/release.sh
cp -R build_dist/Build/Products/Release/Burrow.app /Applications/
open /Applications/Burrow.app

The local script applies a coherent ad-hoc signature to the app and every bundled executable so Full Disk Access works during development. Only official tag builds use the private Developer ID identity and Apple notarization.

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. If a macOS build freezes while Burrow creates that status item, the next launch stays in Dock-based compatibility mode on the same OS build and offers a one-click redacted diagnostic report. Automatic Sparkle startup waits until the initial AppKit launch turn has settled and the status item is stable; if the updater then fails its own stability window, later automatic checks pause for that app/OS build while manual checks remain available. A new macOS build retries a guarded status item; a new Burrow or macOS build retries an updater that previously failed its stability window.

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 one bundled engine binary, burrow-engine (FSL-1.1-ALv2; its source is publicly available and the signed binary ships inside the app — see Attribution), plus an MIT fclones sidecar for duplicate finding. 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 plus crash, hang, startup, update, and sampled performance diagnostics. It sends no screen recordings, user files, user paths, metrics, or stored IP; turn it off in Settings. PostHog delivery and its bounded sanitized retry outbox run entirely off AppKit's main thread. Full list in TELEMETRY.md.
• No background root helper by default. When Clean/Optimize — or an uninstall whose app bundle needs an administrator — need admin rights, macOS's own dialog asks you and Burrow runs that one engine command as root, then exits — you approve every elevation. Every elevated run gets a fixed environment: BURROW_HOME points the engine back at your home (so an elevated uninstall removes your leftovers, not root's) and BURROW_PRIVILEGED=1 makes it refuse user-writable sidecar overrides. You can opt in to a small signed helper so those prompts accept Touch ID; it grants no standing privilege (every root operation still authenticates, every time), performs only scan, clean, and optimize, and can be removed from Settings. Details in SECURITY.md.
• 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 reads Homebrew's local index when it opens and runs brew update only when you click Refresh, the same fetch brew does for itself.
• Distribution signatures: new official macOS tags fail unless Developer ID signing, notarization, and the signed Sparkle ZIP/feed checks pass; local macOS builds use an ad-hoc development identity. Windows preview artifacts remain unsigned, so 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. Loopback is a network boundary, not authentication: every request needs the random per-install bearer credential, an exact localhost Host, no browser Origin, and stays inside the request-size/rate limits. On macOS, read the credential locally with defaults read dev.caezium.Burrow query_auth_token; on Windows it lives in the current user's %LOCALAPPDATA%\BurrowWin\settings.json, and the stdio bridge adds it automatically. Disabling Windows REST does not close the listener because the authenticated stdio bridge still posts to /mcp.

BURROW_HTTP_TOKEN="$(defaults read dev.caezium.Burrow query_auth_token)"
curl -H "Authorization: Bearer $BURROW_HTTP_TOKEN" http://127.0.0.1:9277/health

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)
bash ../scripts/fetch-sparkle.sh  # vendor the checksum-pinned official Sparkle.framework
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

Contents/Resources/burrow  (burrow-engine, one binary; one {ok, data|error} envelope per command,
                            NDJSON when streamed)
burrow status --watch          ──> SnapshotProducer (one long-lived stream, one line per tick;
                                   polls `status --json` only if the stream drops)
                                   ──> SQLite (WAL) ──┬─> Status / History (charts)
                                                      ├─> HTTP QueryServer (:9277)
                                                      └─> Burrow --mcp (stdio) ─> Claude Code / Cursor / Codex
burrow analyze --progress <p>  ──> live file/dir/byte ticks, then the full payload
                                   ──> DiskScanner + squarified Treemap ─> Analyze
                                   (one `analyze` per child directory is the fallback)
burrow clean|optimize|purge --stream ─> OperationFlow (NDJSON, live on both elevation routes:
                                        the helper relays stdout over XPC, osascript tails the
                                        root shell's log) ─> Clean / Optimize / Purge
burrow clean --apply --permanent --plan <file> --stream
                               ──> the reviewed clean: Confirm writes the ticked paths to a plan
                                   file and the engine removes only those — no re-scan — and
                                   reports each one back (removed / failed / protected + reason)
burrow installer, uninstall [--apply] ─> Installers / Software (buffered envelope; uninstall is
                                        elevated only when the bundle needs an administrator)
burrow dupes|orphans|photos|net --json ─> Duplicates / Leftovers / Photos / Network (+ fclones sidecar)

The Swift side names the seams after what they are: BurrowEngine resolves and spawns the bundled binary and parses its envelope, EngineRunner is the one capture/stream/PTY facade, EngineCLI is discovery plus the elevated do shell script builder, and MoActions is the single gate that mints every destructive run for the GUI and the MCP server alike. A source build without an initialized engine submodule falls back to a system mo, whose argv is the inverse of the engine's (mo runs live by default; the engine previews by default and needs --apply) — BurrowEngine.engineArgv is the one translation, applied only when the resolved binary is the bundled engine.

One app binary, two modes: default is the menu-bar GUI; 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

Burrow (this repository) is MIT. The app bundle ships two separately licensed binaries — the full notices are in NOTICE:

• burrow-engine (Contents/Resources/burrow) is © 2026 caezium, licensed under the Functional Source License 1.1, ALv2 future license (FSL-1.1-ALv2). Its source lives in the public caezium/burrow-engine repository, vendored as a submodule and built into a single universal binary at release time; the binary ships with its license and dependency notices under Contents/Resources/licenses/burrow-engine/. Its command surface (clean, optimize, uninstall, analyze, status, …) is modelled on Mole CLI (mo), which is © tw93, MIT — Burrow no longer bundles a fork of Mole's code.
• fclones (Contents/Resources/fclones) is © Piotr Kołaczkowski, MIT — the duplicate-file engine behind the Duplicates pane.
• 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.

内容由编辑整理，部分信息来自 GitHub 与项目官网，版权归原作者所有。发现错误？报告问题