POSIX tmux + git worktree orchestrator for parallel “heads”
One tmux session + worktree per branch. Fast switches, layouts, YAML, and a multi-session dashboard; optional GitHub issues and AI agents.
- Requirements:
git,tmux(≥ 3.0). Optional:fzf, GitHub CLI, an AI CLI (claude,aider,gemini, etc.). - Install:
git clone https://github.com/Someblueman/hydra && cd hydra && sudo ./install.sh- or
sudo make install
- Try it:
hydra spawn feature-x -l devhydra list•hydra switch•hydra dashboard•hydra kill feature-x
If you want to generate GIFs yourself, you can use the VHS project from Charm
# Create a new head for a branch (tmux + worktree)
hydra spawn feature-branch [-l default|dev|full]
# From a GitHub issue
hydra spawn --issue 123
# Bulk and mixed agents
hydra spawn feature -n 3 --ai aider
hydra spawn exp --agents "claude:2,aider:1"
# Inspect & switch
hydra list # list all sessions
hydra list --json # JSON output for scripting
hydra list -g mygroup # filter by group
hydra switch # interactive (fzf if available)
# Manage
hydra kill feature-branch
hydra kill --all [--force]
hydra cleanup # remove dead mappings, stale locks, orphaned worktrees
# Group operations
hydra group feature-x backend # assign to group
hydra group feature-x # show group
hydra group feature-x --clear # remove from group
# Session output
hydra tail feature-x # view last 50 lines of session output
hydra tail feature-x -f # follow session output continuously
hydra broadcast "make test" # send command to all sessions
hydra broadcast -g backend "..." # send to specific group
hydra wait-idle # wait for sessions to become idle
hydra wait-idle -g backend -s 10 # wait for group with 10s idle threshold
# System
hydra regenerate # restore sessions after restart
hydra status # per-head health
hydra status --json # JSON output
hydra doctor # performance diagnostics
# Dashboard & TUI
hydra dashboard # multi-session overview
hydra tui # interactive session managerdefault: Single full-screen panedev: Two panes (editor ~70% left, terminal right)full: Three panes (editor top-left, terminal top-right, logs bottom)- Cycle in-session with
Ctrl-L.
| Variable | Description |
|---|---|
HYDRA_HOME |
Runtime dir (default ~/.hydra) |
HYDRA_AI_COMMAND |
Default AI tool (claude) |
HYDRA_ROOT |
Force library discovery when running from source |
HYDRA_DASHBOARD_PANES_PER_SESSION |
1, N, or all |
HYDRA_SKIP_AI |
Skip auto-starting AI tool on spawn |
HYDRA_DASHBOARD_NO_ATTACH |
Create dashboard without attaching |
HYDRA_NONINTERACTIVE |
Skip all confirmation prompts (for CI/automation) |
HYDRA_REGENERATE_RUN_STARTUP |
Run startup commands on regenerate |
HYDRA_ALLOW_ADVANCED_REFS |
Relax branch charset validation (use with care) |
HYDRA_DISABLE_YAML |
Disable YAML config parsing |
Per‑head AI selection is persisted: hydra spawn <branch> --ai <tool> shows in hydra list/status and is reused by hydra regenerate.
Place .hydra/config.yml in the worktree or repo root to declare windows/panes and optional startup commands:
windows:
- name: editor
panes:
- cmd: nvim
- cmd: bash
split: v
- name: server
panes:
- cmd: npm run dev
startup:
- echo "Project ready"- On spawn/regenerate: windows and panes are applied.
startupruns on spawn, and on regenerate only ifHYDRA_REGENERATE_RUN_STARTUP=1. - Minimal parser supports the fields above; values are plain strings.
Add .hydra/ scripts to customize lifecycle:
hooks/pre-spawn: runs before tmux session; env:HYDRA_WORKTREE,HYDRA_BRANCH.hooks/layout: override built‑in layouts; env:HYDRA_SESSION,HYDRA_WORKTREE.startup: one command per line; sent to the main pane after spawn.hooks/post-spawn: after layout/startup; env:HYDRA_SESSION,HYDRA_WORKTREE,HYDRA_BRANCH.
- Shows panes from all heads in one tmux window; exits with
qand restores everything. - Collect more than one pane per head with
--panes-per-session <N|all>orHYDRA_DASHBOARD_PANES_PER_SESSION.
Interactive terminal UI for managing sessions with real-time updates.
hydra tui| Key | Action |
|---|---|
j/k, arrows |
Navigate sessions |
Enter |
Switch to selected session |
Space |
Toggle selection (for bulk ops) |
x |
Toggle all selections |
G |
Select all |
d |
Kill selected session(s) |
t |
Set tag on session |
T |
Filter by tag |
/ |
Search/filter sessions |
? |
Show help overlay |
q |
Quit |
make lint # ShellCheck + dash syntax
make test # Run tests in tests/*.sh
make help # Show all targetssudo ./uninstall.sh # prompts to remove user data
sudo ./uninstall.sh --purge # non-interactive, remove user dataMIT