View as markdown

Configuration

Hive reads two YAML files. Most of what you’ll tune lives in the per-project file that hive init creates.

1. The two config files
2. Launch & permission mode
3. Agent profiles
4. Token-cost knobs: budgets & timeouts
5. Reviewers
6. Patrol
7. Daemon enrollment
8. Babysitter (experimental)
9. Telegram bot

The two config files

File	Scope	Holds
~/.config/hive/config.yml	Global	Registered projects and bot settings (allowlist, voice transcription).
<project>/.hive-state/config.yml	Per-project	Default branch, worktree root, budgets, timeouts, stage agents, reviewers, daemon enrollment, patrol, and babysitter settings.

Per-project values are deep-merged onto Hive’s built-in defaults, then validated. A bad value raises a clear config error rather than failing later — so it’s safe to edit and re-run. Arrays (like review.reviewers) are replaced wholesale, never merged element-by-element.

Launch & permission mode

claude:
  mode: tmux                 # tmux (default) or headless
  permission_mode: bypassPermissions

• mode — tmux runs Claude-backed stages in attachable tmux sessions using your logged-in session; headless uses non-interactive spawns (good for service-only hosts).
• permission_mode — one of acceptEdits, auto, bypassPermissions, default, dontAsk, plan. bypassPermissions skips file-operation prompts (recommended for local runs); auto keeps Claude Code auto-mode rules.

Agent profiles

Each stage runs on a named agent profile. The three built-in profiles are claude (default), codex, and pi. You can point a stage at a different agent, and override a profile’s binary, env var, or minimum version:

plan:    { agent: claude }
execute: { agent: codex }    # the rendered template recommends codex for execute

agents:
  codex:
    bin: codex
    env_override: HIVE_CODEX_BIN
    min_version: "0.125.0"

Token-cost knobs: budgets & timeouts

These are generous sanity caps for runaway agents, not cost targets. Lower them if you want a tighter ceiling per stage.

budget_usd:
  brainstorm: 50
  plan: 100
  execute_implementation: 500
  review_fix: 500
  # …

timeout_sec:
  brainstorm: 1800
  plan: 3600
  execute_implementation: 14400
  # …

Reviewers

The 6-review stage runs a configurable set of reviewers. A fresh hive init ships a populated, recommended list; you can add, remove, or reorder entries. Each reviewer needs a unique name and output_basename (the basename keeps concurrent review files from colliding).

review:
  reviewers:
    - { name: claude-ce-code-review, agent: claude, output_basename: claude-ce-code-review }
    - { name: codex-ce-code-review,  agent: codex,  output_basename: codex-ce-code-review }
  triage: { enabled: true, agent: claude, bias: courageous }
  fix:    { agent: claude }
  max_passes: 2
  max_wall_clock_sec: 5400

Patrol

Patrol is autonomous repository patrol: it maps feature slices, reviews them, validates fixes, and opens PRs for the ones that pass. Patrol is opt-in — a project with no patrol config, or a patrol section without an explicit mode:, stays disabled.

Set a single mode dial instead of hand-tuning knobs:

patrol:
  mode: medium    # ultrapatrol | high | medium | low | off

Mode	Cadence
ultrapatrol	Timer, every 30 min
high	Timer, every 2 h
medium	Timer, every 4 h
low	On new commits (baseline SHA-check cadence)
off	Disabled

hive init offers medium as the suggested starting mode, but that’s only a prompt default — it’s never applied unless you accept it (or set mode: yourself). Patrol scans are per-project: each project runs at most one scan at a time, and different projects patrol in parallel rather than competing for a single global slot. See the patrol command page.

Daemon enrollment

The daemon is global autostart infrastructure; per-project config only decides whether this project is picked up for dispatch, and bounds concurrency:

daemon:
  enabled: true
  max_concurrent_runs: 1          # task-dispatch slots for this project
  max_concurrent_patrol_scans: 1  # separate per-project cap for patrol scans

Patrol scans run on a separate in-flight budget from task dispatch, so a long scan never consumes a task slot.

Babysitter (experimental)

The PR babysitter keeps open PRs green and mergeable. It’s opt-in and off by default:

babysitter:
  enabled: false
  interval: 10m
  max_concurrent_prs: 2
  labels_ignore: [wip, do-not-merge, draft]
  budget_minutes: 30
  budget_usd: 50

See babysit and Operating.

Telegram bot

Global bot settings live in ~/.config/hive/config.yml:

bot:
  enabled: true
  chat_id_allowlist:
    - 123456789

Voice-note capture reads an OpenAI-compatible transcription key from the environment (e.g. HIVE_WHISPER_API_KEY); the key is never written into config. Full setup is on the bot page.