# 🍺 brewbar

> A localhost web GUI for managing macOS package managers — Homebrew and friends, with a view.

[![npm](https://img.shields.io/npm/v/brewbar.svg)](https://www.npmjs.com/package/brewbar)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![runtime: bun](https://img.shields.io/badge/runtime-Bun-black.svg)](https://bun.sh)

**English** · [中文](README.zh.md)

brewbar turns the command-line package managers you already use into a fast, single-page web app that runs entirely on your own machine. It manages **Homebrew** as a first-class citizen and treats **npm, pip, cargo, go, gem, bun and pnpm** as equal providers — install, upgrade, uninstall, inspect, and audit them all from one place.

![brewbar dashboard](https://raw.githubusercontent.com/gps949/brewbar/main/docs/assets/dashboard.png)

## Features

- **8 package managers, one UI** — Homebrew (formulae + casks) plus npm, pip, cargo, go, gem, bun, pnpm. Switch providers and manage each consistently.
- **Real terminal** — operations run in an in-browser PTY (xterm.js). It answers `sudo`/`[Y/n]` prompts; you type right in the **Activity** dock.
- **Command preview** — every action shows the exact command before it runs. What you preview is what executes.
- **Transactional operation queue** — multi-select, queue, retry, and cancel jobs; live status and logs.
- **Package detail for every provider** — description, homepage/repository, installed & latest version, disk size, and the configured source/registry.
- **On-demand scans (with progress)** — like a disk cleaner: click to scan **disk usage** (sort packages by size) or **check for updates** (works even for managers with no native outdated check, such as bun/cargo/go).
- **CVE scanning** — free, keyless vulnerability scan via [OSV.dev](https://osv.dev) for npm/PyPI/crates.io/RubyGems/Go ecosystems.
- **Dependency graph** — interactive 1-hop "what depends on this / what does this need" view for Homebrew formulae.
- **Brewfile three-way diff** — see what's installed vs. declared, and sync.
- **Optional AI assistant** — bring your own key. Works with Anthropic and any OpenAI-compatible endpoint (DeepSeek, Zhipu GLM, Moonshot Kimi, xAI Grok, Google Gemini, …). Streams answers. Your key is stored locally and never sent to the browser.
- **Polished UX** — light/dark themes, `⌘K` command palette, full English/简体中文 localization, and a responsive layout that works from phone to desktop.

## Requirements

- **macOS** (brewbar shells out to macOS tools and package-manager paths).
- **[Bun](https://bun.sh) ≥ 1.0** — the only runtime needed. No Node, Electron, or Xcode.
- Homebrew is optional; if it's missing, an onboarding screen guides installation. The other managers are detected automatically when present.

## Install & run

### Run instantly (no install)

```sh
bunx brewbar
```

### Install globally

```sh
bun install -g brewbar
# or: npm install -g brewbar   (the `brewbar` command still runs under Bun)
brewbar
```

Either way, brewbar starts a local server, prints a URL, and opens your browser:

```
🍺 brewbar running at http://127.0.0.1:4321/?token=<random>
```

Stop it with `Ctrl-C`.

**Options:** `brewbar --port=5000` (choose a port), `brewbar --no-open` (don't auto-open the browser).

### Run from source

```sh
git clone https://github.com/gps949/brewbar.git
cd brewbar
bun install
bun run prod        # build the web app, then start the server
```

## How it works

brewbar is a single Bun process: a [Hono](https://hono.dev) API + WebSocket server that also serves a prebuilt React/Vite/Tailwind front-end. It binds to `127.0.0.1` only and mints a fresh random access token on every launch, so nothing on your network can reach it. Package operations run through a real PTY (via macOS `script`), which is how interactive prompts and `sudo` work without any privileged daemon.

## Security

- Listens on **localhost only**; every launch generates a new access token embedded in the opened URL.
- No telemetry, no account, no paywall.
- The AI assistant's API key (if you configure one) is stored at `~/.config/brewbar/ai.json` with `0600` permissions and is **never** returned to the browser.

## Usage manual

See **[docs/USAGE.md](docs/USAGE.md)** (English) · **[docs/USAGE.zh.md](docs/USAGE.zh.md)** (中文) for a page-by-page walkthrough of every feature.

## Development

```sh
bun install
bun run dev:server   # API + WebSocket with --watch (no auto-open)
bun run dev:web      # Vite dev server for the front-end
bun test ./server    # server tests
bun run build        # build the web app into web/dist
```

The repo is a Bun workspace monorepo: `shared/` (types), `server/` (Hono API, providers, jobs), `web/` (React app).

## License

[MIT](LICENSE) © gps949