Hive

A terminal TUI for managing multiple AI coding agent sessions across projects — Claude, Codex, Gemini, GitHub Copilot, Aider, OpenCode, and more. Native support for Claude agent teams (orchestrator + workers).

┌─────────────────────────────────────────────────────────────────┐
│ ▼ project-alpha             │ ╔══════ preview ════════════════╗ │
│   ▼ [team] feature-x        │ ║                               ║ │
│     ★ orchestrator [claude] │ ║  > implement the auth module  ║ │
│     ○ worker-1 [claude]     │ ║  Working on JWT validation…   ║ │
│     ○ worker-2 [codex]      │ ║                               ║ │
│   ○ solo-session [gemini]   │ ╚═══════════════════════════════╝ │
│ ▶ project-beta              │                                   │
├─────────────────────────────┴───────────────────────────────────┤
│ project-alpha / feature-x / orchestrator [claude] [waiting]      │
│ q:quit  r:rename  a:attach  t:new  T:new-team  ?:help           │
└─────────────────────────────────────────────────────────────────┘

Features

Multiple projects — organize work into named projects with color coding
Multiple sessions per project — each session runs in a persistent terminal pane
Session persistence — sessions keep running after the TUI closes; reconnect with hive start
Agent teams — native Claude multi-agent teams with orchestrator + worker layout
Easy switching — vim-style navigation (j/k/J/K), numbered project jumps (1–9)
Mouse support — click sidebar items, preview pane, and grid cells; scroll wheel in all panes
Live preview — 500ms refresh with ANSI color passthrough; always shows the most-recent output
Session title editing — press r to rename inline, or let the agent set it via escape sequence
Extensible hooks — shell scripts fired on 11 lifecycle events with rich HIVE_* env vars
Responsive — adapts to any terminal width, sidebar collapses on narrow terminals
Multi-agent support — Claude, Codex, Gemini, Copilot, Aider, OpenCode, custom commands

Requirements

Go 1.25+ (to build from source)
tmux — the default and recommended backend for managing terminal sessions

Native backend (alpha): Hive includes an experimental built-in PTY backend that requires no external dependencies. It is not recommended for general use. Enable it with hive start --native or by setting "multiplexer": "native" in config.json.

Installation

Build from source (Linux / macOS)

git clone https://github.com/lucascaro/hive
cd hive
go build -o hive .
sudo mv hive /usr/local/bin/   # or any directory on your PATH

Or use the helper script:

./build.sh

Build from source (Windows)

Note: The native PTY backend is not available on Windows. Hive uses the tmux backend on Windows — install tmux via MSYS2, WSL, or Chocolatey (choco install msys2).

git clone https://github.com/lucascaro/hive
cd hive
.\build.ps1          # builds hive.exe and installs it (run as Administrator to install system-wide)

Or build manually:

go build -o hive.exe .

After building, add hive.exe to a directory on your PATH.

Config directory on Windows: %APPDATA%\hive\ (e.g. C:\Users\You\AppData\Roaming\hive\)

Using Hive on Windows:

Install tmux (via WSL, MSYS2, or Chocolatey).
Run hive start from a terminal that has tmux on its PATH (e.g. Git Bash, MSYS2 terminal, or WSL).

No manual config change is needed — tmux is already the default backend.

Verify

hive version

Getting Started

Platform-specific guides:

Getting Started on macOS

Getting Started on Windows

1. Launch Hive

hive start

On first launch, Hive creates the config directory (~/.config/hive/ on Linux/macOS, %APPDATA%\hive\ on Windows) with a default config.json and starts the background multiplexer daemon.

2. Create a project

Press n, type a project name, press Enter.

3. Create a session

With a project selected, press t. A picker appears — choose your agent:

Select Agent
────────────
▶ [claude]   Claude (Anthropic)
  [codex]    Codex (OpenAI)
  [gemini]   Gemini (Google)
  [copilot]  GitHub Copilot CLI
  [aider]    Aider
  [opencode] OpenCode
  [custom]   Custom command

enter: select  esc: cancel

4. Attach to a session

Select a session with j/k and press a or Enter. The TUI suspends and you interact with the agent directly. Press Ctrl+Q to detach and return to Hive.

5. Create an agent team

Press T to open the team wizard. You'll be guided through:

Team name + goal
Orchestrator agent (Claude recommended)
Number of workers + agent type per worker
Shared working directory
Confirmation — all sessions are created and agents launched

Teams appear in the sidebar with the orchestrator marked ★:

▼ [team] feature-x
  ◉ ★ orchestrator [claude]
  ○ worker-1     [claude]
  ○ worker-2     [codex]

Session status is shown with a colored dot in both the sidebar and grid view:

