Configuration Reference¶

This page provides complete documentation for all Cub configuration options.

Harness Configuration¶

Controls which AI harness (Claude Code, Codex, etc.) is used to execute tasks.

harness.default¶

The default harness to use for task execution.

When set to auto, Cub attempts harnesses in priority order and uses the first one that is available.

harness.priority¶

Order to try harnesses when using auto mode.

The first available harness in the list is used. This allows you to prefer certain harnesses while having fallbacks.

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

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

cub run --harness claude

Budget Configuration¶

Manage token budget to control AI API costs.

budget.default¶

Token budget limit per session.

The execution loop exits when the budget is exceeded. This prevents runaway costs.

budget.warn_at¶

Warning threshold as a percentage of budget.

When token usage reaches this percentage of the budget, a warning is logged. This gives you advance notice before hitting the limit.

{
  "budget": {
    "default": 100000,
    "warn_at": 0.9
  }
}

{
  "budget": {
    "default": 5000000,
    "warn_at": 0.7
  }
}

export CUB_BUDGET=200000
cub run

# View budget warnings
jq 'select(.event_type=="budget_warning")' ~/.local/share/cub/logs/myproject/*.jsonl

# Calculate total tokens used
jq -s '[.[].data.tokens_used // 0] | add' ~/.local/share/cub/logs/myproject/*.jsonl

Loop Configuration¶

Control the main execution loop behavior.

loop.max_iterations¶

Maximum number of iterations before the loop exits.

This prevents infinite loops and provides a hard stop for long-running sessions. Each task attempt counts as one iteration.

cub run --max-iterations 5 --once

{
  "loop": {
    "max_iterations": 200
  }
}

Clean State Configuration¶

Enforce code quality and consistency checks between task executions.

clean_state.require_commit¶

Enforce git commits after harness completes a task.

When enabled, Cub verifies that all changes are committed after each task. This ensures a clean state between tasks.

clean_state.require_tests¶

Enforce test passage before allowing commits.

When enabled, tasks must pass all tests before the clean state check succeeds. This ensures code quality at each step.

clean_state.auto_commit¶

Automatically commit remaining changes when the harness completes successfully.

When the harness exits with code 0 but forgets to commit, this setting allows Cub to commit the remaining changes automatically. This prevents task failures due to uncommitted changes when the work is actually complete.

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

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

cub run --no-require-clean

Task Configuration¶

Control task lifecycle behavior.

task.auto_close¶

Automatically close tasks when the harness completes successfully.

When the harness exits with code 0 but the agent forgets to close the task, this setting allows Cub to close it automatically. This prevents tasks from getting stuck in "in_progress" state.

{
  "task": {
    "auto_close": true
  }
}

{
  "task": {
    "auto_close": false
  }
}

Hooks Configuration¶

Control the hook system for task lifecycle events.

hooks.enabled¶

Enable or disable all hooks.

hooks.fail_fast¶

Stop the loop if a hook fails.

When enabled, a hook failure (non-zero exit code) stops the entire run. When disabled, hook failures are logged but execution continues.

hooks.async_notifications¶

Run post-task and on-error hooks asynchronously (non-blocking).

When enabled, notification hooks (post-task, on-error, on-budget-warning, on-all-tasks-complete) fire in the background so they don't slow down the main loop. All async hooks are collected before the session ends. Set to false to run all hooks synchronously.

{
  "hooks": {
    "enabled": false
  }
}

{
  "hooks": {
    "enabled": true,
    "fail_fast": true
  }
}

{
  "hooks": {
    "enabled": true,
    "async_notifications": false
  }
}

See the Hooks System Guide for details on writing custom hooks.

Guardrails Configuration¶

Prevent runaway loops and redact sensitive information from output.

guardrails.max_task_iterations¶

Maximum attempts for a single task.

When exceeded, the task is marked as failed and skipped. This prevents infinite retry loops on problematic tasks.

guardrails.max_run_iterations¶

Maximum total iterations in a run.

When exceeded, the run stops immediately. This prevents runaway loop behavior across all tasks.

guardrails.iteration_warning_threshold¶

Warning threshold as a percentage of iteration limit.

Logs a warning when approaching max_task_iterations or max_run_iterations.

guardrails.secret_patterns¶

Regular expression patterns to detect and redact sensitive information.

Patterns are matched case-insensitively against log output. Matched values are redacted to prevent accidental exposure.

{
  "guardrails": {
    "max_task_iterations": 2,
    "max_run_iterations": 10,
    "iteration_warning_threshold": 0.5
  }
}

{
  "guardrails": {
    "secret_patterns": [
      "api[_-]?key",
      "password",
      "token",
      "secret",
      "authorization",
      "credentials",
      "webhook_url",
      "private_key",
      "aws_secret"
    ]
  }
}

export CUB_MAX_TASK_ITERATIONS=10
export CUB_MAX_RUN_ITERATIONS=200
cub run

Complete Configuration Schema¶

Here is the complete JSON schema for .cub.json:

{
  "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,
    "auto_commit": true
  },
  "task": {
    "auto_close": true
  },
  "hooks": {
    "enabled": true,
    "fail_fast": false
  },
  "guardrails": {
    "max_task_iterations": 3,
    "max_run_iterations": 50,
    "iteration_warning_threshold": 0.8,
    "secret_patterns": [
      "api[_-]?key",
      "password",
      "token",
      "secret",
      "authorization",
      "credentials"
    ]
  }
}

Debugging Configuration¶

View Merged Configuration¶

Check what configuration Cub is actually using:

# Show debug output including config
cub run --debug --once 2>&1 | grep -i config

# View global config
cat ~/.config/cub/config.json | jq .

# View project config
cat .cub.json | jq .

Validate Configuration¶

Ensure your JSON is valid before using:

# Validate global config
jq empty ~/.config/cub/config.json && echo "Valid"

# Validate project config
jq empty .cub.json && echo "Valid"

Common Issues¶