Homebrew Manager

Native macOS GUI for Homebrew
Install, upgrade, uninstall, cleanup, autoremove, taps, services, doctor — with a live command console.

---

Why this exists

Homebrew is powerful on the CLI. Day-to-day maintenance — outdated packages, leftover deps, services, taps, doctor — is easier when you can see it, confirm destructive commands, and watch live output. Homebrew Manager is a native SwiftUI app that wraps the official brew CLI (no Cellar scraping, no reimplementation of Homebrew).

Not affiliated with Homebrew or the Homebrew project. Homebrew® is a trademark of its respective owners. This app shells out to your local brew executable.

Features

Area	Capabilities
Installed	List formulae & casks; filter All / Formulae / Casks / Pinned; pin/unpin; uninstall; dependency tree; “why installed” (brew uses --installed)
Outdated	Multi-select upgrade or upgrade all (brew outdated --json=v2 / brew upgrade)
Search & install	Debounced search; confirm sheet shows the exact brew install … command
Leaves & cleanup	Leaves, autoremove dry-run + run, cleanup dry-run + run (--prune=all optional)
Taps	List / add / untap with confirmation
Services	Start / stop / restart / run
Doctor	brew doctor, version, config; warnings surfaced in-UI
Console	Live streamed stdout/stderr; copy / clear / cancel
Settings	Custom brew path override; auto-detect Apple Silicon & Intel prefixes
Safety	Destructive actions require confirmation; exact command preview

Performance notes

• Installed list uses fast brew list --versions (not multi-hundred-KB info --json dumps into the UI).
• Bulk/read commands are quiet in the console; mutating commands stream live.
• Concurrent quiet reads; console updates are throttled.

Requirements

• macOS 14+
• Xcode 16+ (Swift 6.1 toolchain) to build from source
• Homebrew installed (/opt/homebrew/bin/brew or /usr/local/bin/brew, or a custom path)

Install with Homebrew

brew tap will702/gui-manager
brew install --cask homebrew-manager

Already using will702/tap?

brew tap will702/tap
brew install --cask homebrew-manager

Unsigned builds may need quarantine bypass on first open:

brew install --cask --no-quarantine homebrew-manager

Then launch Homebrew Manager from Applications (requires Homebrew itself for managing packages).

Quick start (from source)

1. Install Homebrew if needed.
2. Build a Release app (see below) or open the workspace in Xcode and Run.
3. Launch Homebrew Manager — if brew is missing, the app shows a banner with a link to brew.sh (it will not install Homebrew for you).

git clone https://github.com/will702/homebrew-gui-manager.git
cd homebrew-gui-manager
./Scripts/package-release.sh
open dist/HomebrewManager.app

Build from source

Xcode (recommended)

open HomebrewManager.xcworkspace

Select the HomebrewManager scheme → My Mac → Run (⌘R).

Command line

# Debug build & run (requires XcodeBuildMCP optional tooling, or use xcodebuild)
xcodebuild \
  -workspace HomebrewManager.xcworkspace \
  -scheme HomebrewManager \
  -configuration Debug \
  -destination 'platform=macOS' \
  build

# Release .app + zip + DMG
./Scripts/package-release.sh
# → dist/HomebrewManager.app
# → dist/HomebrewManager.zip
# → dist/HomebrewManager.dmg

GitHub Actions — auto DMG + cask bump

Workflow .github/workflows/release-dmg.yml runs on macos-15:

Trigger	Result
Push to main	Release DMG + ZIP uploaded as Actions artifacts (30 days)
Tag v* (e.g. git tag v1.0.1 && git push --tags)	GitHub Release + updates Casks/homebrew-manager.rb + syncs to will702/homebrew-tap (optional TAP_TOKEN secret)
Actions → Bundle DMG → Run workflow	Manual build; optional draft release

Install token: brew tap will702/gui-manager (this repo) or brew tap will702/tap.

