Configuration¶

Cub uses a layered configuration system that allows you to set defaults globally, override them per-project, and further customize via environment variables and CLI flags.

Configuration Precedence¶

Configuration is loaded and merged in the following order, with later sources overriding earlier ones:

flowchart LR
    A[Defaults] --> B[Global Config]
    B --> C[Project Config]
    C --> D[Environment Variables]
    D --> E[CLI Flags]

    style E fill:#4CAF50,color:white
    style D fill:#8BC34A
    style C fill:#CDDC39
    style B fill:#FFEB3B
    style A fill:#FFC107

Quick Setup¶

Global Configuration¶

Set up your user-wide defaults:

cub init --global

This creates ~/.config/cub/config.json with sensible defaults:

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

Project Configuration¶

Create .cub.json in your project root to override global settings:

cd my-project
cub init

Or create manually:

{
  "budget": {
    "default": 500000
  },
  "loop": {
    "max_iterations": 50
  },
  "clean_state": {
    "require_tests": true
  }
}

Directory Structure¶

Cub follows the XDG Base Directory Specification for configuration and data:

~/.config/cub/
+-- config.json              # Global configuration
+-- hooks/                   # Global hook directories
    +-- pre-loop.d/
    +-- pre-task.d/
    +-- post-task.d/
    +-- on-error.d/
    +-- post-loop.d/

~/.local/share/cub/
+-- logs/                    # Session logs
    +-- {project}/
        +-- {session}.jsonl  # YYYYMMDD-HHMMSS format

~/.cache/cub/              # Cache directory

.cub.json                  # Project-level config (in project root)
.cub/hooks/                # Project-specific hooks (in project root)

Configuration Sections¶

Cub configuration is organized into these sections:

Next Steps¶