hive

README

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 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.

hive init   # interactive setup wizard — alias, config, tmux binding
hv          # launch

hive init detects installed AI agents, scaffolds ~/.config/hive/config.yaml, appends an hv alias to your shell rc, and adds a tmux keybinding to jump back to hive.

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

Local Dev Setup

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

mise run dev runs hive with project-local defaults from mise.toml:

• 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

Mode	Config Path	Data Directory	Use Case
Dev	./config.dev.yaml	./.data	Contributing and testing changes safely
Global	~/.config/hive/config.yaml	~/.local/share/hive	Day-to-day hive usage

Run with dev config:

mise run dev
mise run dev -- new
mise run dev -- doctor

Run against your global config:

mise run start
mise run start -- doctor

Common Contributor Commands

mise run test
mise run lint
mise run check
mise run build
mise run validate

Before opening a PR, run mise run check. If you changed config behavior, also run mise run validate and mise run dev -- 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.