DraconDev/terhub

> terhub is a fullscreen TUI (plus a plain CLI) that gathers every
> session, every pane, and every agent from every place you work
> (local tmux/zellij/screen, SSH hosts, agent processes) into one
> screen, names which ones need you, and lets you jump to them, mark
> them, and drive them. It's the overview that the terminal never had.
If you've ever lost a pane in a stack of tmux ls outputs, missed an
agent waiting for input because you were in the wrong window, or wanted
to see at a glance which of fifteen sessions actually need you —
terhub is the screen that fixes that. It works on top of tmux, zellij,
and screen locally, and reaches across SSH to other hosts.
## Backend parity
Every backend is the same TUI; what differs is which CLI verbs terhub has
implemented for it. A - in the table means the verb is not wired yet,
so a row in that backend will be visible but its p/x/r keys won't
do anything (you can still attach and read).
| Capability | tmux | zellij | screen | SSH fleet | native tabs |
| List sessions | ✓ | ✓ | ✓ | ✓ | ✓ |
| Attach | ✓ | ✓ | ✓ | ✓ | ✓ |
| List panes | ✓ | – | – | ✓ | – |
| Capture last lines | ✓ | – | – | ✓ | – |
| Kill / swap / focus | ✓ | – | – | ✓ | – |
| Agent hook events | ✓ | – | – | – | – |
| Activity sparkline | ✓ | – | – | ✓ | – |
| Freezing / thawing | ✓ | – | – | ✓ | – |
Native tabs are Konsole, kitty, and WezTerm — the TUI lists them so you
can Enter into them; it does not drive their panes. SSH fleet goes
through the terhub binary on the remote, so anything the remote's
backend supports is supported there too.
## Install
Requires tmux 3.x on PATH and Rust 1.89+.
sh
cargo install --path .
terhub init # config + agent hooks + daemon, one shot
terhub # opens the TUI
First run creates ~/.config/terhub/config.toml with defaults.
Full manual: GUIDE.md.
Project status: AUDIT.md (the 2026-10-19 audit — 36 findings) and
TASKS.md (the prioritised improvement backlog).
## The TUI
One-line session bar on top, one huge pane table, one status bar — no modes
except small popups:
Session bar. All plus one segment per session, with attached marker
(●/○), pane counts, and a worst-state dot (red = something needs you).
←/→ filters the table immediately, Enter attaches, Alt+1..8 jumps
to tabs.
Pane table. Every pane: attention mark (! needs you, + marked,
focused, ✓ already seen), pane id, session, window, command, repo
dir, agent, state, source (hook = agent-reported fact, proc = binary
found, scr = screen guess), time in state, last turn, idle age
(every row shows it, working included — it separates "streaming"
from "frozen on the same frame"; only a truly idle row tints), and
a summary carrying the prompt or error line that decided the state.
States that matter are red. Waiting, error, stuck, and quota-limited
rows shout; working/idle/paused are quiet. The filter chip (◼) names every
filter hiding rows so one is never silently active.
Preview on demand. Right-click or p: fullscreen scrollable reader
over the pane's last 500 lines with its own ANSI colors, live CPU, and —
in git repos — branch plus diff shortstat.
Filters. f searches (or just start typing); ! excludes. The
standing exclusion from [ui] filter is always on. A query that is