Installation¶

Get Cub installed and configured on your system.

Prerequisites¶

Before installing Cub, ensure you have:

Python 3.10+¶

Cub requires Python 3.10 or later.

# Check your Python version
python3 --version

If you need to install or upgrade Python:

macOSUbuntu/DebianWindows

brew install python@3.12

sudo apt update
sudo apt install python3.12 python3.12-venv

Download from python.org or use:

winget install Python.Python.3.12

At Least One AI Harness¶

Cub orchestrates AI coding CLIs but doesn't include them. Install at least one:

Harness	Install Command	Notes
Claude Code	`npm install -g @anthropic-ai/claude-code`	Recommended. Required for `cub prep`
OpenAI Codex	`npm install -g @openai/codex`	Good for OpenAI ecosystem
Google Gemini	`npm install -g @google/gemini-cli`	Alternative perspective
OpenCode	See project docs	Open-source option

Claude Code is Required for Prep

The cub prep pipeline (triage, architect, plan, bootstrap) requires Claude Code. For cub run, any harness works.

One-Liner Install (Recommended)¶

The fastest way to get started:

curl -LsSf https://docs.cub.tools/install.sh | bash

This script will:

Install pipx if not already present
Install Cub via pipx
Add Cub to your PATH
Run cub init --global to set up config directories

After installation, restart your shell (or open a new terminal):

# Verify installation
cub --version

Upgrading

Already have Cub installed? Upgrade with:

pipx upgrade cub

Or simply re-run the installer script.

Alternative Installation Methods¶

Using pipx (Manual)Using uvFrom Source (Development)

pipx installs Python applications in isolated environments:

# Install pipx if needed
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install Cub
pipx install git+https://github.com/lavallee/cub.git

# Set up global config
cub init --global

uv is a fast Python package manager:

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Cub as a tool
uv tool install git+https://github.com/lavallee/cub.git

# Set up global config
cub init --global

For contributing or running the latest code:

# Clone the repository
git clone https://github.com/lavallee/cub ~/tools/cub
cd ~/tools/cub

# Install dependencies (using uv)
uv sync

# Or using pip
python3.10 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Add to PATH
export PATH="$HOME/tools/cub/.venv/bin:$PATH"

# Set up global config
cub init --global

Add the PATH export to your ~/.bashrc or ~/.zshrc for persistence.

Verifying Installation¶

After installation, verify everything is working:

# Check Cub version
cub --version

# Check available commands
cub --help

# Run diagnostics
cub doctor

The cub doctor command checks:

Python version compatibility
Available harnesses (claude, codex, gemini, opencode)
Configuration file locations
Common issues and fixes

Common Issue: Command Not Found

If cub is not found after installation:

Restart your shell or run source ~/.bashrc (or ~/.zshrc)
Check that ~/.local/bin is in your PATH
For pipx: run pipx ensurepath and restart

Global Setup¶

After installing Cub, run the global initialization:

cub init --global

This creates:

Path	Purpose
`~/.config/cub/config.json`	Global configuration
`~/.config/cub/hooks/`	Global hook directories
`~/.local/share/cub/logs/`	Log storage
`~/.cache/cub/`	Cache directory

Default Global Configuration¶

The global config file (~/.config/cub/config.json) contains default settings:

{
  "harness": {
    "default": "auto",
    "priority": ["claude", "opencode", "codex", "gemini"]
  },
  "budget": {
    "default": 1000000,
    "warn_at": 0.8
  },
  "loop": {
    "max_iterations": 100
  },
  "hooks": {
    "enabled": true
  }
}

You can edit this file to change defaults for all projects.

Optional: Task Backend¶

Cub supports two task management backends:

JSON Backend (Default)¶

No additional setup needed. Tasks are stored in prd.json in your project.

Beads Backend (Recommended)¶

For advanced task management with the beads CLI:

macOSOther Platforms

brew install steveyegge/beads/bd

See the beads installation docs

Cub auto-detects the beads backend when .beads/ directory exists in your project.

Next Steps¶

Now that Cub is installed:

Quick Start - Run your first autonomous session
Core Concepts - Understand prep, run, and task backends
Configuration - Customize Cub for your workflow

Uninstalling¶

If you need to remove Cub:

pipxuvFrom Source

pipx uninstall cub

uv tool uninstall cub

rm -rf ~/tools/cub
# Remove the PATH entry from your shell config

To also remove configuration and data:

rm -rf ~/.config/cub
rm -rf ~/.local/share/cub
rm -rf ~/.cache/cub