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"]

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

Hive watches configured workspace directories and rescans them when repositories are added, removed, or renamed. Run :WorkspaceRefresh from the command palette to rescan manually.

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

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