Skip to content
bossanova
GitHub Sign in Try Now

Installation

Bossanova runs natively on macOS and Linux.

Install methods

brew install bossanova-dev/tap/bossanova

Works on macOS and Linux. Installs boss, bossd, and the open-core plugins. Sets up the daemon automatically.

Quick start

  1. Step 1: Install bossanova

    Pick a method from the tabs above. Homebrew is the recommended path on macOS and Linux.

  2. Step 2: Verify your install

    Run this command after installing — you should see all three checks pass.

    boss daemon status

    Expected output:

    ✓ bossd is running (PID 12847)
✓ Service: ~/Library/LaunchAgents/com.bossanova.bossd.plist
✓ Socket: reachable

  3. Step 3: Launch the boss client

    Opens the terminal UI showing your repos and any active sessions.

    boss

  4. Step 4: Add your first repo

    Type r to add your first repository. Bossanova sets up the worktree base directory and registers the repo with the daemon.

  5. Step 5: Spawn your first agent

    Press n in the TUI to create a new session. Pick the repo, type a prompt, and Claude starts working in an isolated worktree.

System requirements

OS
macOS 13+ or Linux
Prerequisites

Troubleshooting

brew: command not found
Homebrew isn't installed. Follow the one-liner at brew.sh, then re-run the install command.
boss: command not found after install
The install put binaries in ~/.local/bin, which isn't on your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell rc file (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish) and start a new shell.
Daemon not starting
Re-register the launchd / systemd service by running boss daemon install. On macOS, check the launchd logs at ~/Library/Logs/com.bossanova.bossd.log; on Linux, run journalctl --user -u bossd.
Can't see Claude Code in repo list
Bossanova invokes the claude CLI directly. Run which claude to confirm it's on your PATH; if not, install it from the Claude Code setup docs.