Upgrading Cub¶

This guide covers major version upgrades and migration paths.

Upgrading to Cub 0.24+ (Harness Abstraction)¶

Cub 0.24 introduces a new async harness architecture with support for hooks, custom tools, and the Claude Agent SDK.

TL;DR¶

What Changed¶

New Harness Architecture:

• All harnesses now use an async interface (run_task, stream_task)
• Claude backend split into claude (SDK) and claude-cli (shell-out)
• New capabilities: hooks, custom_tools, sessions

New Capabilities (Claude SDK only):

Migration Steps¶

1. Update your installation:

cd ~/tools/cub
git pull origin main
uv sync

2. (Optional) Install SDK for hooks:

pip install claude-agent-sdk

3. Test the new backend:

# Uses new SDK backend by default
cub run --once

# Fall back to legacy if needed
cub run --once --harness claude-cli

Breaking Changes¶

Harness detection order changed:

claude > opencode > codex > gemini

claude (SDK) > claude-cli > codex > gemini > opencode

Python API changes:

from cub.core.harness import get_backend, detect_harness

backend = get_backend("claude")
result = backend.invoke(prompt, system)

from cub.core.harness import get_async_backend, detect_async_harness

backend = get_async_backend("claude")
result = await backend.run_task(task_input)

Troubleshooting¶

"Claude SDK not available"

Install the SDK or use legacy mode:

pip install claude-agent-sdk
# or
cub run --harness claude-cli

Hooks not working

Hooks only work with the SDK backend. Verify you're using claude, not claude-cli:

cub run --harness claude  # SDK with hooks

Upgrading to Cub 0.21+ (Bash to Python)¶

Cub 0.21 is a major architectural rewrite that migrates from Bash to Python while maintaining the existing feature set and workflow. This guide explains what changed, why, and how to upgrade.

TL;DR¶

The core workflow remains identical - the main change is the implementation language and improved performance.

What Changed¶

Why Python?¶

Cub v0.20 (Bash) had limitations:

Cub v0.21 (Python) provides:

• 10-50x faster JSON operations (in-process vs subprocess)
• Type safety: Pydantic v2 models with automatic validation
• Better testing: pytest framework with comprehensive test suite
• Modern CLI: Typer for clean subcommand structure
• Foundation for future: Live dashboards, parallel execution, Docker sandboxing

What Stays the Same¶

1. Task management: beads and prd.json backends work identically
2. Configuration: .cub.json and ~/.config/cub/ still work
3. Harnesses: Claude Code, Codex, Gemini, OpenCode all supported
4. Hooks: ~/.config/cub/hooks/ directory structure unchanged
5. Core loop: Task selection -> prompt generation -> harness execution -> commit
6. Workflow: cub run, cub status, cub init --global all work the same

What's New¶

• Python 3.10+ requirement: No more Bash 3.2
• Faster performance: Eliminates jq subprocess overhead
• Better error messages: Pydantic validation catches config errors early
• Improved CLI help: Subcommand structure with auto-generated help
• Type safety: Full type hints and mypy strict mode
• Better testing: 100+ pytest tests with >80% coverage
• Foundation for future: Architecture designed for dashboards and parallel execution

Breaking Changes¶

1. Bash Compatibility No Longer Available¶

./cub --once

cub run --once  # Python-based, must use `cub` command

git checkout bash-legacy  # Switch to Bash version
git checkout main         # Switch back to Python version

2. Python 3.10+ Required¶

The new version requires Python 3.10 or higher.

Check your version:

python3 --version

Install Python 3.10+:

brew install python@3.10

sudo apt-get install python3.10

pyenv install 3.10
pyenv global 3.10

3. Virtual Environment Required¶

Python version requires a virtual environment in the project.

Initialize:

cd ~/tools/cub
uv sync  # Creates .venv automatically

Add to shell config:

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

4. No More Bash Dependencies¶

5. Configuration Format¶

Config files (.cub.json, ~/.config/cub/config.json) remain compatible, but new fields are available:

{
  "harness": {
    "default": "claude"
  }
}

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

Step-by-Step Upgrade Guide¶

1. Backup (Optional)¶

cd ~/tools/cub
git status  # Ensure clean state
git branch backup/v0.20  # Create backup branch

2. Update Cub¶

cd ~/tools/cub
git pull origin main

3. Install Python Dependencies¶

uv sync

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

4. Update Shell Configuration¶

Add to ~/.bashrc, ~/.zshrc, or equivalent:

# Cub Python CLI
export PATH="$HOME/tools/cub/.venv/bin:$PATH"

Then reload:

source ~/.bashrc  # or ~/.zshrc

5. Verify Installation¶

# Should show Python version and subcommands
cub --version
cub --help

# Should work as before
cd your-project
cub run --once

6. Run Quality Checks (Optional)¶

# Type checking
mypy src/cub

# Tests
pytest tests/ -v

# Linting
ruff check src/

7. Update Documentation Files¶

Review your project's CLAUDE.md or AGENT.md:

• Update build/test commands to use Python tools
• Update prerequisite documentation
• Update example commands

Common Migration Issues¶

"cub: command not found"¶

# Check if .venv exists
ls ~/tools/cub/.venv

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

# Reload shell
source ~/.bashrc

"Python 3.10+ required"¶

# Check version
python3 --version

# Install newer version
brew install python@3.10  # macOS
# or
sudo apt-get install python3.10  # Ubuntu

Configuration validation error¶

# Remove or fix .cub.json
rm .cub.json

# Run init to generate valid config
cub init --global

Harness not found¶

# Check if Claude Code is installed
which claude

# Install Claude Code
# Follow https://github.com/anthropics/claude-code

# Or specify different harness
cub run --harness opencode

Rollback¶

If you need to revert to Bash version:

cd ~/tools/cub
git checkout bash-legacy
git checkout v0.20  # Or specific tag

# Remove Python virtual environment if desired
rm -rf .venv

Performance Improvements¶

Python v0.21 is significantly faster than Bash v0.20:

Real-world impact:

• 100 tasks: v0.20 (50s setup) -> v0.21 (5s setup)
• Loop of 10: v0.20 (5s overhead) -> v0.21 (50ms overhead)

FAQ¶

Will my beads tasks be migrated automatically?¶

No migration needed! Your .beads/issues.jsonl works exactly as before. Both Bash and Python versions read the same task format.

Can I still use prd.json?¶

Yes, JSON backend is still supported. Beads is now recommended for new projects.

Do I need to update my configuration?¶

No, old configs still work. New fields have sensible defaults. Only update if you want new features like budget management or hooks.

Will my hooks still work?¶

Yes! Hook location (~/.config/cub/hooks/) and format are unchanged. Just verify they're executable:

chmod +x ~/.config/cub/hooks/post-task.d/*.sh

What if I have custom hooks or scripts?¶

Update any references from cub command to use new Python version. Main changes:

Is the core loop the same?¶

Yes, completely identical. Task selection, prompt generation, harness execution, and commit workflow are unchanged.

Is there a performance regression?¶

No, quite the opposite! v0.21 is 10-50x faster due to eliminating jq subprocess overhead.

Getting Help¶

If you run into issues:

1. Check error message: Python errors are usually more descriptive than Bash
2. Run in debug mode: cub run --debug shows what's happening
3. Check logs: ~/.local/share/cub/logs/ has detailed execution logs
4. Report issue: GitHub Issues

What's Next¶

After v0.21, planned releases include:

All of these build on v0.21's Python foundation!