Herdr: Terminal Multiplexer with Built-in AI Agent State Awareness

Herdr is a terminal-native agent runtime and multiplexer built in Rust with the Ratatui TUI library. It runs inside your existing terminal (WezTerm, iTerm2, Kitty, and others) rather than replacing it. It adopts the pane, tab, and session persistence model of tmux and extends it with awareness of AI coding agents: processes running in Herdr panes are identified as agents and their state (working, idle, blocked) is displayed in a sidebar.

Why a multiplexer built for agents

tmux treats all processes the same. If a Claude Code or Codex instance is running in a pane, tmux sees a text stream with no understanding of the process state. Herdr identifies these agents and surfaces their state, so a single glance at the sidebar shows which agents are working, which are idle, and which are blocked waiting for input.

Newer AI-native terminals like Warp and Cmux replace the terminal entirely, requiring adoption of their keybindings and configuration. Herdr runs inside the terminal you already use, preserving existing fonts, color schemes, shell configuration, and muscle memory.

Installation

On macOS or Linux with Homebrew:

brew install herdr

On Linux via install script:

curl -fsSL https://herdr.dev/install.sh | sh

On NixOS via flake:

nix run github:ogulcantuna/herdr

Launch with:

herdr

Interface and navigation

The interface has four areas:

• Spaces sidebar (left): workspaces, each representing a project context
• Agents list (bottom left): detected AI agent processes with status
• Main pane (center/right): one or more terminal panes
• Navigator (bottom): keyboard shortcut hints

The default prefix key is Ctrl+b (same as tmux). Key commands:

• Ctrl+b then Shift+n: new workspace
• Ctrl+b then ?: full keybinding reference

Panes can be split by right-clicking and selecting "Split vertical" or via keyboard. Mouse support is available for resizing, focusing, and context menus.

Agent state tracking

When AI agents are started in Herdr panes, they appear in the agents sidebar with real-time status:

• blocked: waiting for user input (for example, a first-run permission prompt)
• idle: ready to accept a prompt
• working: processing a task

Sending a prompt to an agent immediately updates its status in the sidebar, confirming the task was received. This provides unambiguous state awareness across multiple concurrent agents without switching panes to check.

Agent-driven orchestration via the Herdr CLI

The Herdr CLI is available while the TUI is running. External processes (including agents) can execute herdr commands to create panes, run processes, and read pane output programmatically.

Available operations include herdr pane split-right, herdr agent read, and herdr pane close.

A practical example: give an agent the task of performing a security audit. The agent can use the Herdr CLI to create two panes, run a secrets scanner in one and a dependency checker in the other, wait for both to complete, read their output, produce a summary report, and close the temporary panes. This turns a single high-level prompt into a multi-step workflow that self-orchestrates within the terminal.

Remote development via SSH

Herdr uses a client-server architecture. The server process manages sessions, workspaces, and panes. The client is a thin process in the terminal window that captures input and renders output. Locally, they communicate over a Unix socket.

The --remote flag starts the server on a remote machine and the client locally, forwarding communication through the SSH tunnel:

herdr --remote ssh://user@your-remote-server

The server runs on the remote machine (with access to remote files and compute). The client runs locally and reads the local ~/.config/herdr/config.toml. All local keybindings, themes, and settings apply to the remote session. This provides a unified experience regardless of where the server runs.

Configuration

The configuration file is at ~/.config/herdr/config.toml. Reload in a running session with prefix + Shift+r.

Prefix key

[keys]
prefix = "ctrl+space"

Theme

Built-in themes include Catppuccin, Gruvbox, Nord, and Dracula. The settings menu is available at prefix + s.

[theme]
name = "catppuccin"

Notifications

Herdr can emit a sound or system notification when an agent changes state in a background pane, useful for long-running tasks.

Final thoughts

Herdr's most practically useful feature is agent state tracking. Without it, managing multiple concurrent AI agents requires switching between panes to verify each agent's state. The sidebar view provides that at a glance.

The agent-driven orchestration through the Herdr CLI is the more experimental feature, but it enables workflows that are difficult to replicate otherwise: an agent that creates its own workspace structure, executes tools, reads results, and cleans up, all from a single initial prompt.

The SSH --remote flag is a clean solution to the common problem of remote development environments losing local tool configuration. Running the client locally ensures the session feels local regardless of where the compute is.

Documentation and installation instructions are at herdr.dev.

Got an article suggestion? Let us know

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.