Skip to content
Back to search

Burrow

๐Ÿน Cleanup, app management, maintenance, disk analysis, and live status in one free, open-source, native Mac app + extensive support for AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/caezium/Burrow with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/caezium/Burrow'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/caezium--burrow/badge.svg)](/listings/caezium--burrow)

HTML

<a href="/listings/caezium--burrow"><img src="/api/listings/caezium--burrow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> 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](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](https://github.com/caezium/Burrow/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`](windows/docs/release.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md ยท README ยท 644 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. > Burrow is an independent open-source (MIT) app. It bundles its own engine โ€”
  2. > `burrow-engine`, a single source-available binary under the Functional Source
  3. > License (FSL-1.1-ALv2) whose command surface is modelled on the
  4. > [Mole](https://github.com/tw93/Mole) (`mo`) CLI by tw93 โ€” and is **not
  5. > affiliated with or endorsed by [mole.fit](https://mole.fit/)** (the official
  6. > Mole for Mac app by `mo`'s author); its own name, mark, palette, and copy are
  7. > original.
  8. >
  9. > If you like Mole and want to fund `mo`'s development โ€” **buy mole.fit ($19)**.
  10. <div align="center">
  11. <h1>burrow</h1>
  12. <p><em>๐Ÿน The open-source system companion for your Mac โ€” clean, uninstall, analyze, optimize, and monitor, built for you and your AI agents.</em></p>
  13. </div>
  14. <p align="center">
  15. <a href="https://github.com/caezium/Burrow/stargazers"><img src="https://img.shields.io/github/stars/caezium/Burrow?style=flat-square" alt="Stars"></a>
  16. <a href="https://github.com/caezium/Burrow/releases"><img src="https://img.shields.io/github/v/tag/caezium/Burrow?label=version&style=flat-square" alt="Version"></a>
  17. <a href="https://github.com/caezium/Burrow/releases"><img src="https://img.shields.io/github/downloads/caezium/Burrow/total?style=flat-square&label=downloads" alt="Downloads"></a>
  18. <img src="https://img.shields.io/badge/macOS-14%2B-black?style=flat-square" alt="macOS 14+">
  19. <img src="https://img.shields.io/badge/Windows-10%2F11%20beta-blue?style=flat-square" alt="Windows beta">
  20. <img src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" alt="License: MIT">
  21. </p>
  22. <p align="center">
  23. <a href="https://trendshift.io/repositories/47076" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/47076" alt="caezium%2FBurrow | Trendshift" width="250" height="55"/></a>
  24. <a href="https://trendshift.io/repositories/47076" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/47076/daily?language=Swift" alt="caezium/Burrow on Trendshift" width="250" height="55"/></a>
  25. <a href="https://trendshift.io/repositories/47076" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/47076/weekly?language=Swift" alt="caezium%2FBurrow | Trendshift" width="250" height="55"/></a>
  26. </p>
  27. **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](https://github.com/caezium/burrow-engine), FSL-1.1 โ€” see [Attribution](#attribution--license)) whose commands mirror [Mole](https://github.com/tw93/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/`](windows/).**
  28. Mac:
  29. ```sh
  30. brew install --cask caezium/tap/burrow
  31. ```
  32. Windows: download from [releases](https://github.com/caezium/Burrow/releases)
  33. ## Contents
  34. - [Screenshots](#screenshots)
  35. - [The tools](#the-tools)
  36. - [Platforms](#platforms)
  37. - [Roadmap](#roadmap)
  38. - [How Burrow compares to other tools](#how-burrow-compares-to-other-tools)
  39. - [Settings](#settings)
  40. - [Permissions & Full Disk Access](#permissions--full-disk-access)
  41. - [Requirements](#requirements)
  42. - [Install](#install)
  43. - [Security & trust](#security--trust)
  44. - [Use it with your AI agent](#use-it-with-your-ai-agent)
  45. - [Develop & test](#develop--test)
  46. - [Architecture](#architecture)
  47. - [Attribution & license](#attribution--license)
  48. ## Screenshots
  49. ### macOS
  50. <table>
  51. <tr>
  52. <td><img alt="Status โ€” live CPU, memory, GPU, disk, network, and battery" src="docs/assets/shot-status.png"></td>
  53. <td><img alt="History โ€” long-range charts over a local SQLite metric history" src="docs/assets/shot-history.png"></td>
  54. </tr>
  55. <tr>
  56. <td><img alt="Analyze โ€” squarified treemap of your whole disk" src="docs/assets/shot-analyze.png"></td>
  57. <td><img alt="Clean โ€” hub for caches, dev build junk, and leftover installers" src="docs/assets/shot-clean.png"></td>
  58. </tr>
  59. <tr>
  60. <td><img alt="Clean โ€” scanning, with a live reclaimable total" src="docs/assets/shot-clean-running.png"></td>
  61. <td><img alt="Clean โ€” scan complete, reclaimable space found" src="docs/assets/shot-clean-result.png"></td>
  62. </tr>
  63. <tr>
  64. <td><img alt="Optimize โ€” maintenance running" src="docs/assets/shot-optimize-running.png"></td>
  65. <td><img alt="Optimize โ€” maintenance complete, areas refreshed" src="docs/assets/shot-optimize-done.png"></td>
  66. </tr>
  67. <tr>
  68. <td><img alt="Software โ€” installed apps with search, sort, and multi-select uninstall" src="docs/assets/shot-apps.png"></td>
  69. <td><img alt="Software โ€” Homebrew app updates" src="https://github.com/user-attachments/assets/8c3fa0bd-ba08-4dff-af5c-b0213b8adb69"></td>
  70. </tr>
  71. <tr>
  72. <td><img alt="Settings" src="https://github.com/user-attachments/assets/a642c5eb-6959-4b7a-a29a-de9bb9f0edb3"></td>
  73. </tr>
  74. </table>
  75. <p align="center">
  76. <img 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">
  77. </p>
  78. <p align="center">
  79. <em>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.</em>
  80. <br>
  81. <img alt="Explain with AI โ€” burrow_snapshot analyzed in plain language" src="https://raw.githubusercontent.com/caezium/Burrow/main/docs/assets/shot-ai.png">
  82. <em>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.</em>
  83. <br>
  84. <img width="1177" height="887" alt="image" src="https://github.com/user-attachments/assets/e067a39f-808b-41a8-ac02-9dd19cabf929" />
  85. </p>
  86. <p align="center">
  87. <img 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">
  88. </p>
  89. ### Windows preview
  90. <table>
  91. <tr>
  92. <td><img alt="Windows preview โ€” Status overview with health, CPU, memory, GPU, disk, network, and fan cards" src="docs/assets/shot-windows-status-overview.png"></td>
  93. </tr>
  94. <tr>
  95. <td><img alt="Windows preview โ€” Status battery and process table" src="docs/assets/shot-windows-status-processes.png"></td>
  96. </tr>
  97. <tr>
  98. <td><img alt="Windows preview โ€” History charts for CPU, memory, disk, and network" src="docs/assets/shot-windows-history.png"></td>
  99. </tr>
  100. <tr>
  101. <td><img alt="Windows preview โ€” Analyze treemap for disk usage" src="docs/assets/shot-windows-analyze.png"></td>
  102. </tr>
  103. <tr>
  104. <td><img alt="Windows preview โ€” Apps uninstall inventory sorted by size" src="docs/assets/shot-windows-apps.png"></td>
  105. </tr>
  106. </table>
  107. > **Windows TypeScript rewrite:** An initial Electron + React implementation that follows the current macOS UI is available in [`windows/typescript/`](windows/typescript/README.md). 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](windows/typescript/MIGRATION.md) for capability gaps and Windows validation requirements.
  108. ## The tools
  109. Burrow wraps its bundled `burrow-engine` binary in a native desktop app: clean
  110. junk, purge dev artifacts, sweep leftover installers, uninstall apps, run safe
  111. maintenance, map your disk, and watch live system status โ€” in one window. On top
  112. of that it adds things the CLI doesn't have: a **long-running history** of your
  113. machine's metrics in a local store and an **MCP server** so any AI agent (Claude
  114. Code, Cursor, Codexโ€ฆ) can ask "what's been happening on this machine."
  115. **macOS** is the mature flagship. **Windows** currently has a native WinUI 3 /
  116. .NET 8 preview app, Windows telemetry/history, tray HUD, loopback HTTP, MCP
  117. stdio bridge, CI, tests, and unsigned release packaging.
  118. | Tool | What it does | `mo` command |
  119. |---|---|---|
  120. | **Status** | Live dashboard with per-metric sparklines and a sortable/pinnable process table. | `mo status --json` |
  121. | **Clean** | Preview what's reclaimable, then clean for real โ€” categorized cache/log/leftover removal. | `mo clean` |
  122. | **Purge** | Reclaim space from dev projects: `node_modules`, build dirs, `target/`, `__pycache__`, and more โ€” preview streams in, one confirmation, everything found goes to the Trash. | `mo purge` |
  123. | **Installers** | Find and remove leftover `.dmg`/`.pkg` installer files in bulk. | `mo installer` |
  124. | **Optimize** | One-tap safe maintenance: rebuild caches, repair metadata, flush DNS, restart Dock/Finder. | `mo optimize` |
  125. | **Software** | Installed-app list with search/sort (size, name, recent, source) and multi-select uninstall; an **Updates** tab with a Mac apps / Homebrew picker, each half with its own check and update-all. | `mo uninstall --list`, `brew outdated` |
  126. | **Analyze** | Squarified treemap of your disk; drill into any folder, reveal in Finder. | `mo analyze --json` |
  127. Every scan offers a **no-risk preview** (`--dry-run`) first, a clear
  128. **reclaimed-space summary** when it finishes, and a **Stop** button to abort a
  129. running job.
  130. ### What's on the Status dashboard
  131. A live, glanceable read of your Mac's vitals, refreshed continuously:
  132. - **CPU** โ€” usage, load averages (1/5/15), core count, temperature
  133. - **Memory** โ€” used %, pressure (normal/warning/critical), swap
  134. - **GPU** โ€” name and utilisation (Apple Silicon via IOAccelerator)
  135. - **Disk** โ€” capacity and live read/write I/O rates
  136. - **Network** โ€” up/down throughput per interface
  137. - **Battery** โ€” percentage, health, cycle count, time remaining
  138. - **Health score** โ€” Mole's overall 0โ€“100 rating, with a one-line reason
  139. - **Top processes** โ€” by CPU or memory, sortable and pinnable
  140. ### Burrow's own extras
  141. - **History** โ€” long-range charts (5 m โ†’ 90 d) over a local SQLite history of
  142. every metric, plus peak-per-process tables. Nothing the CLI keeps.
  143. - **Activity** โ€” a running log of what Burrow has done (cleans, optimizes,
  144. scans) and the live status of anything in flight.
  145. - **Menu-bar HUD** โ€” health hero, metric tiles, top processes, and live job
  146. status, all from the menu bar (you can also run as a Dock app instead).
  147. - **MCP server** โ€” a stdio JSON-RPC server (`burrow mcp` / `Burrow --mcp`) plus
  148. an optional localhost HTTP API, so any AI agent can query your Mac's recent
  149. state. See [Use it with your AI agent](#use-it-with-your-ai-agent).
  150. - **Signed native updates** โ€” Sparkle checks a signed feed and presents its
  151. native update UI; archives and the feed are both Ed25519-signed, and nothing
  152. downloads or installs automatically. A real 0.11.0-to-0.11.1 update completed
  153. without Terminal or Homebrew and relaunched the notarized app successfully.
  154. ([#281](https://github.com/caezium/Burrow/issues/281))
  155. ## Platforms
  156. | | macOS | Windows |
  157. |---|---|---|
  158. | Status | **Stable** โ€” flagship | **Preview** โ€” checked in under `windows/` |
  159. | Engine | bundled Rust `burrow-engine` (FSL-1.1-ALv2), with a Mole-compatible command surface; source builds can use an external `mo` for nonprivileged operations | bundled Mole/PowerShell engine plus Windows fallbacks where needed |
  160. | UI | SwiftUI, translucent menu-bar app | WinUI 3 / .NET 8 |
  161. | Install | `brew install --cask caezium/tap/burrow` | build from source; unsigned preview artifacts via `windows/scripts/build-release.ps1` |
  162. | Source | [`macos/`](macos/) | [`windows/`](windows/) |
  163. Both apps live in this one repo, side by side, sharing this README, the landing
  164. site, and release documentation. The Windows preview currently includes a native
  165. shell, tool pages, local telemetry/history, loopback HTTP/MCP surfaces, tests,
  166. CI, and unsigned local packaging. See the [Windows architecture notes](windows/docs/windows-architecture.md)
  167. and [release notes](windows/docs/release.md).
  168. ### Windows preview
  169. The checked-in Windows app currently includes:
  170. - A native WinUI 3 / .NET 8 shell with Dashboard, History, Activity, Analyze,
  171. Clean, Purge, Installers, Apps, Optimize, and Settings routes.
  172. - Local Windows telemetry sampling for Dashboard, History, tray status, HTTP,
  173. and MCP.
  174. - Local JSONL-backed history/activity storage.
  175. - Optimize preview/confirm flows through Mole where available; the Windows Clean
  176. route is present but still a guarded pending stub until Mole Windows exposes a
  177. stable non-interactive cleanup contract for the GUI.
  178. - Native Windows fallback flows for Analyze, Purge, installer cleanup, and app
  179. inventory where the Windows Mole branch is still interactive or lacks JSON.
  180. - A tray icon, live tooltip, tray HUD, status menu, and quick navigation.
  181. - A loopback-only HTTP API (`/health`, `/info`, `/snapshot`, `/metrics`) and a
  182. stdio MCP bridge with the read-only Burrow tools.
  183. - Unit tests, Windows CI, local smoke-test helpers, and an unsigned release
  184. script that produces a setup executable, portable ZIP, hashes, and WinGet
  185. manifests.
  186. ## Roadmap
  187. <!-- ROADMAP:BEGIN generated by scripts/site-release.py; edit docs/roadmap.json instead -->
  188. The full board, with status and voting, lives at **[burrow.computer/roadmap](https://burrow.computer/roadmap)**. Vote by upvoting an issue, or [open a request](https://github.com/caezium/Burrow/issues/new/choose).
  189. **Building**
  190. - 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.
  191. **Planned**
  192. - 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))
  193. - 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.
  194. **Considering**
  195. - 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))
  196. - 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.
  197. _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](https://burrow.computer/releases.html)._
  198. <!-- ROADMAP:END -->
  199. <a href="https://star-history.dera.page/#caezium/Burrow&type=timeline&legend=top-left">
  200. <picture>
  201. <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=caezium/Burrow&type=timeline&theme=dark&legend=top-left" />
  202. <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=caezium/Burrow&type=timeline&legend=top-left" />
  203. <img height="350" alt="Star History Chart" src="https://star-history.dera.page/svg?repos=caezium/Burrow&type=timeline&legend=top-left" />
  204. </picture>
  205. </a>
  206. ## How Burrow compares to other tools
  207. A factual feature/scope comparison. The competitor columns are the **macOS**
  208. landscape; the Windows column reflects only the checked-in preview.
  209. **mole.fit** is from the original author of `mo` โ€” buy it ($19) if you want that
  210. and to fund `mo`.
  211. | | Burrow (macOS) | Burrow (Windows preview) | mole.fit | CleanMyMac | Pearcleaner | `mo` / ncdu |
  212. |---|:---:|:---:|:---:|:---:|:---:|:---:|
  213. | Price | Free | Free | $19 once | Subscription | Free | Free |
  214. | Open source | MIT | MIT | โ€“ | โ€“ | โœ… | โœ… (`mo`) |
  215. | Signed / notarized | โœ… Developer ID + Apple notarization *(0.11.0+; earlier archives lack both)* | No โ€” unsigned preview | โœ… | โœ… | โœ… | n/a |
  216. | Junk cleanup | โœ… | partial - Clean route pending | โœ… | โœ… | โ€“ | โœ… (`mo`) |
  217. | Dev-artifact purge | โœ… | โœ… | โœ… | partial | โ€“ | โœ… (`mo`) |
  218. | Leftover-installer sweep | โœ… | โœ… | โœ… | โœ… | โ€“ | โœ… (`mo`) |
  219. | Uninstall + leftovers | โœ… | โœ… | โœ… | โœ… | โœ… *(focus)* | โœ… (`mo`) |
  220. | Disk treemap | โœ… | โœ… | โœ… | โœ… | โ€“ | ncdu *(TUI)* |
  221. | Live system monitor | โœ… | โœ… | โœ… | partial | โ€“ | โ€“ |
  222. | Long-term metric history | โœ… | โœ… *(JSON)* | โ€“ | โ€“ | โ€“ | โ€“ |
  223. | MCP / agent API | โœ… | โœ… | โ€“ | โ€“ | โ€“ | โ€“ |
  224. | GUI | โœ… | โœ… | โœ… | โœ… | โœ… | โ€“ *(terminal)* |
  225. ## Settings
  226. Everything is local and takes effect immediately unless noted:
  227. | Setting | What it controls |
  228. |---|---|
  229. | **History retention** | How long metric history is kept (1 day โ†’ 1 year); older rows are pruned hourly. |
  230. | **Vacuum after large prunes** | Reclaim DB file space after a big prune (off by default). |
  231. | **Sampling rate** | How often Burrow runs `mo status --json` (5 s โ†’ 5 min). |
  232. | **App language** | Follow the system, or force English / ็ฎ€ไฝ“ไธญๆ–‡ / ็น้ซ”ไธญๆ–‡ / ะ ัƒััะบะธะน / ๆ—ฅๆœฌ่ชž / Deutsch / Franรงais / Espaรฑol / ํ•œ๊ตญ์–ด / Portuguรชs (Brasil) *(relaunch)*. See [docs/localization.md](docs/localization.md). |
  233. | **Menu-bar icon** | Show the menu-bar item, or run as a regular Dock app instead. |
  234. | **MCP / agent access** | Copyable stdio config + the tool list for Claude Code, Cursor, Codex, Cline, and any MCP client. |
  235. | **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. |
  236. | **Engine** | Shows the resolved engine's product name and version (`burrow-engine` in official builds, or an external `mo` in source builds). The bundled engine updates with signed Burrow releases; source builds using an external engine retain its updater. |
  237. ## Permissions & Full Disk Access
  238. Cleaning system and app caches means reading TCC-protected folders, so macOS
  239. will prompt โ€” once per folder โ€” unless the app has **Full Disk Access**. Burrow
  240. handles this honestly:
  241. - Before a flood-prone scan it shows a gate explaining the trade-off, with a
  242. one-click link to **System Settings โ†’ Full Disk Access** (grant once, no more
  243. prompts).
  244. - Don't want to grant it? **Scan with admin** runs the same scan as root โ€”
  245. root bypasses TCC, so it's a single password prompt instead of a flood.
  246. - Burrow only ever reads sizes; it never opens that data itself, and the real
  247. cleanup always goes through macOS's own admin dialog.
  248. ## Requirements
  249. ### macOS
  250. - **macOS 14+**
  251. - **No separate engine install.** Burrow bundles its own engine
  252. (`burrow-engine`, one FSL-1.1 binary) and runs it directly. _(Building from
  253. source? The engine is staged from the public `macos/vendor/burrow-engine`
  254. submodule, with no GitHub read token required. Without an initialized engine
  255. submodule, Burrow falls back to a system `mo` โ€”
  256. `brew install mole` โ€” with mo's own argv conventions.)_
  257. ### Windows preview
  258. - **Windows 10/11**
  259. - **.NET 8 SDK** for local build/test.
  260. - **Inno Setup** only when running the unsigned release packaging script.
  261. ## Install
  262. > Burrow 0.11.0 is the first Developer ID-signed and Apple-notarized release.
  263. > New official macOS tags must pass signing, notarization, ticket stapling, and
  264. > Gatekeeper assessment before they can publish. Version 0.10.5 used an ad-hoc
  265. > signature rather than Developer ID and was not notarized; older archives also
  266. > predate the current distribution guarantee.
  267. > The full security/trust write-up is in **[SECURITY.md](SECURITY.md)**.
  268. ### Homebrew (recommended)
  269. ```bash
  270. brew install --cask caezium/tap/burrow # the app + bundled engine
  271. ```
  272. The live cask installs the signed and notarized build, preserves quarantine so
  273. Gatekeeper can validate Apple's ticket, and contains no `postflight` bypass or
  274. unsigned-build warning. It is marked `auto_updates true` because Sparkle owns
  275. in-app updates.
  276. ### Direct download
  277. Download `Burrow-x.y.z.zip` from
  278. [Releases](https://github.com/caezium/Burrow/releases), unzip into
  279. `/Applications`, then:
  280. ```bash
  281. open /Applications/Burrow.app
  282. ```
  283. Keep the downloaded app's quarantine metadata intact: Gatekeeper uses it to
  284. verify the stapled notarization ticket. If you're intentionally installing an
  285. archived 0.10.5-or-earlier build, right-click the app and choose **Open**;
  286. those builds predate the notarization ticket.
  287. ### macOS build from source
  288. ```bash
  289. brew install xcodegen
  290. git clone https://github.com/caezium/Burrow.git && cd Burrow
  291. bash scripts/release.sh
  292. cp -R build_dist/Build/Products/Release/Burrow.app /Applications/
  293. open /Applications/Burrow.app
  294. ```
  295. The local script applies a coherent ad-hoc signature to the app and every
  296. bundled executable so Full Disk Access works during development. Only official
  297. tag builds use the private Developer ID identity and Apple notarization.
  298. Burrow lives in the menu bar (it's a menu-bar agent). Click the icon โ†’ **Open
  299. Burrow** โ€” or turn the menu-bar icon off in Settings to run it as a Dock app.
  300. If a macOS build freezes while Burrow creates that status item, the next launch
  301. stays in Dock-based compatibility mode on the same OS build and offers a
  302. one-click redacted diagnostic report. Automatic Sparkle startup waits until
  303. the initial AppKit launch turn has settled and the status item is stable; if
  304. the updater then fails its own stability window,
  305. later automatic checks pause for that app/OS build while manual checks remain
  306. available. A new macOS build retries a guarded status item; a new Burrow or
  307. macOS build retries an updater that previously failed its stability window.
  308. ### Windows preview build
  309. ```powershell
  310. git clone https://github.com/caezium/Burrow.git
  311. cd Burrow\windows
  312. dotnet restore .\BurrowWin.sln
  313. dotnet build .\BurrowWin.csproj -c Release -p:Platform=x64 -nr:false -v:minimal
  314. dotnet test .\Tests\BurrowWin.Tests\BurrowWin.Tests.csproj -c Release -v:minimal
  315. ```
  316. To create the checked-in unsigned preview artifacts locally:
  317. ```powershell
  318. .\scripts\build-release.ps1
  319. ```
  320. That script builds the app, runs tests, publishes the WinUI payload, creates an
  321. unsigned Inno Setup installer, creates a portable ZIP fallback, writes
  322. `SHA256SUMS.txt`, and writes WinGet manifests. See
  323. [`windows/docs/release.md`](windows/docs/release.md).
  324. ## Security & trust
  325. Burrow drives one bundled engine binary, `burrow-engine` (FSL-1.1-ALv2; its
  326. source is publicly available and the signed binary ships inside the app โ€” see
  327. [Attribution](#attribution--license)), plus an MIT `fclones` sidecar for
  328. duplicate finding. The honest privacy picture:
  329. - **No accounts, no ads.** Your metrics, history, and file contents stay on
  330. your machine. The macOS app sends opt-out anonymous usage plus crash, hang,
  331. startup, update, and sampled performance diagnostics. It sends no screen
  332. recordings, user files, user paths, metrics, or stored IP; turn it off in
  333. Settings. PostHog delivery and its bounded sanitized retry outbox run entirely
  334. off AppKit's main thread. Full list in **[TELEMETRY.md](TELEMETRY.md)**.
  335. - **No background root helper by default.** When Clean/Optimize โ€” or an
  336. uninstall whose app bundle needs an administrator โ€” need admin rights, macOS's
  337. own dialog asks you and Burrow runs that one engine command as root, then
  338. exits โ€” you approve every elevation. Every elevated run gets a fixed
  339. environment: `BURROW_HOME` points the engine back at *your* home (so an
  340. elevated uninstall removes your leftovers, not root's) and
  341. `BURROW_PRIVILEGED=1` makes it refuse user-writable sidecar overrides. You can
  342. opt in to a small signed helper so those prompts accept Touch ID; it grants
  343. no standing privilege (every root operation still authenticates, every time),
  344. performs only scan, clean, and optimize, and can be removed from Settings.
  345. Details in **[SECURITY.md](SECURITY.md)**.
  346. - **Local-only surfaces:** the MCP/HTTP surfaces bind to loopback only
  347. (`127.0.0.1`) and history is stored locally. On Windows, the HTTP REST toggle
  348. disables REST endpoints but keeps the local `/mcp` bridge route available for
  349. stdio MCP clients. The macOS Updates tab reads Homebrew's local index when it
  350. opens and runs `brew update` only when you click Refresh, the same fetch
  351. `brew` does for itself.
  352. - **Distribution signatures:** new official macOS tags fail unless Developer ID
  353. signing, notarization, and the signed Sparkle ZIP/feed checks pass; local
  354. macOS builds use an ad-hoc development identity. Windows preview artifacts
  355. remain unsigned, so direct-download users should expect SmartScreen or
  356. stricter Application Control policy prompts.
  357. - The full honest write-up, including macOS admin trade-offs and the "Scan with
  358. admin" option, is in **[SECURITY.md](SECURITY.md)**.
  359. ## Use it with your AI agent
  360. Burrow doubles as an [MCP](https://modelcontextprotocol.io) server over stdio,
  361. so **any MCP-capable agent** โ€” Claude Code, Cursor, Codex, Cline, Zed, and
  362. others โ€” can read your machine's recent state. Same server, same `{command, args}`
  363. shape everywhere.
  364. ### Let your agent set it up
  365. For macOS, paste this to your coding agent and it'll wire itself in:
  366. > Add the **Burrow** MCP server to my config so you can read my Mac's system
  367. > history. It's a local stdio MCP server โ€” run it as `burrow mcp` if the
  368. > Homebrew shim is on my PATH, otherwise
  369. > `/Applications/Burrow.app/Contents/MacOS/Burrow` with args `["--mcp"]`. Add it
  370. > under my MCP servers, reload, and confirm the tools `burrow_snapshot`,
  371. > `burrow_history`, `burrow_top_processes`, `burrow_process_usage`, and
  372. > `burrow_info` are available. Then tell me my Mac's current CPU and memory.
  373. ### Or configure it manually
  374. The config is the same JSON for every agent โ€” only the file differs:
  375. ```json
  376. {
  377. "mcpServers": {
  378. "burrow": {
  379. "command": "/Applications/Burrow.app/Contents/MacOS/Burrow",
  380. "args": ["--mcp"]
  381. }
  382. }
  383. }
  384. ```
  385. | Agent | Where it goes |
  386. |---|---|
  387. | **Claude Code** | `~/.claude/settings.json` โ€” or `claude mcp add burrow -- /Applications/Burrow.app/Contents/MacOS/Burrow --mcp` |
  388. | **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project) |
  389. | **Codex** | add a `[mcp_servers.burrow]` entry in `~/.codex/config.toml` |
  390. | **Cline / Zed / other** | the client's "MCP servers" / `mcpServers` config |
  391. If you installed via Homebrew, a `burrow` shim is on your PATH, so you can use
  392. `command: "burrow", args: ["mcp"]` instead of the bundle path. Reload the agent
  393. and ask in plain language.
  394. Windows preview builds include the stdio bridge in source under
  395. `windows/Tools/McpStdioBridge/` and in release artifacts as
  396. `Assets\Mcp\burrow-mcp-stdio.exe`.
  397. **Tools** โ€” 19 over MCP, read-only by default. The full reference, with **when an
  398. agent should reach for each**, is in **[docs/agent-tools.md](docs/agent-tools.md)**.
  399. The essentials:
  400. - **Status & history** โ€” `burrow_snapshot`, `burrow_history`, `burrow_top_processes`,
  401. `burrow_process_usage` (rank by `cpu_time`/`peak_cpu`/`avg_cpu`/`peak_mem`),
  402. `burrow_diff`, `burrow_disk_forecast`, `burrow_report`
  403. - **Diagnose** โ€” `burrow_doctor` (Full Disk Access, memory pressure, disk headroom,
  404. SIP/Gatekeeper/FileVault/firewall, battery, high-CPU, display/volume/network),
  405. `burrow_ports`, `burrow_info`
  406. - **Disk & apps** โ€” `burrow_analyze`, `burrow_list_apps`, `burrow_cleanup_history`,
  407. `burrow_deleted_files`
  408. - **Maintain (gated)** โ€” `burrow_clean`, `burrow_optimize`, `burrow_uninstall`,
  409. `burrow_purge`, `burrow_installer`
  410. Actuating tools preview (`--dry-run`) unless `confirm:true` **and** the matching
  411. Settings opt-in is enabled โ€” an agent can always look, but only acts with your say-so.
  412. Windows also keeps `burrow_uninstall(action=...)` as a compatibility tool for
  413. list, leftover-preview, and confirmed vendor-uninstaller launch workflows.
  414. There's also an optional localhost REST API (`127.0.0.1:9277` โ€” `/health`,
  415. `/info`, `/snapshot`, `/metrics`) for dashboards or curl. Loopback is a network
  416. boundary, not authentication: every request needs the random per-install bearer
  417. credential, an exact localhost `Host`, no browser `Origin`, and stays inside the
  418. request-size/rate limits. On macOS, read the credential locally with
  419. `defaults read dev.caezium.Burrow query_auth_token`; on Windows it lives in the
  420. current user's `%LOCALAPPDATA%\BurrowWin\settings.json`, and the stdio bridge
  421. adds it automatically. Disabling Windows REST does not close the listener
  422. because the authenticated stdio bridge still posts to `/mcp`.
  423. ```bash
  424. BURROW_HTTP_TOKEN="$(defaults read dev.caezium.Burrow query_auth_token)"
  425. curl -H "Authorization: Bearer $BURROW_HTTP_TOKEN" http://127.0.0.1:9277/health
  426. ```
  427. ## Develop & test
  428. ### macOS
  429. ```bash
  430. cd macos # the macOS app lives here (monorepo: macos/ + windows/)
  431. bash ../scripts/fetch-sentry.sh # vendor Sentry.xcframework (it's a local framework, not an SPM dep)
  432. bash ../scripts/fetch-sparkle.sh # vendor the checksum-pinned official Sparkle.framework
  433. xcodegen generate
  434. xcodebuild -project Burrow.xcodeproj -scheme Burrow \
  435. -configuration Debug -destination 'platform=macOS' test
  436. ```
  437. The suite covers the parts that matter through public interfaces: DB roundtrip
  438. + range + stride sampler + prune + corruption recovery, Store clamping/defaults,
  439. Maintenance prune, MCP tool routing + the semantic usage ranking, squarified
  440. treemap invariants, the Full Disk Access decision, and `mo` output parsing.
  441. ### Windows preview
  442. ```powershell
  443. cd windows
  444. dotnet restore .\BurrowWin.sln
  445. dotnet build .\BurrowWin.csproj -c Release -p:Platform=x64 -nr:false -v:minimal
  446. dotnet build .\Tests\BurrowWin.Tests\BurrowWin.Tests.csproj -c Release -nr:false -v:minimal
  447. dotnet test .\Tests\BurrowWin.Tests\BurrowWin.Tests.csproj -c Release --no-build -v:minimal
  448. ```
  449. For local GUI smoke checks:
  450. ```powershell
  451. .\run-local.ps1 -NoBuild -SmokeTest -Restart -RequireHealth -Route settings -TimeoutSeconds 60
  452. ```
  453. ## Architecture
  454. ### macOS
  455. ```
  456. Contents/Resources/burrow (burrow-engine, one binary; one {ok, data|error} envelope per command,
  457. NDJSON when streamed)
  458. burrow status --watch โ”€โ”€> SnapshotProducer (one long-lived stream, one line per tick;
  459. polls `status --json` only if the stream drops)
  460. โ”€โ”€> SQLite (WAL) โ”€โ”€โ”ฌโ”€> Status / History (charts)
  461. โ”œโ”€> HTTP QueryServer (:9277)
  462. โ””โ”€> Burrow --mcp (stdio) โ”€> Claude Code / Cursor / Codex
  463. burrow analyze --progress <p> โ”€โ”€> live file/dir/byte ticks, then the full payload
  464. โ”€โ”€> DiskScanner + squarified Treemap โ”€> Analyze
  465. (one `analyze` per child directory is the fallback)
  466. burrow clean|optimize|purge --stream โ”€> OperationFlow (NDJSON, live on both elevation routes:
  467. the helper relays stdout over XPC, osascript tails the
  468. root shell's log) โ”€> Clean / Optimize / Purge
  469. burrow clean --apply --permanent --plan <file> --stream
  470. โ”€โ”€> the reviewed clean: Confirm writes the ticked paths to a plan
  471. file and the engine removes only those โ€” no re-scan โ€” and
  472. reports each one back (removed / failed / protected + reason)
  473. burrow installer, uninstall [--apply] โ”€> Installers / Software (buffered envelope; uninstall is
  474. elevated only when the bundle needs an administrator)
  475. burrow dupes|orphans|photos|net --json โ”€> Duplicates / Leftovers / Photos / Network (+ fclones sidecar)
  476. ```
  477. The Swift side names the seams after what they are: `BurrowEngine` resolves
  478. and spawns the bundled binary and parses its envelope, `EngineRunner` is the
  479. one capture/stream/PTY facade, `EngineCLI` is discovery plus the elevated
  480. `do shell script` builder, and `MoActions` is the single gate that mints every
  481. destructive run for the GUI and the MCP server alike. A source build without
  482. an initialized engine submodule falls back to a system `mo`, whose argv is the
  483. inverse of the engine's (mo runs live by default; the engine previews by
  484. default and needs `--apply`) โ€” `BurrowEngine.engineArgv` is the one
  485. translation, applied only when the resolved binary is the bundled engine.
  486. One app binary, two modes: default is the menu-bar GUI; `Burrow --mcp` is the
  487. stdio MCP server (it forks before SwiftUI claims the process).
  488. The whole UI is one translucent window with a top-pill nav (`Brand`/`Tool`
  489. design system); Settings, History, and Activity are panes in that same window.
  490. ### Windows preview
  491. The Windows app is a WinUI 3 / .NET 8 project in [`windows/`](windows/) using
  492. MVVM view models, service-layer Windows/Mole integration, local JSONL history,
  493. loopback HTTP, and a stdio MCP bridge. Mole remains the preferred engine path
  494. where it is safe and non-interactive; Windows-native fallbacks cover current
  495. gaps in the Windows Mole branch. See
  496. [`windows/docs/windows-architecture.md`](windows/docs/windows-architecture.md).
  497. ## Attribution & license
  498. Burrow (this repository) is [MIT](LICENSE). The app bundle ships two
  499. separately licensed binaries โ€” the full notices are in [NOTICE](NOTICE):
  500. - **`burrow-engine`** (`Contents/Resources/burrow`) is ยฉ 2026 caezium, licensed
  501. under the **Functional Source License 1.1, ALv2 future license**
  502. (FSL-1.1-ALv2). Its source lives in the public
  503. [caezium/burrow-engine](https://github.com/caezium/burrow-engine) repository,
  504. vendored as a submodule and built into a single universal binary at release
  505. time; the binary ships with its license and dependency notices under
  506. `Contents/Resources/licenses/burrow-engine/`. Its command surface (`clean`, `optimize`,
  507. `uninstall`, `analyze`, `status`, โ€ฆ) is modelled on **Mole CLI** (`mo`), which
  508. is ยฉ [tw93](https://github.com/tw93/Mole), MIT โ€” Burrow no longer bundles a
  509. fork of Mole's code.
  510. - **`fclones`** (`Contents/Resources/fclones`) is ยฉ Piotr Koล‚aczkowski, MIT โ€”
  511. the duplicate-file engine behind the Duplicates pane.
  512. - Inspired by the **mole.fit** Mac app (same author as `mo`). Burrow is an
  513. independent reimplementation with its own brand โ€” no assets, icons, copy, or
  514. trade dress are taken from mole.fit.
  515. - The history-DB + MCP pattern shares lineage with the same author's
  516. [Stats fork](https://github.com/caezium/stats) (`caezium/stats@henry/history-mcp`).
  517. - Treemap layout: Bruls, Huijsen & van Wijk (2000), "Squarified Treemaps,"
  518. re-implemented from scratch in Swift.
  519. ## Contributing
  520. Burrow is community-driven. The repo currently contains the macOS app in
  521. [`macos/`](macos/) and the Windows preview in [`windows/`](windows/). We welcome
  522. bug fixes, tests, documentation improvements, and focused improvements to the
  523. checked-in platform implementations.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.