CI packages are unsigned. First launch may need Right-click → Open.

Local DMG-only (after .app exists): ./Scripts/create-dmg.sh

Tests

xcodebuild \
  -workspace HomebrewManager.xcworkspace \
  -scheme HomebrewManager \
  -destination 'platform=macOS' \
  test

Signing / notarization (optional)

Release builds enable Hardened Runtime. App Sandbox is disabled (Homebrew needs unrestricted filesystem + process execution) — not Mac App Store–ready without a helper/XPC redesign.

For Developer ID distribution, see Config/ExportOptions-DeveloperID.plist and:

xcrun notarytool submit dist/HomebrewManager.zip --keychain-profile <PROFILE> --wait
xcrun stapler staple dist/HomebrewManager.app

Architecture

HomebrewManager.xcworkspace
├── HomebrewManager/              # @main app shell + Assets.xcassets
├── HomebrewManagerPackage/       # SPM feature module (SwiftUI + brew layer)
│   └── Sources/HomebrewManagerFeature/
│       ├── Brew/                 # Path resolver, CommandRunner, BrewService
│       ├── Models/               # Codable brew JSON + UI models
│       ├── Stores/               # AppModel, CommandLogStore, settings
│       ├── Views/                # Sidebar screens
│       └── Components/           # Console, confirm sheets, banners
├── Config/                       # xcconfig, entitlements, export options
├── Resources/Brand/              # Logo / icns masters
├── docs/                         # Flowcharts + generated visuals
└── Scripts/package-release.sh

flowchart LR
  UI[SwiftUI Views] --> Model[AppModel]
  Model --> Brew[BrewService]
  Brew --> Runner[CommandRunner]
  Runner --> CLI["brew CLI"]
  Brew --> Models[JSON Models]
  Runner --> Log[CommandLogStore]
  Log --> Console[Live Console]

Loading

More diagrams (safety flow, sequence charts, state machine): docs/VISUALS.md.

BrewService is the only facade for brew operations. Prefer official JSON flags:

• brew info --json=v2, brew outdated --json=v2
• brew list --formula/--cask --versions, brew leaves, brew deps --tree, brew uses --installed
• brew services, brew tap / untap, brew pin / unpin
• brew doctor, cleanup, autoremove, upgrade, install, uninstall

Branding

Asset	Path
App icon set	HomebrewManager/Assets.xcassets/AppIcon.appiconset/
Accent (#C47A3A)	HomebrewManager/Assets.xcassets/AccentColor.colorset/
Master PNG	Resources/Brand/AppIcon-1024.png
ICNS	Resources/Brand/AppIcon.icns

For AI agents & tools

Structured project context for LLMs and coding agents:

• llms.txt — machine-readable project summary
• AGENTS.md — contributor / agent guidelines
• CITATION.cff — how to cite this software
• docs/VISUALS.md — flowcharts + generated architecture images

Acknowledgments & citations

This project stands on open tooling and documentation:

Project	Role	License / link
Homebrew	Package manager CLI this app drives	BSD-2-Clause
Swift / SwiftUI	App language & UI	Apache 2.0 / Apple frameworks
Xcode	Build system	Apple
XcodeBuildMCP	Scaffold / AI macOS build workflows (dev tooling)	See upstream
Shields.io	README badges	CC0

Homebrew Manager does not redistribute Homebrew; users must install it separately from brew.sh.

Contributing

See CONTRIBUTING.md. Bug reports and PRs welcome.

Security

See SECURITY.md. Do not run untrusted formulae blindly — this GUI executes the same brew your terminal would.

License

MIT © 2026 Gregorius Willson

Cite this project

@software{HomebrewManager2026,
  author = {Willson, Gregorius},
  title = {Homebrew Manager},
  year = {2026},
  url = {https://github.com/will702/homebrew-gui-manager},
  license = {MIT}
}

Or use CITATION.cff (GitHub “Cite this repository”).