○ gray: idle
● green: working
◉ amber: waiting
✕ red: dead

The status legend is always visible in the main status bar and in the grid view footer.

Navigation

Key	Action
`j` / `↓`	Move cursor down
`k` / `↑`	Move cursor up
`J`	Jump to next project
`K`	Jump to previous project
`1`–`9`	Jump to project by number
`Space`	Toggle collapse/expand project or team
`←`	Collapse project/team; on a session, collapses its parent
`→`	Expand project or team
`Tab`	Switch focus between sidebar and preview
`a` / `Enter`	Attach to selected session
`r`	Rename session or team inline
`t`	New session (opens agent picker)
`T`	New agent team (opens wizard)
`n`	New project
`x` / `d`	Kill selected session
`D`	Kill entire team
`g`	Grid view — current project only
`G`	Grid view — all projects
`/`	Filter sessions by name
`?`	Toggle help overlay
`H`	Toggle session keybinding reference
`q`	Quit (sessions keep running)
`Q`	Quit and kill all managed sessions

Grid View

Press g to open a tiled overview of all sessions in the current project. Press G to see all sessions across every project. Each tile shows a live preview of the session's most-recent output and displays the project name, session name, and agent type.

╭─────────────────────╮  ╭─────────────────────╮
│ ● [claude] auth     │  │ ● [codex] tests      │
│ project-alpha       │  │ project-alpha        │
│ Working on JWT…     │  │ Writing unit…        │
╰─────────────────────╯  ╰─────────────────────╯
╭─────────────────────╮
│ ○ [gemini] docs     │
│ project-beta        │
│ Generating API…     │
╰─────────────────────╯
○ idle  ● working  ◉ waiting  ✕ dead
←→↑↓/hjkl: navigate   enter/a: attach   x: kill   r: rename   G: all projects   esc/g/q: exit

You can also left-click a tile to move the cursor to it, or click the hint bar at the bottom to navigate.

Key	Action
Arrow keys / `hjkl`	Navigate tiles
`Enter` / `a`	Attach to selected session
`x`	Kill selected session
`r`	Rename selected session
`G`	Switch to all-projects view
`g` / `Esc` / `q`	Exit grid

Session Titles

Set manually

Select a session and press r. Type the new title and press Enter.

Set by the agent

Any agent can set the session title by writing an OSC 2 escape sequence:

# Standard xterm title sequence — works in any terminal
printf '\033]2;My new title\007'

# Or use the Hive-specific marker (invisible in terminal output)
printf '\000HIVE_TITLE:My new title\000'

Hive polls for these sequences in the background and updates the sidebar automatically. User-set titles take precedence by default (configurable).

Configuration

Config file: ~/.config/hive/config.json

{
  "schema_version": 1,
  "theme": "dark",
  "preview_refresh_ms": 500,
  "agent_title_overrides_user_title": false,
  "multiplexer": "tmux",
  "agents": {
    "claude":   { "cmd": ["claude"] },
    "codex":    { "cmd": ["codex"] },
    "gemini":   { "cmd": ["gemini"] },
    "copilot":  { "cmd": ["copilot"] },
    "aider":    { "cmd": ["aider"] },
    "opencode": { "cmd": ["opencode"] }
  },
  "team_defaults": {
    "orchestrator": "claude",
    "worker_count": 2,
    "worker_agent": "claude"
  },
  "hooks": {
    "enabled": true,
    "dir": "~/.config/hive/hooks"
  },
  "keybindings": {
    "new_project": "n",
    "new_session": "t",
    "new_team": "T",
    "kill_session": "x",
    "kill_team": "D",
    "rename": "r",
    "attach": "a",
    "nav_up": "k",
    "nav_down": "j",
    "nav_project_up": "K",
    "nav_project_down": "J",
    "filter": "/",
    "palette": "ctrl+p",
    "help": "?",
    "quit": "q",
    "quit_kill": "Q"
  }
}

Multiplexer backends

Value	Description
`"tmux"` (default)	Uses the external `tmux` binary. Battle-tested and recommended. Requires tmux to be installed. Detach from a session with Ctrl+B D.
`"native"` ⚠️ alpha	Built-in Go PTY backend. No external dependencies, but not recommended for general use. A background daemon (`hive mux-daemon`) keeps sessions alive after the TUI exits. Enable with `hive start --native`.

Custom agents

Add any CLI tool as a custom agent by extending the agents map:

"agents": {
  "claude": { "cmd": ["claude"] },
  "my-llm": { "cmd": ["my-llm", "--interactive", "--model", "gpt-4o"] }
}

When you press t and choose "custom", Hive will show your custom agents.

Hooks

Hive fires shell hooks on lifecycle events. Drop an executable script into ~/.config/hive/hooks/:

