config

name	config
description	This skill should be used when the user asks to "configure hive", "setup hive for my workflow", "customize session spawn", "add tmux integration", "create custom keybindings", "add user commands", or needs guidance on hive configuration, rules, spawn commands, terminal integration, or keybindings.
compatibility	claude, opencode

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