Frequently Asked Questions¶

Cub requires:

• Python 3.10+ - Required for the Python CLI
• At least one AI harness - Claude Code, Codex, Gemini, or OpenCode
• Git - For version control integration
• jq - For JSON processing (in bash components)

Optional:

• Docker - For sandbox mode
• Beads CLI - For beads task backend

Claude Code is recommended for most users because it supports:

• All Cub features (streaming, token tracking, system prompts)
• Best integration with cub prep
• Active development and support

See the Harnesses comparison for a full capability matrix.

Yes! The Python version of Cub can be installed with:

# Using pipx (recommended)
pipx install cub-cli

# Or using uv
uv tool install cub-cli

# Or using pip
pip install cub-cli

However, most AI harnesses (Claude Code, Codex, Gemini) are installed via npm. You only need npm for harness installation, not for running Cub itself.

Use the one-liner installer:

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

Or install via pipx for isolated installation:

pipx install cub-cli

Then set up global configuration:

cub init --global

cub prep - Preparation phase (work ahead of execution)

• Converts vague ideas into structured tasks
• Runs triage, architect, plan, and bootstrap stages
• Requires human review and refinement
• Creates agent-ready task specifications

cub run - Execution phase (autonomous operation)

• Executes prepared tasks with an AI harness
• Runs autonomously without human intervention
• Tracks progress, handles errors, manages budget
• Updates task status as work completes

The workflow is: Prep (human-in-loop) -> Run (autonomous)

Use the --once flag:

cub run --once

This runs a single iteration and exits. Useful for testing or when you want to review after each task.

Yes! Use nohup or screen/tmux:

# With nohup
nohup cub run &> cub.log &

# With screen
screen -S cub
cub run
# Ctrl+A, D to detach

# With tmux
tmux new -s cub
cub run
# Ctrl+B, D to detach

Monitor progress with:

cub status
# Or
cub monitor

Press Ctrl+C once for a graceful shutdown. Cub will:

1. Finish the current operation
2. Save state
3. Exit cleanly

Press Ctrl+C twice for immediate termination (may lose current task progress).

Cub is designed to be resumable:

1. Task status remains unchanged (still "in_progress")
2. Git state is preserved (uncommitted changes may exist)
3. Running cub run again will resume from where it left off

Check status after a crash:

git status
cub status

Cub uses a layered configuration system:

Priority: CLI flags > environment variables > project config > global config > defaults

In your global config (~/.config/cub/config.json):

{
  "harness": {
    "priority": ["claude", "opencode", "codex", "gemini"]
  }
}

Or set per-project in .cub.json.

Via CLI:

cub run --budget 5000000

Or in config:

{
  "budget": {
    "limit": 5000000,
    "warn_at": 80
  }
}

In .cub.json:

{
  "clean_state": {
    "require_commit": false,
    "require_tests": false
  }
}

Beads is the recommended backend for new projects. It provides a full CLI for task management and syncs with GitHub Issues.

Run the migration:

# Preview changes
cub --migrate-to-beads-dry-run

# Execute migration
cub --migrate-to-beads

This converts your prd.json tasks to .beads/issues.jsonl.

With beads backend:

bd create "Task title" --desc "Detailed description"

With JSON backend, edit prd.json manually:

{
  "tasks": [
    {
      "id": "new-task-1",
      "title": "New task",
      "description": "What to do",
      "status": "open"
    }
  ]
}

With beads:

bd close <task-id> -r "Completed successfully"

Or use the Cub CLI:

cub close-task <task-id> --reason "Done"

Claude Code has the most complete feature support:

• Streaming output - See progress in real-time
• Token reporting - Accurate budget tracking
• System prompts - Separate instructions from tasks
• JSON output - Reliable response parsing
• Model selection - Choose models per task

Other harnesses work but may lack some features.

Yes! Configure a priority order:

{
  "harness": {
    "priority": ["claude", "opencode", "codex"]
  }
}

Cub uses the first available harness. You can also select per-task with labels:

bd label <task-id> harness:codex

Add a model label to the task:

bd label <task-id> model:haiku

When the task runs, Cub passes the model to the harness (if supported).

By default, no. Cub runs tasks but doesn't automatically commit. The AI harness may commit as part of its work (Claude Code often does).

You can configure hooks to commit after tasks:

{
  "hooks": {
    "post_task": ["git add . && git commit -m 'Task complete'"]
  }
}

Cub can bind branches to epics:

# Create and bind branch to epic
cub branch my-epic

# List bindings
cub branches

# Create PR when done
cub pr my-epic

See Git Integration for details.

Git worktrees allow multiple checkouts of the same repo. Cub uses them for:

• Parallel execution - Run multiple tasks simultaneously
• Isolation - Each task works in its own directory

# Run 3 tasks in parallel with worktrees
cub run --parallel 3

See Worktrees for details.

Sandbox mode runs tasks in Docker containers for complete isolation:

cub run --sandbox

Benefits:

• Untrusted code can't affect your system
• Reproducible environment
• Network isolation (optional)

See Sandbox Mode for details.

Use the --parallel flag:

cub run --parallel 3

Each task runs in its own git worktree. Tasks must be independent (no shared dependencies).

See Parallel Execution for details.

Hooks run custom scripts at key points:

• pre_run - Before session starts
• post_run - After session ends
• pre_task - Before each task
• post_task - After each task

Configure in .cub.json:

{
  "hooks": {
    "post_task": ["./scripts/notify.sh"]
  }
}

See Hooks System for details.

1. Enable debug mode:

   cub run --debug --once
   

2. Run diagnostics:

   cub doctor
   

3. Check logs:

   tail -100 .cub/logs/session-*.jsonl | jq .
   

Common causes:

• Large context - Big files or many tasks slow down the AI
• Network latency - Check your connection
• Rate limiting - Use --once and space out runs
• Heavy tests - Consider require_tests: false for drafts

Enable debug mode to see timing:

cub run --debug --once

1. Gather diagnostic info:

   cub doctor > doctor.txt
   cub run --debug --once 2>&1 | tee debug.log
   

2. Open an issue with:

3. Error message
4. Doctor output
5. Debug logs
6. Steps to reproduce
7. Your environment (OS, Python version, harness)

Check the Changelog and Upgrading Guide for breaking changes and migration instructions.

Yes! Initialize Cub in any project:

cd my-existing-project
cub init

Then create tasks and run:

cub prep  # Or manually create tasks
cub run