~/.config/hive/hooks/
├── on-session-create
├── on-session-kill
├── on-session-attach
├── on-session-detach
├── on-session-title-changed
├── on-project-create
├── on-project-kill
├── on-team-create
├── on-team-kill
├── on-team-member-add
└── on-team-member-remove

Every hook receives HIVE_* environment variables:

Variable	Example
`HIVE_EVENT`	`session-create`
`HIVE_PROJECT_NAME`	`my-project`
`HIVE_SESSION_TITLE`	`orchestrator`
`HIVE_AGENT_TYPE`	`claude`
`HIVE_TEAM_NAME`	`feature-x`
`HIVE_TEAM_ROLE`	`orchestrator`
`HIVE_WORK_DIR`	`/home/user/project`
`HIVE_TMUX_SESSION`	`hive-abc12345`

Example: macOS notification on new session

#!/bin/bash
# ~/.config/hive/hooks/on-session-create
osascript -e "display notification \"$HIVE_SESSION_TITLE\" with title \"Hive: New $HIVE_AGENT_TYPE session\""

Multiple hooks per event

Create a .d/ directory for multiple hooks on one event (run alphabetically):

~/.config/hive/hooks/on-session-create.d/
├── 01-notify.sh
└── 02-log.sh

Hooks have a 5-second timeout. Non-zero exit codes are logged to ~/.config/hive/hive.log but never crash Hive.

See docs/hooks.md for the full reference.

Agent Teams

Agent teams coordinate multiple AI agents on a shared goal. See docs/agent-teams.md for the full guide.

Quick start:

Press T in a project → fill in the wizard
Attach to the orchestrator (a), describe the task
Switch between worker sessions with j/k to monitor progress
Workers can signal completion: printf '\033]2;DONE: auth module\007'

Headless Attach

Attach to a session by name without starting the TUI:

hive attach orchestrator
hive attach session-1
hive attach <session-id>

Session Persistence

Closing the TUI (q) does not stop your agents. With the tmux backend, sessions live inside a tmux server and keep running after the TUI exits. Re-open Hive with hive start to reconnect — your sessions are exactly where you left them. You can also attach to any session directly with tmux attach -t <session>.

To kill everything on exit, use Q instead of q.

Data Storage

Path	Contents
`~/.config/hive/config.json`	User configuration
`~/.config/hive/state.json`	Projects, teams, sessions
`~/.config/hive/mux.sock`	Native backend daemon socket (alpha only)
`~/.config/hive/mux-daemon.log`	Native backend daemon log (alpha only)
`~/.config/hive/hooks/`	Lifecycle hook scripts
`~/.config/hive/hive.log`	Error and hook output log

Architecture

Hive is built with:

Bubble Tea — Elm-inspired MVU TUI framework
Lip Gloss — terminal styling and layout
Bubbles — text input, list, key binding components
creack/pty — PTY allocation for the native (alpha) multiplexer backend
Cobra — CLI subcommands

The tmux backend delegates to the tmux binary for all session management. The experimental native backend runs as a background daemon (hive mux-daemon) that owns all PTY master file descriptors and communicates with the TUI over a Unix domain socket.

internal/
├── tui/        # Bubble Tea model and all UI components
├── mux/        # multiplexer abstraction
│   ├── native/ # built-in PTY backend (daemon + client)
│   └── tmux/   # tmux backend wrapper
├── tmux/       # tmux CLI wrappers (used by mux/tmux backend)
├── state/      # data model and reducer functions
├── config/     # configuration loading and defaults
├── escape/     # OSC 2 title sequence parser
└── hooks/      # shell hook runner

Contributing

Bug reports and pull requests welcome. See CONTRIBUTING.md for build instructions, testing, and submission guidelines.

Architecture

See ARCHITECTURE.md for a detailed description of every package and how they interact.

Security

See SECURITY.md for the security policy and known considerations for multi-user systems.

License

MIT — see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 101 Commits
.claude		.claude
.github		.github
cmd		cmd
docs		docs
features		features
internal		internal
research/tui-rendering		research/tui-rendering
scripts		scripts
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
build.ps1		build.ps1
build.sh		build.sh
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

Hive

Features

Requirements

Installation

Build from source (Linux / macOS)

Build from source (Windows)

Verify

Getting Started

1. Launch Hive

2. Create a project

3. Create a session

4. Attach to a session

5. Create an agent team

Navigation

Grid View

Session Titles

Set manually

Set by the agent

Configuration

Multiplexer backends

Custom agents

Hooks

Example: macOS notification on new session

Multiple hooks per event

Agent Teams

Headless Attach

Session Persistence

Data Storage

Architecture

Contributing

Architecture

Security

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages