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 Hive's current state-tracker result as a weak label. 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.

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