hive

hive

The command center for your AI colony

Manage multiple AI agent sessions in isolated git environments with real-time status monitoring.

Documentation | Getting Started | Configuration | Contributing

Installation

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)
• Inter-agent Messaging — Pub/sub communication between sessions
• Context Sharing — Shared storage per repository via .hive symlinks
• 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

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
• Messaging — Inter-agent pub/sub communication
• 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
• task (https://taskfile.dev)
• golangci-lint

Local Dev Setup

git clone https://github.com/colonyops/hive.git
cd hive
task run

Use task run during development. It runs hive with project-local defaults from Taskfile.yml:

• HIVE_CONFIG=./config.dev.yaml
• HIVE_DATA_DIR=./.data
• HIVE_LOG_FILE=./dev.log
• HIVE_LOG_LEVEL=debug

This isolates contributor testing from your personal/global hive sessions.

Dev Config vs Global Config

Run with dev config:

task run
task run -- new
task run -- doctor

Run against your global config (compatibility checks):

go run *.go --config ~/.config/hive/config.yaml --data-dir ~/.local/share/hive

Common Contributor Commands

task test
task lint
task check
task build
task validate

Before opening a PR, run task check. If you changed config behavior, also run task validate and task run -- doctor.

Acknowledgments

This project was heavily inspired by agent-deck by Ashesh Goplani. Several concepts and code patterns were adapted from their work. Thanks to the agent-deck team for open-sourcing their project under the MIT license.

Disclaimer: The majority of this codebase was vibe-coded with AI assistance. Use at your own risk.