# Herdr: Terminal Multiplexer with Built-in AI Agent State Awareness [Herdr](https://herdr.dev/) 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. ![Main Herdr user interface showing the layout with Spaces, Agents, and panes with agent status](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/402ff04c-ef7c-4614-486d-f57aac72ca00/orig =1920x1080) ## 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: ```command brew install herdr ``` On Linux via install script: ```command curl -fsSL https://herdr.dev/install.sh | sh ``` On NixOS via flake: ```command nix run github:ogulcantuna/herdr ``` ![Herdr website showing installation options including Script, Homebrew, and Nix Flake](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/ea6b57fb-b557-4048-d381-dc5a0f79a700/orig =1920x1080) Launch with: ```command 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 ![Agent list showing Claude's status changing from idle to working in real-time](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/9f17c5be-c510-4638-4b77-70605ae03400/lg2x =1920x1080) 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`. ![Claude using the Herdr CLI to create a vertical split and run commands in both panes simultaneously](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/0538aec6-439b-4d1a-b1b3-e8d669e8c500/md2x =1920x1080) 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. ![Diagram showing Herdr's client-server model with the server on the remote machine and the client on the local laptop](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/16b5222a-a857-4869-d1ea-70ea805faa00/orig =1920x1080) The `--remote` flag starts the server on a remote machine and the client locally, forwarding communication through the SSH tunnel: ```command 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 ```toml [keys] prefix = "ctrl+space" ``` ### Theme Built-in themes include Catppuccin, Gruvbox, Nord, and Dracula. The settings menu is available at prefix + `s`. ```toml [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. ![Herdr settings menu showing the toasts tab for configuring notification popups](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/45f6955a-df1d-408a-bd2a-bffb435f3900/md2x =1920x1080) ## 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](https://herdr.dev/).