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