hive-hooks

---

Installation

brew install tmux
brew install colonyops/tap/hive

Or install directly with Go:

go install github.com/colonyops/hive@latest

Pre-built binaries are also available on the GitHub Releases page.

Overview

Hive manages isolated git sessions for running AI agents in parallel. Instead of manually managing git worktrees or directories, hive handles cloning, recycling, and spawning terminal sessions with your preferred AI tool (Claude, Aider, Codex).

Each hive session is a complete git clone in a dedicated directory with its own terminal environment. Sessions are tracked through a lifecycle (active → recycled → deleted) and can be reused, reducing clone time and disk usage.

Key Features:

• Session Management — Create, recycle, and prune isolated git clones
• Terminal Integration — Real-time status monitoring of AI agents in tmux (works out of the box)
• Task Tracking — Built-in epics and tasks for multi-agent coordination (hive hc)
• Inter-agent Messaging — Pub/sub communication between sessions
• Context Sharing — Shared storage per repository via .hive symlinks
• Operator Todos (Experimental) — Track human follow-up items from agents via CLI/TUI todo flows
• Custom Keybindings — Bind keys to user-defined or system commands
• Command Palette — Vim-style command palette for custom commands (: key)

Quick Start

Prerequisites: Git and tmux installed.

# Add alias to .bashrc/.zshrc
alias hv='tmux new-session -As hive hive'

# Add to ~/.tmux.conf to jump back to hive
# bind l switch-client -t hive

# Launch
hv

Press n to create sessions, enter to open them, and : for the command palette.

See the Getting Started guide for full setup instructions.

Status Indicators

Indicator	Color	Meaning
[●]	Green (animated)	Agent actively working
[!]	Yellow	Agent needs approval/permission
[>]	Cyan	Agent ready for input
[?]	Dim	Terminal session not found
[○]	Gray	Session recycled

Documentation

Full documentation is available at colonyops.github.io/hive.

• Getting Started — Terminology, quick start, first session
• Configuration — Config file, rules, templates, options
• User Commands — User commands and command palette
• Keybindings — Key mappings and palette commands
• Task Tracking — Built-in epics and tasks for multi-agent coordination
• Messaging — Inter-agent pub/sub communication
• Todos (Experimental) — Operator todo lifecycle and CLI usage
• Plugins — Claude, tmux, and other plugins
• Themes — Built-in themes and custom palettes
• Context & Review — Shared context directories and review tool
• FAQ — Common questions

Dependencies

• Git (available in PATH or configured via git_path)
• tmux (required — provides session management and status monitoring)

Contributing

Prerequisites

• Go 1.25+
• git
• tmux
• mise (https://mise.jdx.dev)
• golangci-lint