kombrucha (bru)

⚡ A blazing fast Homebrew-compatible package manager

Status: Beta

• Core Commands: Fully functional package management (install, uninstall, upgrade)
• Bottle-Based: Works with 95% of Homebrew formulae (those with bottles)
• Well-Tested: 32 automated tests covering critical workflows
• Source Builds: Not yet supported (Phase 3 feature)

See internal/status-report.md for detailed status.

Features

• Fast: 2-20x faster than Homebrew (8x average, verified benchmarks)
• Efficient: Minimal CPU usage with compiled binary
• Compatible: Works with Homebrew formulae and infrastructure (bottle-based)
• Beautiful: Colorized output with NO_COLOR support and pipe-aware formatting
• Parallel: Concurrent operations for maximum performance
• Robust: Graceful error handling and partial failure recovery

What Works ✅

Package Management (fully functional):

• install, uninstall, upgrade, reinstall - Bottle-based formulae
• install --cask, uninstall --cask - macOS applications (DMG, ZIP, PKG)
• fetch, list, outdated, autoremove, cleanup
• pin, unpin - Version locking
• Full dependency resolution and graph traversal

Discovery & Information (fully functional):

• search, info, desc, deps, uses
• list, leaves, missing, formulae, casks, unbottled
• which-formula, options, cat, log

Repository Management (fully functional):

• tap, untap, tap-info, tap-new, update
• extract, migrate, readall, tap-readme

System & Utilities (fully functional):

• config, doctor, env, home, shellenv
• cache, analytics, commands, completions
• services - launchd integration for background services
• bundle - Brewfile install and dump

Development Tools (not implemented - use brew instead):

• create, audit, livecheck, linkage, test, style

What Doesn't Work ❌

Phase 3: Source Builds (not implemented):

• Formulae without bottles (~1-5% of packages)
• Building from source (--build-from-source flag)
• Head installations (--HEAD flag)
• Custom build options
• Formula testing (bru test)

Workaround: Use brew for these edge cases or wait for Phase 3 (Ruby interop)

Installation

Via Install Script (Recommended)

curl -fsSL https://raw.githubusercontent.com/nijaru/kombrucha/main/install.sh | sh

Via Cargo

cargo install kombrucha

This installs the bru binary to ~/.cargo/bin/

From Source

git clone https://github.com/nijaru/kombrucha.git
cd kombrucha
cargo build --release
# Binary is at: ./target/release/bru

Shell Completions (Optional)

# Bash
bru completions bash > ~/.local/share/bash-completion/completions/bru

# Zsh
bru completions zsh > ~/.zfunc/_bru

# Fish
bru completions fish > ~/.config/fish/completions/bru.fish

Quick Start

# Search for packages
bru search rust

# Search only formulae or casks
bru search --formula python
bru search --cask docker

# Get info about a package
bru info wget

# Quick description lookup
bru desc wget jq curl

# Show dependencies
bru deps --tree wget

# Show only installed dependencies
bru deps --installed wget

# See what depends on a package
bru uses openssl

# Get JSON output (for scripting)
bru info --json wget

# List installed packages
bru list

# Check for outdated packages
bru outdated

# Install a package
bru install hello

# Uninstall a package
bru uninstall hello

# Remove unused dependencies
bru autoremove

# Clean up old versions
bru cleanup

# List taps (third-party repositories)
bru tap

# Add a tap
bru tap user/repo

# Remove a tap
bru untap user/repo

# Update all taps
bru update

# Download bottles without installing
bru fetch wget jq tree

Performance

Verified Benchmarks (October 21, 2025) - M3 Max, macOS 15.1, 500 Mbps:

Average speedup: 8x across common operations

See internal/performance-analysis.md for detailed analysis and methodology.

Why?

Homebrew is amazing but slow. On modern networks (100+ Mbps), Ruby overhead dominates execution time. bru eliminates this overhead while targeting full compatibility with Homebrew's formulae and infrastructure.

See performance analysis for the technical breakdown.

Testing

# Unit tests
cargo test

# Integration tests (install/uninstall workflow)
./scripts/test-integration.sh

# Smoke tests (quick validation)
./scripts/test-smoke.sh

# Run benchmarks
./benchmarks/phase2-install.sh  # Simple package
./benchmarks/phase2-complex.sh  # Package with dependencies

See scripts/README.md for detailed testing documentation.

Documentation

For AI Agents - Start with AGENTS.md for project overview and structure

Current Status:

• ai/STATUS.md - START HERE - Current project state
• ai/TODO.md - Active tasks and priorities
• ai/DECISIONS.md - Architectural decisions log

Architecture:

• docs/architecture/SPEC.md - Technical architecture
• docs/architecture/feature-parity-audit.md - Command coverage
• docs/architecture/implementation-roadmap.md - Development phases
• docs/architecture/testing-strategy.md - Testing approach

Research:

• ai/RESEARCH.md - Research index
• ai/research/performance-analysis.md - Performance breakdown
• ai/research/homebrew-compatibility.md - Compatibility analysis
• benchmarks/ - Performance testing and results

License

MIT OR Apache-2.0