Skip to content

User Guide

The User Guide provides comprehensive documentation for using Cub effectively. Whether you are setting up your first autonomous coding session or optimizing complex workflows, these guides will help you get the most out of Cub.

Guide Sections

  • Configuration

    Learn how to configure Cub for your environment and projects. Covers config files, environment variables, and precedence rules.

    Configuration

  • Task Management

    Understand how Cub manages tasks using different backends. Learn about task states, dependencies, and filtering.

    Task Management

  • The Run Loop

    Dive into Cub's core execution loop. Learn how tasks are selected, executed, and completed.

    Run Loop

  • Prep Pipeline

    Transform visions into executable tasks. Use triage, architect, plan, and bootstrap to prepare your work.

    Prep Pipeline

  • AI Harnesses

    Configure and use different AI assistants: Claude Code, OpenAI Codex, Google Gemini, and OpenCode.

    AI Harnesses

  • Git Integration

    Manage branches, create pull requests, and use worktrees for parallel development.

    Git Integration

  • Hooks System

    Extend Cub with custom scripts that run at key points in the task lifecycle.

    Hooks System

  • Budget & Guardrails

    Control costs with token budgets and prevent runaway loops with iteration limits.

    Budget & Guardrails

  • Advanced Topics

    Explore sandbox mode, parallel execution, captures, and audit logging.

    Advanced

Topic Description
Configuration Reference Complete reference for all config options
Environment Variables All supported environment variables
Beads Backend Primary task management backend
Claude Code Harness Using Claude Code with Cub
Hook Examples Ready-to-use hook scripts

Common Workflows

Starting a New Project

  1. Initialize Cub globally: cub init --global
  2. Create a new project: cub new my-project (or cub init in an existing project)
  3. Prepare tasks: cub prep to run the vision-to-tasks pipeline
  4. Execute: cub run to start autonomous execution

Daily Development

# Check what's ready to run
cub status --ready

# Run a single task for testing
cub run --once

# Run with live output
cub run --stream

# Monitor progress in another terminal
cub monitor

CI/CD Integration

# Deterministic execution for CI
export CUB_BUDGET=2000000
export CUB_MAX_ITERATIONS=50
cub run --harness claude --require-clean

Getting Help