hrdx Terminal Multiplexer

hrdx is a terminal multiplexer optimized for AI agents

hrdx is an experimental, minimal terminal multiplexer written in Go that allows developers to run multiple AI coding agents (such as Claude Code, Codex CLI, pi, and zot) and standard shells side-by-side. It organizes projects as workspaces in a sidebar, providing a centralized environment to monitor and interact with various agents across different directories.

Core Architecture: Real Terminals and Persistence

Unlike terminal wrappers, hrdx utilizes genuine PTY (pseudoterminal) sessions with a full terminal emulator for every pane. This ensures that Agent TUIs (Text User Interfaces) maintain full functionality, including streaming, slash commands, and mouse support. Tools can detect they are running inside hrdx via the HRDX=1 environment variable.

Session Persistence

hrdx employs a lightweight session holder process that keeps pane processes alive even after the TUI is closed. Upon relaunching, hrdx reattaches to these sessions, restoring the exact state of running commands, scrollback, and screen layout (including workspaces, tabs, and split ratios).

Workspace and Agent Management

Visual Organization

The interface features a sidebar that displays a hierarchy of workspaces, Git branches, and panes. To minimize clutter, tab rows are only added when a workspace contains multiple tabs.

Agent Status Tracking

Every pane includes a status indicator to track agent activity:

• Working: Agents display animated braille spinners.
• Finished (Unfocused): An unfocused agent turns orange when it completes a task.
• Acknowledged: Focusing the pane restores the indicator to green.

Custom Agent Integration

Users can register any agent CLI as a custom harness via a harness.json file. This allows third-party agents (like Aider or Goose) to be integrated into the hrdx ecosystem, enabling them to appear in pickers and the sidebar with custom busy-detection strings to drive the status spinners.

Extensibility and Control

Socket API for Automation

hrdx provides a JSON socket API (via a Unix socket) that allows external scripts, editors, or other AI agents to drive the session. Supported methods include:

• workspace.create: Open a directory as a workspace.
• pane.create: Add a pane to a specific workspace.
• pane.send_text: Type text into a pane.
• pane.read: Retrieve the visible screen as plain text.
• pane.wait: Block until an agent is idle or busy.

Remote and Containerized Workflows

Because every pane is a real PTY, hrdx supports remote hosts, Docker containers, and Kubernetes workloads. Users can launch agents directly on remote targets using commands like ssh -tt user@host 'cd /path/to/project && exec codex'. These can be registered as custom harnesses to appear in the native hrdx pickers.

Configuration and Customization

• Keybindings: Prefix keys (default ctrl+b) are remappable via keys.json.
• Themes: Visual styles can be customized using JSON theme files that override ANSI 256 colors or hex codes.
• Notifications: Users can configure system notifications or custom audio files to alert them when an agent finishes a turn.

Community Perspective

While some users praised the tool for its responsiveness and its potential to bring them back to a terminal-based development workflow, others questioned its utility compared to established tools like tmux. One user noted:

"I hate to be that guy, but why would I use this over tmux? All of the features and qualities noted in the readme do not feel novel or unique."

However, hrdx distinguishes itself from tmux by providing a specialized UI for agent status monitoring and a programmable socket API specifically designed for agent-driven automation.