Getting Started
Install hive, configure your environment, and launch your first AI agent session in under five minutes.
Installation
Prerequisites
- Git — available in your PATH
- tmux — required for session management and status monitoring
tmux is required
Hive uses tmux for session management, agent monitoring, and preview panes. Install it before proceeding — hive will not function without it.
Homebrew
brew install colonyops/tap/hive
GitHub Release
Pre-built binaries for macOS and Linux are available on the GitHub Releases page. Download the appropriate archive for your platform, extract it, and place the binary on your PATH.
Go Install
go install github.com/colonyops/hive@latest
Mise
Install via mise using the GitHub backend:
mise use -g github:colonyops/hive
Verify
hive --version
hive doctor # Check configuration and environment
Quick Start
1. Set up a shell alias
Hive works best when running inside tmux. When you create a session, hive spawns a tmux session for the agent — if hive itself is also a tmux session, you can seamlessly switch between hive and your agents without leaving tmux. Hive becomes your home base: open an agent, do some work, jump back to hive, spin up another.
Recommended alias
Add to your .bashrc / .zshrc:
alias hv='tmux new-session -As hive hive'
This runs hive inside a dedicated tmux session called hive. If the session already exists, it reattaches.
2. Add a tmux keybinding to jump back
Add to your ~/.tmux.conf:
bind l switch-client -t hive
Now <prefix> l returns you to hive from any agent session.
3. Configure repo directories (optional)
To create sessions from the TUI with n, tell hive where your repos live:
# ~/.config/hive/config.yaml
repo_dirs:
- ~/projects
- ~/work
Info
Without repo_dirs, you can still create sessions from the CLI by running hive new from within a git repository:
cd ~/projects/my-app
hive new Fix Auth Bug
4. Launch
hv
Hive auto-detects tmux, bundles its own session management scripts, and registers default keybindings — no other config needed. Press n to create sessions, enter to open them, and : for the command palette.