Config - Configure Hive for Your Workflow

Set up and customize hive to match development workflows with rules, spawn commands, keybindings, and terminal integration.

Configuration File

Location: ~/.config/hive/config.yaml

Current version: 0.2.5

cat ~/.config/hive/config.yaml   # View config
$EDITOR ~/.config/hive/config.yaml  # Edit config
hive doc migrate                  # Check version and migrate

Minimal Config

version: 0.2.5

rules:
  - pattern: ""  # Matches all repos
    windows:
      - name: claude
        command: "claude"
        focus: true
      - name: shell

Rules System

Rules match repository URLs with regex patterns and define behavior.

Rule Structure

rules:
  - pattern: ".*github\\.com/org-name/.*"  # Regex pattern
    max_recycled: 3                         # Max recycled sessions
    windows:                                # Declarative tmux windows (recommended)
      - name: claude
        command: "claude"
        focus: true
      - name: shell
    recycle: []                             # Commands when recycling
    commands: []                            # Setup commands after clone
    copy: []                                # Files to copy from original

Rule precedence: Last matching rule with spawn/windows config wins.

Window Config Fields

Field	Type	Required	Description
name	string	yes	Window name (supports templates)
command	string	no	Command to run (empty = default shell)
dir	string	no	Working directory override
focus	bool	no	Select this window after creation

windows is mutually exclusive with spawn/batch_spawn. If neither is set, the default layout (agent window + shell) is used.

Pattern Examples

- pattern: ""                                    # Match all repos
- pattern: ".*github\\.com/my-org/.*"           # Match specific org
- pattern: ".*github\\.com/my-org/my-repo"      # Match specific repo
- pattern: ".*(my-org|other-org)/.*"             # Match multiple orgs

Template Variables

Commands support Go templates with {{ .Variable }} syntax.

Context	Variables
windows, spawn, batch_spawn	.Path, .Name, .Slug, .ContextDir, .Owner, .Repo
batch_spawn, windows (batch)	.Prompt
recycle	.DefaultBranch
usercommands.*.sh	.Path, .Name, .Remote, .ID, .Tool, .TmuxWindow, .Args, .Form.*

Use {{ .Variable | shq }} for safe shell quoting.

Terminal Integration

Tmux

tmux:
  poll_interval: 1.5s
  preview_window_matcher: ["claude", "aider", "codex"]

Status indicators:

• [●] Green - Agent actively working
• [!] Yellow - Agent needs approval
• [>] Cyan - Agent ready for input
• [?] Dim - Terminal not found
• [○] Gray - Session recycled

User Commands

Define custom commands accessible via : command palette or keybindings.

usercommands:
  name:
    sh: "command template"     # Shell command
    help: "Description"        # Help text
    confirm: "Are you sure?"   # Optional confirmation
    silent: true               # Skip loading popup
    exit: "true"               # Exit TUI after command

Examples

usercommands:
  tidy:
    sh: "send-claude {{ .Name }} /tidy"
    help: "Run /tidy in Claude session"
    confirm: "Commit and push changes?"
    silent: true

  vscode:
    sh: "code {{ .Path }}"
    help: "Open session in VS Code"
    silent: true
    exit: "true"

  msg:
    sh: 'hive msg pub -t agent.{{ .ID }}.inbox "{{ range .Args }}{{ . }} {{ end }}"'
    help: "Send message to session inbox"

Keybindings

Map keys to user commands in the TUI.

keybindings:
  r:
    cmd: Recycle
    confirm: "Recycle this session?"
  d:
    cmd: Delete
  o:
    cmd: vscode
  enter:
    cmd: attach

Reserved keys: ?, :, v, j/k/↑/↓, /, n

Additional Resources

For detailed configuration examples, spawn command patterns for different terminals, and migration guides, see:

• references/spawn-patterns.md - Terminal-specific spawn command examples (tmux, WezTerm, Kitty, iTerm2, Alacritty)
• references/workflow-examples.md - Complete workflow configurations for common setups
• references/troubleshooting.md - Common configuration issues and solutions

Related Skills

• /hive:inbox - Check inter-agent messages
• /hive:publish - Send messages between sessions
• /hive:session-info - Get current session details