# hrdx

> hrdx is an experimental, minimal, lightweight terminal multiplexer built for the agent era: projects as workspaces in a sidebar, tabs per workspace, and real terminal panes running Codex CLI, Claude Code, zot, pi, or plain shells side by side. Free and open source under the MIT license.

Key facts:
- Every pane is a genuine PTY session with a full terminal emulator behind it; agent TUIs run exactly as they do standalone. `HRDX=1` lets tools detect they run inside hrdx.
- The sidebar shows every workspace with its git branch and ahead/behind counts, every pane with a live status dot, and optional nested group headings. Groups are labels, not processes or directories, and can contain non-Git workspaces.
- Sessions persist across restarts via a lightweight session holder: shells and agents reattach exactly where they were, running commands and all.
- Any agent CLI can be registered as a custom harness via a small JSON file (harness.json), including remote agents over ssh, docker, or kubectl.
- A JSON socket API (hrdx.sock, newline-delimited JSON) lets scripts inspect workspaces, spawn split or tab-scoped floating panes, type into agents, wait for idle, read screens, subscribe to events, and register custom pane, tab, or sidebar context-menu actions. workspace.create accepts an optional group_path array or opt-in group_from_git default. workspace.move changes group membership without restarting panes, [] makes a workspace standalone, and group.list returns occupied group paths and ancestors. Status remains a flat workspace list with optional group_path fields. On Unix, hrdx uses XDG_RUNTIME_DIR/hrdx/hrdx-<id>.sock if the state directory cannot host sockets, where <id> is the first 16 hex digits of the SHA-256 hash of the absolute state path.
- An opt-in plugin platform (--plugins) runs approved external processes over newline-delimited JSON on stdio. Plugins declare context-menu actions, finder search providers, notifications, footer status, views, activation markers, and typed configuration in a plugin.json manifest. Scoped group.list requires workspace.read, and workspace.move requires its separate grant. Plugins are trusted code, not sandboxed.
- Floating panes render above the split layout at center, top, bottom, left, or right anchors without changing sibling ratios. They are ephemeral, omitted from the sidebar, and close through their title-bar x or pane.close.
- State, keys, harnesses, themes, and plugins share one directory: ~/Library/Application Support/hrdx on macOS, $XDG_CONFIG_HOME/hrdx on Linux, %AppData%\hrdx on Windows. Sockets stay beside the state file when supported. Otherwise macOS and Linux can use XDG_RUNTIME_DIR for the API and holder sockets, while existing holder sockets are retained. An absolute XDG_CONFIG_HOME is honored on macOS as well, with an existing Application Support directory kept until moved.
- Themes are JSON files overriding any subset of the built-in colors; notification sounds and per-agent toggles are configurable in the settings window.
- Prefix keys are tmux style behind ctrl+b. The fuzzy finder shows and searches group paths, but group placement is API/plugin-only. Full mouse support: click, drag to resize and reorder, right-click menus, text selection to clipboard. Group headings are not interactive.
- Install: curl -fsSL https://www.hrdx.dev/install.sh | bash (macOS or Linux, needs at least one agent CLI on PATH). Update with `hrdx update`.

## Docs

- [Getting started](https://www.hrdx.dev/docs): install, run, CLI flags, persistence
- [Keys and mouse](https://www.hrdx.dev/docs/keys): ctrl+b prefix keys, mouse interactions
- [Custom harnesses](https://www.hrdx.dev/docs/harnesses): harness.json format, remote and container panes
- [Socket API](https://www.hrdx.dev/docs/api): methods, events, scripting examples
- [Plugins](https://www.hrdx.dev/docs/plugins): approval, capability grants, manifest, wire protocol
- [Themes](https://www.hrdx.dev/docs/themes): theme JSON format, color slots, default palette

## Project

- [GitHub repository](https://github.com/patriceckhart/hrdx): source code, issues, releases
- [README](https://raw.githubusercontent.com/patriceckhart/hrdx/main/README.md): full reference documentation
- [Install script](https://www.hrdx.dev/install.sh): installation one-liner target

## Legal

- [Privacy](https://www.hrdx.dev/privacy): no data collection, no cookies, no trackers
- [Disclaimer](https://www.hrdx.dev/disclaimer): no warranty, MIT licensed