Capture is opt-in, consent-gated, and fully reversible. Nothing is captured until you say yes; one command reverts everything.

A terminal you kill from Terminal Hub really dies. A hub-owned session you spawn keeps running until you kill it. The background router can crash and your shells survive — there's no system-wide single point of failure.

Table of contents

• Install
• Features
• How it works
• Platform support
• Usage
• Configuration
• Update
• Uninstall
• Roadmap
• Security
• License

Install

npm i -g @term-hub/term-hub

This installs the term-hub and hub commands and registers a launcher in your OS apps menu (Launchpad/Spotlight on macOS, the app grid on Linux, the Start Menu on Windows).

• Launch the GUI: run term-hub, or click Terminal Hub in your apps menu. The install registers it automatically.
• Use the CLI: hub status, hub kill <id>, hub update, hub uninstall, …

On first launch, Terminal Hub asks to enable capture — click Enable, then open a new terminal and it shows up.

npm i -g @term-hub/term-hub pulls in exactly one platform-specific binary package (@term-hub/darwin-arm64, @term-hub/darwin-x64, @term-hub/linux-x64, or @term-hub/linux-arm64) via optionalDependencies — npm resolves this automatically based on your OS/CPU, so you never download binaries for a platform you're not on.

Features

Capture & control

• Auto-capture every interactive shell via a one-time, consent-gated shell-rc hook.
• Two views of one shell — drive a session from hub and from the terminal it was spawned in.
• Spawn hub-owned sessions that persist independently of any terminal.
• Session buckets — Healthy / Ghost (dead socket) / Orphan (live, no record), so nothing gets lost.

The canvas

• Terminals are floating windows — drag the title bar to move, drag the corner to resize.
• Infinite pannable / zoomable canvas — drag empty space to pan, ⌘/Ctrl-scroll to zoom, Fit to frame them all.
• Attach / Detach (stop viewing, session keeps running) and Kill (end the shell), with in-button progress.

Correct & safe

• No single point of failure — each session owns its own pty in a detached process; killing the router never kills a shell.
• Authenticated — per-install token + same-uid peer-credential check on every socket.
• Real terminal behavior — raw-mode passthrough (arrow keys, tab-completion, Ctrl-C all work), no double-echo.
• Reversible — uninstall reverts the rc change, removes ~/.hub, and removes the installed app.
• Self-updating GUI — the desktop app checks for, downloads, verifies (Ed25519-signed), and installs new versions of itself; no reinstall needed.

How it works

• hub-relay — one process per session. It owns the pty and a headless vt100 screen (for replay), fully detached. Because the shell lives here, the router can die and restart without touching your shells.
• hub-daemon — a non-pty reverse-proxy router over a single unix socket. It knows every session and fans viewers out to the right relay. It owns no pty, so it is never a single point of failure.
• hub-cli (hub) — install / uninstall / update / kill / status. Owns the rc-file editing (marker-guarded, byte-exact backup, edit-preserving restore) and autostart (launchd on macOS, systemd on Linux).
• hub-app — the desktop GUI: an infinite canvas of terminal windows, per-tile connection to the daemon.

Platform support

| Platform | Status | Notes | |---|:---:|---| | macOS (Apple Silicon & Intel) | ✅ Supported | launchd autostart, real signed .app bundle, self-updating | | Linux (x86_64 & arm64) | ✅ Supported | systemd user unit, AppImage, self-updating | | Windows | 🚧 In progress | CLI/engine work is underway; no GUI binaries published yet |

Notes:

• macOS: the app is ad-hoc signed (no Developer ID yet) — Gatekeeper won't complain about a locally-built or self-updated copy, but a fresh download from a browser may show an "unidentified developer" warning once.
• Linux: the GUI needs the webkit runtime — sudo apt install libwebkit2gtk-4.1-0 (Debian/Ubuntu) or sudo dnf install webkit2gtk4.1 (Fedora); the launcher tells you if it's missing.
• Windows: binaries aren't published yet — see Roadmap.

Usage

• Capture a terminal — just open a new terminal after enabling. It appears under Healthy as an External session.
• Open a tile — click a session (or Open) to bring up its live terminal on the canvas.
• Move / resize — drag the title bar to move a window; drag the bottom-right corner to resize (the shell's size follows).
• Pan / zoom — drag empty canvas to pan, ⌘/Ctrl-scroll to zoom toward the cursor, Fit to frame all windows.
• New hub session — + New session spawns a hub-owned shell that persists until killed.
• Detach vs Kill — Detach stops viewing (the session keeps running); Kill ends the shell for everyone.
• CLI:

  hub status              # list live sessions (healthy / ghost / orphan)
  hub kill <id>            # end a session's shell

Configuration

• Bypass capture for one shell: HUB_DISABLE=1 in the environment skips the hook.
• Turn capture off globally: uninstall (below), or comment out the marked block in your rc file.
• Scrollback buffer: set per-tile scrollback in the app's Settings (gear icon, bottom of the sidebar) — applies to newly opened tiles.
• Update prompts: the app checks for updates on launch and every 24h while open; accepting a prompt restarts the app onto the new version.

Update

The desktop app self-updates — it checks for new versions automatically and prompts you to restart when one's available. You don't need to reinstall via npm for GUI updates.

The CLI engine can also be swapped in place without dropping live sessions:

hub update --bin-src <dir> [--yes]

• --bin-src <dir> — copies hub, hub-daemon, hub-relay from <dir> into ~/.hub/bin. Omit it to leave the binaries on disk untouched and just restart the daemon.
• --yes — skip the confirmation prompt.

Under the hood: the daemon process is stopped and a fresh one started (binaries are swapped via an atomic rename). Your terminals' shells and ptys are owned by independent relay processes that are never touched — the new daemon re-discovers every still-running session on its own startup. Expect a sub-second window where hub status / the GUI can't reach the daemon; the sessions themselves never blink.

Requires a prior hub install; running it without one fails with a clear error rather than doing anything.

Uninstall

• From the app: Settings → Uninstall hub & remove app — reverts the rc line (preserving any edits you made after install), stops the service, deletes ~/.hub, and removes the installed app.
• From the CLI:

  hub uninstall                    # revert the shell-rc capture hook, stop the daemon, delete ~/.hub
  npm rm -g @term-hub/term-hub     # remove the CLI + the installed GUI app + apps-menu entry

Either path is a complete, equivalent teardown — npm uninstall and the in-app button both leave the exact same clean state. Uninstall is surgical: it removes only hub's own block from your rc file and leaves everything else untouched.

Roadmap

• Windows support (in progress) — the current engine leans on POSIX (unix sockets, fork/setsid, termios). Windows needs named-pipe transport, a CreateProcess-based detach, console-mode raw handling, a PowerShell-profile capture hook, Windows peer-credential auth, and Task Scheduler autostart.
• Layouts & workspaces — save/restore canvas arrangements; named workspaces.
• Persistence options — opt-in "keep external sessions alive after their terminal closes."
• Canvas polish — edge-resize (not just corner), snap/tiling helpers, minimap.
• Remote sessions — securely attach to relays on another host.

Security

• Every daemon/relay socket requires a per-install token (~/.hub/token, mode 0600) and a same-uid peer-credential check — a different user can't read the token or connect.
• Capture is off until you consent, and the injected rc block is guarded (HUB_ACTIVE / HUB_DISABLE / interactive / tty / command -v hub) so it degrades safely and never bricks your shell.
• The daemon owns no pty and never sees your shell's environment on the wire.
• The desktop app only ever installs updates whose Ed25519 signature verifies against a pinned public key — a tampered or unsigned build is rejected, both on first install and on every self-update.

License

MIT