Configuration

Config file: ~/.config/hive/config.yaml

Example

workspaces:
  - ~/projects

agents:
  default: claude
  claude:
    command: claude
    flags: ["--model", "opus"]
  aider:
    command: /opt/bin/aider
    flags: ["--model", "sonnet"]

tmux:
  poll_interval: 1.5s
  preview_window_matcher: ["claude", "aider"]
  capture_recording:
    enabled: false

tui:
  theme: tokyo-night

rules:
  - pattern: ""
    max_recycled: 5
    windows:
      - name: "{{ agentWindow }}"
        command: '{{ agentCommand }} {{ agentFlags }}'
        focus: true
      - name: shell
    commands:
      - hive ctx init

  - pattern: ".*/data-team/.*"
    agent: aider

General Settings

Environment Overrides

Use environment overrides for machine-specific paths and defaults without maintaining separate config files. Empty environment variables are ignored. Run hive config to inspect the resolved values.

Agents

Agent profiles define the AI tools available for spawning in sessions. The default key selects which profile to use when creating a new session unless a matching rule sets agent, the session is created with --agent, or HIVE_DEFAULT_AGENT is set.

Set HIVE_DEFAULT_AGENT to override agents.default for a single machine or shell session. The value must match an existing profile key in agents.

export HIVE_DEFAULT_AGENT=codex

Agent resolution order is: CLI/session agent, then batch --agent, then the last matching rules[].agent, then HIVE_DEFAULT_AGENT, then agents.default. Sessions can run multiple agents by opening additional tmux windows — use tmux.preview_window_matcher to control which windows the TUI monitors.

Tmux

Pane capture recording

Pane capture recording is disabled by default. When explicitly enabled, Hive records only fresh captures it already reads from classified agent panes; it does not install agent hooks or trigger extra tmux captures.

Recordings are individual JSON files under $HIVE_DATA_DIR/recordings/tmux (normally ~/.local/share/hive/recordings/tmux). Each filename is the SHA-256 hash of the complete visible pane capture, so identical content is stored only once across panes and Hive processes. Metadata and the weak label come from the first observation of those exact bytes; later identical observations are skipped. Hive stores the whole visible pane; capture-pane does not include tmux scrollback history. Directories use mode 0700 and files use mode 0600. Each record contains the terminal content, an opaque session/pane key, detected tool, and the Stage 2 published terminal.Status as its weak label (hive_assess_v1). The separate rule ID and matched signals describe the Stage 1 assessment evidence that fed the tracker. Weak labels are useful for bootstrapping a training corpus but are not human-verified ground truth. A private .identity.key keeps opaque grouping keys stable across Hive processes; exclude that key from any corpus export.

Terminal

Hive detects agent status in two stages: a stateless per-poll assessment of the visible pane content, then a debounce tracker (terminal.status) that turns those assessments into stable, published statuses. Debouncing exists because a single poll can catch a tool mid-redraw; requiring a status to repeat before it's published avoids flickering between active/ready/missing on transient noise.

Entering active, approval, or question is always immediate (a busy indicator or a dialog is trusted the moment it's seen); only leaving those states is debounced, since a false positive there is a brief flash rather than a missed prompt.

terminal.status.confirm.missing.polls is not a status.Tracker debounce policy — it is consumed directly by the tmux transport as a list-panes failure tolerance: N polls tolerates N-1 consecutive tmux list-panes failures (serving the last-known cache) before a pane is published as missing. This keeps a single transient tmux hiccup from flashing every session missing.

Each polls/min_duration pair is combined, not alternative: the tracker requires max(polls, ceil(min_duration / tmux.poll_interval)) consecutive confirming polls. Setting min_duration shorter than tmux.poll_interval has no effect, since the poll-count floor already dominates — hive doctor warns about this combination.

terminal:
  status:
    confirm:
      idle:
        polls: 2
        min_duration: 2s
        stable_content: true
      missing:
        polls: 2
      approval:
        polls: 1

TUI

Messaging

Context

By default context documents are stored under hive's data directory (~/.local/share/hive/context/). Set context.base_dir or HIVE_CONTEXT_BASE_DIR to redirect them elsewhere — for example, into a git repository so plans and research are version-controlled alongside your code.

context:
  base_dir: ~/notes/hive-context   # store in a dedicated git repo

See Git-backed Context for a practical guide.

Todos

Views

View-specific settings (keybindings, layout, behavior) are configured per-view under the views section.

Sessions View

Tasks View

Messages View

Global

See Keybindings for the full per-view configuration format and defaults.

More Configuration

• Rules — Repository-specific spawn, recycle, setup commands, and file copying
• User Commands — Custom commands for the vim-style command palette
• Keybindings — Per-view key mappings and palette commands
• Todo Configuration — Todo actions, limiter, notifications, and enter behavior
• Plugins — External service integrations (tmux, Claude, GitHub, etc.)
• Themes — Built-in color palettes and custom theme creation

Data Storage

All data is stored at ~/.local/share/hive/:

~/.local/share/hive/
├── hive.db                    # SQLite database (sessions, messages)
├── bin/                       # Bundled scripts (auto-extracted)
│   ├── hive-tmux              # Tmux session launcher
│   └── agent-send             # Send text to agent in tmux
├── repos/                     # Cloned repositories
│   └── myproject-feature1-abc123/
└── context/                   # Per-repo context directories
    ├── {owner}/{repo}/        # Linked via .hive symlink
    └── shared/                # Shared context