{"slug": "show-hn-yet-another-minimal-and-lightweight-terminal-multiplexer-written-in-go", "title": "Show HN: Yet another minimal and lightweight terminal multiplexer written in Go.", "summary": "Developer 'hrdx' released a minimal terminal multiplexer written in Go that runs real PTY sessions for AI agent CLIs including Codex CLI, Claude Code, pi, and zot, with workspace sidebar, tabs, and session persistence. The tool supports macOS, Linux, and Windows 10 1809+ via ConPTY, offers a JSON socket API for scripting, and can be installed via curl or PowerShell. It is positioned for the 'agent era' by letting users run multiple coding agents side by side and monitor their progress with animated spinners.", "body_md": "hrdx is a experimental, minimal and lightweight terminal multiplexer built for the agent era: your projects as workspaces in a sidebar, tabs per workspace, and real terminal panes running [Codex CLI](https://learn.chatgpt.com/docs/codex/cli), [Claude Code](https://code.claude.com/docs/en/quickstart), [pi](https://www.pi.dev), [zot](https://www.zot.sh) or plain shells side by side. Kick off an agent in one project, switch to the next, and let the sidebar spinners tell you who is still working.\n\n**Real terminals, not wrappers.** Every pane is a genuine PTY session with a full terminal emulator behind it. Agent TUIs run exactly as they do standalone: streaming, slash commands, sessions, mouse support, all of it. Panes present a clean terminal identity so capability-sniffing TUIs pick rendering paths that work inside a multiplexer, and`HRDX=1`\n\nlets tools detect they run inside hrdx.**Everything in view.** The sidebar shows one hierarchy of workspaces, Git branches, and panes, adding tab rows only when a workspace has multiple tabs. Every pane has a shared status circle: agents become animated braille spinners while working, and an unfocused agent turns orange when it finishes. Focusing the pane acknowledges it and restores green.**Feels like your terminal.** Scrollback, mouse selection with clipboard copy, drag-to-resize splits, drag-to-reorder workspaces, right-click context menus, and kitty keyboard protocol pass-through so even exotic chords like ctrl+1 reach your agent.**Picks up where you left off.** Quit and relaunch: shells and agents keep running in a lightweight session holder and reattach exactly where they were, running commands and all. Workspaces, tabs, splits, and ratios come back too, and if a session is truly gone, agents resume their latest conversation from their own session store.**Yours to tune.** A settings window (`ctrl+b ,`\n\nor the gear in the sidebar) lets you switch individual agents on or off, pick a notification sound for finished turns (including your own audio files), and change the color theme, with user themes as simple JSON files. All persisted. See[Themes](#themes).**Bring your own agent.** Register any agent CLI as a custom harness via a small JSON file, including its own busy detection for the sidebar spinner and finish sound. It shows up in pickers, cycling, and settings like the built-ins. See[Custom harnesses](#custom-harnesses).**Scriptable from outside.** A JSON socket API lets scripts and editors inspect workspaces and pane states, open projects, spawn panes, type into agents, wait for them to finish, read their screens, and subscribe to live events. See[Socket API](#socket-api).\n\n```\ncurl -fsSL https://www.hrdx.dev/install.sh | bash\nirm https://www.hrdx.dev/install.ps1 | iex\n```\n\nmacOS, Linux, or Windows (10 1809+ / 11, via [ConPTY](https://learn.microsoft.com/en-us/windows/console/creating-a-pseudoconsole-session)), plus at least one agent CLI on your PATH: `codex`\n\n, `claude`\n\n, `pi`\n\nor `zot`\n\n. Update on any supported platform with `hrdx update`\n\n.\n\n```\nhrdx\n```\n\nOpen several projects at once, or pick your default agent:\n\n```\nhrdx --cwd ~/Developer/api --cwd ~/Developer/web\nhrdx --agent claude\n```\n\n| Flag | Purpose |\n|---|---|\n`--cwd PATH` |\nOpen a project as a workspace, repeatable |\n`--agent ID` |\nDefault agent for new panes: `zot` , `pi` , `claude` , `codex` (default `zot` ) |\n`--provider ID` |\nPass a provider to every zot pane (zot only) |\n`--model ID` |\nPass a model to every zot pane (zot only) |\n`--reasoning LEVEL` |\nSet the reasoning level (zot only) |\n`--continue` |\nResume each project's latest session |\n`--codex-bin PATH` |\nUse a specific codex binary |\n`--claude-bin PATH` |\nUse a specific claude binary |\n`--pi-bin PATH` |\nUse a specific pi binary |\n`--zot-bin PATH` |\nUse a specific zot binary |\n`--shell PATH` |\nShell for shell panes (default `$SHELL` ; on Windows only when resolvable, otherwise `%COMSPEC%` /`powershell.exe` ) |\n`--state PATH` |\nState file for workspace persistence (empty disables) |\n`--fresh` |\nIgnore saved workspaces and start clean |\n`--api` |\nServe the control API on a unix socket (default on, `--api=false` disables) |\n`--persist` |\nKeep pane processes alive across restarts via the session holder (default on) |\n\nA native Windows `hrdx.exe`\n\nlaunched from Git Bash ignores an MSYS-only `SHELL`\n\nvalue such as `/usr/bin/bash`\n\n, which Windows cannot resolve, and falls back to `%COMSPEC%`\n\n. To use Git Bash for panes, pass a native path explicitly, for example `hrdx --shell \"C:/Program Files/Git/bin/bash.exe\"`\n\n.\n\nAll keys go to the focused terminal, except the `ctrl+b`\n\nprefix (tmux style):\n\nAfter `ctrl+b` |\nAction |\n|---|---|\n`c` or `C` |\nSplit right / below (opens a picker: installed agents or shell) |\n`a` or `A` |\nSplit right / below with the default agent directly |\n`s` or `S` |\nSplit with a new shell pane directly (right / below), also `%` /`\\\"` and `|` /`-` |\n`w` |\nNew workspace (directory prompt with tab completion, then agent/shell picker) |\n`t` |\nNew tab in the current workspace (opens the agent/shell picker) |\n`n` or `p` |\nNext / previous tab |\n`]` or `[` |\nNext / previous workspace |\n`tab` or `shift+tab` |\nNext / previous pane; stays in prefix mode for repeated jumps, `esc` exits |\n`/` |\nFuzzy finder over every workspace, tab, and pane: type to filter, arrows select, enter jumps |\n`r` |\nRename the focused pane |\n`m` |\nOpen the pane context menu |\n`=` |\nEqualize all splits |\n`u` or `d` (or `pgup` /`pgdown` ) |\nScroll the focused pane's history |\n`esc` / `G` |\nBack to live output, clear selection |\n`,` |\nSettings window: enable / disable agents, notifications |\n`x` |\nClose pane (sibling takes its room) |\n`X` |\nClose workspace |\n`ctrl+b` |\nSend a literal ctrl+b to the pane |\n`q` |\nQuit |\n`left` / `right` |\nScroll the hint row in the footer (narrow terminals) |\n\nPanes whose process exits (for example `exit`\n\nin a shell) close automatically; the sibling pane takes the room. Panes that fail to start stay visible with the error.\n\nPrefix keys are remappable via a `keys.json`\n\nnext to the state file (`~/Library/Application Support/hrdx/keys.json`\n\non macOS, `$XDG_CONFIG_HOME/hrdx/keys.json`\n\non Linux, `%AppData%\\hrdx\\keys.json`\n\non Windows). It maps action names to a single key; an override replaces that action's default keys. The `prefix`\n\naction remaps the `ctrl+b`\n\ntrigger itself, not just an action inside it:\n\n```\n{\n  \"find\": \"f\",\n  \"quit\": \"Q\",\n  \"agent-cycle\": \"g\"\n}\n```\n\nActions: `prefix`\n\n, `literal`\n\n, `quit`\n\n, `picker-right`\n\n, `picker-down`\n\n, `agent-right`\n\n, `agent-down`\n\n, `agent-cycle`\n\n(unbound by default), `shell-right`\n\n, `shell-down`\n\n, `workspace`\n\n, `tab-new`\n\n, `tab-next`\n\n, `tab-prev`\n\n, `space-next`\n\n, `space-prev`\n\n, `pane-next`\n\n, `pane-prev`\n\n, `find`\n\n, `close-pane`\n\n, `close-space`\n\n, `equalize`\n\n, `rename`\n\n, `menu`\n\n, `settings`\n\n, `scroll-up`\n\n, `scroll-down`\n\n, `live`\n\n.\n\nEverything is clickable: workspace, tab, and pane rows in the sidebar, the main tab bar, menus, and the settings entry at the bottom. Drag workspaces to reorder them, drag pane borders to resize, right-click for context menus, and drag with the left button to select text (copied straight to your clipboard). Wheel events go to the pane under the cursor: agent TUIs scroll themselves, shells scroll their local history, and `shift+pgup`\n\n/ `shift+pgdn`\n\ndo the same from the keyboard.\n\nEvery pane is a real PTY, so a shell pane can connect to a remote host, Docker container, or Kubernetes workload. For an interactive shell:\n\n```\nssh user@host\ndocker exec -it -w /workspace container-name sh\nkubectl exec -it -n namespace deploy/app -- sh\n```\n\nAn agent installed at the target can be launched directly instead:\n\n```\nssh -tt user@host 'cd /path/to/project && exec codex'\ndocker exec -it -w /workspace container-name codex\nkubectl exec -it -n namespace deploy/app -- codex\n```\n\nUse the same pattern for any supported or custom agent. Authentication and the agent executable, configuration, credentials, and project files must be available at the target.\n\nTo make remote and container agents appear in pickers, agent cycling, settings, and the sidebar, register their client command as a custom harness:\n\n```\n[\n  {\n    \"kind\": \"remote-codex\",\n    \"binary\": \"ssh\",\n    \"args\": [\"-tt\", \"user@host\", \"cd /path/to/project && exec codex\"]\n  },\n  {\n    \"kind\": \"docker-codex\",\n    \"binary\": \"docker\",\n    \"args\": [\"exec\", \"-it\", \"-w\", \"/workspace\", \"container-name\", \"codex\"]\n  },\n  {\n    \"kind\": \"k8s-codex\",\n    \"binary\": \"kubectl\",\n    \"args\": [\"exec\", \"-it\", \"-n\", \"namespace\", \"deploy/app\", \"--\", \"codex\"]\n  }\n]\n```\n\nWrapper scripts are useful when the host, container, namespace, pod, working directory, or authentication setup is dynamic. Set the harness `binary`\n\nto the wrapper path and put any fixed parameters in `args`\n\n.\n\nThe session holder keeps the local SSH, Docker, or Kubernetes client process alive when hrdx restarts. It cannot keep an agent alive when its remote host, container, pod, or network connection ends, and it does not automatically reconnect. Workspace Git details are read from the local workspace path, not from the remote filesystem.\n\nAny agent CLI beyond the built-ins can be registered by dropping a `harness.json`\n\nnext to the state file (`~/Library/Application Support/hrdx/`\n\non macOS, `$XDG_CONFIG_HOME/hrdx/`\n\non Linux, `%AppData%\\hrdx\\`\n\non Windows). Registered harnesses appear everywhere the built-ins do: in the pickers, in agent cycling, as agent panes in the sidebar hierarchy, and in the settings window for enabling and disabling.\n\n```\n[\n  {\n    \"kind\": \"aider\",\n    \"binary\": \"aider\",\n    \"args\": [\"--no-auto-commits\"],\n    \"resume\": [\"--restore-chat-history\"],\n    \"busy\": \"Waiting for the model\"\n  },\n  {\n    \"kind\": \"goose\",\n    \"idle_title\": \"goose idle\",\n    \"attention_title\": \"goose waiting\"\n  }\n]\n```\n\n| Field | Purpose |\n|---|---|\n`kind` |\nIdentifier used in pickers and pane names (required, must not collide with built-ins) |\n`binary` |\nExecutable to launch (default: same as `kind` ) |\n`args` |\nExtra arguments passed on every launch |\n`resume` |\nArguments that resume the latest session when a restored pane relaunches |\n`resume_first` |\nPut the resume args before `args` (for subcommands like `resume --last` ) |\n`busy` |\nA substring visible on screen only while the harness is working; drives the busy spinner and the finish sound. Empty: braille spinner detection, like the built-ins |\n`idle_title` |\nTerminal-title substring emitted when the harness is idle; overrides a stale visible spinner |\n`attention_title` |\nTerminal-title substring emitted while waiting for user input; overrides the spinner and shows an orange dot when unfocused |\n\nBoth title fields are optional and have no defaults, since every harness\npublishes its own markers. Leave them out and the harness is detected purely\nfrom the screen, exactly as `busy`\n\ndescribes. Set them when the harness keeps a\nspinner on screen while it is really idle or blocked on a prompt: a matching\ntitle always outranks the screen scrape. Check what your harness emits with\n`printf '\\e]2;...\\a'`\n\n-style OSC titles before picking a substring.\n\nWhile hrdx runs it serves a control API on a unix socket next to the state file (`hrdx.sock`\n\n), so scripts, editors, and coding agents can inspect and drive a running session. Disable with `--api=false`\n\n.\n\nThe protocol is newline-delimited JSON: send one request per line, receive one response line with the same `id`\n\n.\n\n```\nSOCK=\"$HOME/Library/Application Support/hrdx/hrdx.sock\"   # macOS\n# SOCK=\"$XDG_CONFIG_HOME/hrdx/hrdx.sock\"                  # Linux\n# hrdx.sock is a native Windows AF_UNIX socket too (%AppData%\\hrdx\\hrdx.sock).\n# WSL has a separate socket namespace and cannot connect to it directly; Git\n# Bash does not ship a compatible `nc -U`. Use a native Windows client, such\n# as .NET UnixDomainSocketEndPoint or Go's net.DialUnix.\n\necho '{\"id\": \"1\", \"method\": \"status\"}' | nc -U \"$SOCK\"\necho '{\"id\": \"2\", \"method\": \"workspace.create\", \"params\": {\"path\": \"~/Developer/api\", \"agent\": \"claude\"}}' | nc -U \"$SOCK\"\necho '{\"id\": \"3\", \"method\": \"pane.create\", \"params\": {\"workspace\": \"api\", \"kind\": \"shell\", \"split\": \"down\"}}' | nc -U \"$SOCK\"\necho '{\"id\": \"4\", \"method\": \"pane.send_text\", \"params\": {\"pane_id\": 3, \"text\": \"run the tests\", \"enter\": true}}' | nc -U \"$SOCK\"\necho '{\"id\": \"5\", \"method\": \"pane.wait\", \"params\": {\"pane_id\": 3, \"until\": \"idle\"}}' | nc -U \"$SOCK\"\necho '{\"id\": \"6\", \"method\": \"pane.read\", \"params\": {\"pane_id\": 3}}' | nc -U \"$SOCK\"\n```\n\n| Method | Effect |\n|---|---|\n`ping` |\nLiveness check, returns `pong` |\n`status` |\nWorkspaces, tabs, and panes with id, kind, running, and busy state |\n`workspace.create` |\nOpen a directory as a workspace (`path` , optional `agent` ) |\n`workspace.close` |\nClose a workspace by name or path |\n`pane.create` |\nAdd a pane (`workspace` name or path, `kind` , `split` : `right` , `down` , `tab` ) |\n`pane.send_text` |\nType into a pane (`pane_id` , `text` , optional `enter` ) |\n`pane.read` |\nThe pane's visible screen as plain text |\n`pane.wait` |\nBlock until a pane's agent is `idle` or `busy` (`until` , optional `timeout_ms` ) |\n`pane.close` |\nClose a pane by id |\n`events.subscribe` |\nKeep the connection open and push events |\n\nSuccessful responses are `{\"id\": \"...\", \"result\": {...}}`\n\n; failures are `{\"id\": \"...\", \"error\": {\"code\": \"not_found\", \"message\": \"...\"}}`\n\nwith codes `not_found`\n\n, `invalid_params`\n\n, `unknown_method`\n\n, `timeout`\n\n, and `error`\n\n.\n\nAfter `events.subscribe`\n\nthe connection stays open and hrdx pushes lines like `{\"event\": \"pane.busy_changed\", \"data\": {\"pane_id\": 3, \"busy\": false}}`\n\n. Events: `workspace.created`\n\n, `workspace.closed`\n\n, `pane.created`\n\n, `pane.closed`\n\n, and `pane.busy_changed`\n\n, so a script can react the moment an agent finishes instead of polling.\n\nEvery request is answered by the TUI's own update loop, so the API always sees exactly what is on screen. `pane.wait`\n\nplus `pane.send_text`\n\nis enough to build simple agent pipelines: prompt an agent, wait until it is idle, read the screen, move on.\n\nhrdx themes are JSON files that override any subset of the built-in colors; missing values inherit the default look. Drop them into a `themes/`\n\ndirectory next to the state file (`~/Library/Application Support/hrdx/themes/`\n\non macOS, `$XDG_CONFIG_HOME/hrdx/themes/`\n\non Linux, `%AppData%\\hrdx\\themes\\`\n\non Windows) and pick them in the settings window's theme section. The change applies immediately and persists.\n\n```\n{\n  \"name\": \"neon\",\n  \"description\": \"Pink accent, near-black bars.\",\n  \"colors\": {\n    \"accent\": 201,\n    \"bar_bg\": \"#101010\"\n  }\n}\n```\n\nValues are ANSI 256 color numbers or `\"#rrggbb\"`\n\nstrings.\n\n| Color | Used for |\n|---|---|\n`accent` |\nFocused pane frames, highlights, logo, selected items |\n`alt` |\nPrefix badge, behind-count in the sidebar |\n`muted` |\nSecondary text, hints, idle pane names |\n`faint` |\nInactive pane borders, sidebar divider |\n`good` |\nRunning dots, input badge |\n`busy` |\nBusy spinner and completed-work attention dot |\n`bad` |\nErrors, exited dots |\n`bar_bg` / `bar_fg` |\nHeader and footer bars |\n`ink` |\nText on accent backgrounds, tab bar strip |\n\nSee `examples/themes/`\n\nfor a full example.\n\nThe notification section of the settings window has two independent toggles for finished agent turns: play a sound (built-in `ding`\n\nand `chime`\n\n, or your own audio files) and a system notification, which rings the terminal bell so your platform's native attention indicator fires: dock badge and bounce on macOS, the window manager's urgency hint on Linux, the taskbar/window attention flash on Windows Terminal (depends on its `bellStyle`\n\nsetting). No notification daemon or permission required. Add custom sounds with a `sounds.json`\n\nnext to the state file; they appear as choices and are previewed when selected:\n\n```\n[\n  { \"name\": \"sheep\", \"file\": \"~/sounds/maehhh.wav\" },\n  { \"name\": \"gong\", \"file\": \"/Users/me/sounds/gong.aiff\" }\n]\n```\n\n`name`\n\nis the label in settings (must not collide with built-ins), `file`\n\nany audio file your OS player understands (`afplay`\n\non macOS, `paplay`\n\n/`aplay`\n\non Linux, PowerShell's `SoundPlayer`\n\non Windows — WAV only there). Missing files are reported in the footer and skipped.\n\nQuitting hrdx does not kill your sessions. Pane processes live in a small background process (the session holder) that hrdx starts on demand and talks to over a local socket. Close the TUI, reopen it, and every shell and agent reattaches exactly where it was: running commands keep running, scrollback and screen state are replayed, nothing restarts. The holder is the same `hrdx`\n\nbinary, uses no resources worth mentioning, and goes away when you kill its sessions.\n\nWorkspaces, panes, split layout, ratios, selection, and holder session ids are saved automatically (default: `~/Library/Application Support/hrdx/state.json`\n\non macOS, `$XDG_CONFIG_HOME/hrdx/state.json`\n\non Linux, `%AppData%\\hrdx\\state.json`\n\non Windows). On the next launch the layout is restored and each pane reattaches to its held session. When a held session is gone (rebooted machine, killed holder), the pane starts fresh instead: shell panes get a new shell, and agent panes relaunch resuming their latest session for that directory via the agent's own session store.\n\n`--persist=false`\n\ndisables the holder (panes die with the TUI, like a plain terminal). `--fresh`\n\nskips restoring and cleans up now-unreferenced held sessions; `--state \"\"`\n\ndisables persistence entirely.\n\n```\nmake check\n```\n\nWindows without `make`\n\non `PATH`\n\n: `go vet ./... && gofmt -l . && go test ./...`\n\n.\n\nMIT", "url": "https://wpnews.pro/news/show-hn-yet-another-minimal-and-lightweight-terminal-multiplexer-written-in-go", "canonical_source": "https://github.com/patriceckhart/hrdx", "published_at": "2026-08-27 17:44:53+00:00", "updated_at": "2026-08-27 18:20:01.879533+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["hrdx", "Codex CLI", "Claude Code", "pi", "zot", "ConPTY"], "alternates": {"html": "https://wpnews.pro/news/show-hn-yet-another-minimal-and-lightweight-terminal-multiplexer-written-in-go", "markdown": "https://wpnews.pro/news/show-hn-yet-another-minimal-and-lightweight-terminal-multiplexer-written-in-go.md", "text": "https://wpnews.pro/news/show-hn-yet-another-minimal-and-lightweight-terminal-multiplexer-written-in-go.txt", "jsonld": "https://wpnews.pro/news/show-hn-yet-another-minimal-and-lightweight-terminal-multiplexer-written-in-go.jsonld"}}