Noureddine RAMDI / herdr: a terminal-native AI agent multiplexer with session persistence and agent state awareness

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1010 Words
github-stars rust terminal tmux ai-agent multiplexer cli

ogulcancelik/herdr

herdr is not your typical terminal multiplexer. It builds on the familiar tmux-style sessions, panes, and tabs but adds a layer of AI agent awareness that sets it apart. Without any configuration, it detects the state of AI agents running inside your terminal—whether they’re blocked, working, done, or idle—by reading foreground process names and analyzing terminal output heuristics. This means you get real-time insight into what your agents are doing, right in the sidebar of your terminal UI.

What herdr does and how it works

At its core, herdr is a terminal-native agent multiplexer written in Rust. It provides persistent workspaces, tabs, and panes with full mouse support, all running as a single binary with no external dependencies. This zero-dependency design keeps the footprint minimal and the user experience snappy.

The architecture combines session persistence similar to tmux with AI agent state detection baked in. Sessions persist independently of client connections, allowing you to detach with ctrl+b q and have your agents keep running in the background. herdr supports remote access over SSH, making it practical for distributed workflows.

A standout feature is the sidebar, which automatically detects agent states by inspecting the foreground process names and terminal output heuristics. No user configuration is required here, making it seamless to monitor multiple agents across different panes and workspaces. The sidebar shows distinct states such as blocked, working, done, and idle, providing an at-a-glance understanding of your agents’ progress.

herdr also exposes a Unix socket API that agents themselves can use programmatically. This API allows agents to create workspaces, split panes, spawn helper processes, read terminal output, and wait for state changes. This level of integration enables complex agent-to-agent orchestration workflows directly from the terminal environment.

The project supports several popular AI agents out of the box, including Claude Code, Codex, OpenCode, and Pi. It offers direct integrations for deeper semantic state reporting, enhancing the default heuristic-based detection.

Technical strengths and design tradeoffs

herdr’s implementation in Rust brings memory safety and performance benefits, which are critical in terminal multiplexers that handle multiple concurrent processes and UI updates.

The single-binary, zero-dependency design is a clear strength. It means you don’t have to wrestle with Electron-based GUIs or heavy runtimes. This keeps the tool lightweight and focused on terminal-native workflows. The tradeoff here is platform support: herdr currently targets Linux and macOS, which covers most developer environments but leaves Windows users out.

The agent state detection is both clever and opinionated. By reading foreground process names and applying heuristics to terminal output, herdr can infer states without any configuration. This approach simplifies user setup but might miss edge cases or require tuning for custom or less common agents.

The Unix socket API for agent orchestration is a powerful extension point. It enables automation and inter-agent communication that goes beyond what typical terminal multiplexers offer. However, this also means users need some scripting or programming ability to fully exploit these capabilities.

The codebase, as seen in the repository, is modular with clear separation between UI rendering, session management, and agent detection logic. This separation improves maintainability and makes it easier to extend integrations with new agents.

Quick start

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

or download the binary from releases. requires linux or macos.

update

herdr notifies you when a new version is available. run manually to update:

herdr update

quick start

herdr

By default herdr launches or attaches to one background session server. ctrl+b q detaches the client. Agents keep running. Use herdr server stop to stop the default server. Use --no-session for the old single-process mode.

Named sessions are runtime/socket namespaces for separate persistent herdr servers. They do not replace workspaces; each named session has its own panes, tabs, workspaces, sockets, and session state while sharing the same global config file.

herdr session list
herdr session attach work
herdr session attach side-project
herdr session stop work
herdr session delete side-project
  1. Press ctrl+b, then shift+n to create a workspace.
  2. Run an agent in the root pane.
  3. Press ctrl+b, then w to open workspace navigation.
  4. Use ctrl+b, then v or minus to split panes, or ctrl+b, then c to create a new tab.
  5. Watch the sidebar for blocked, working, and done states.

On first run, herdr opens a short onboarding flow. After that, restored sessions land in terminal mode; fresh sessions start in navigate mode.

verdict

herdr is a niche but practical tool for developers who regularly work with multiple AI agents in terminal multiplexers. Its zero-configuration agent state detection and session persistence make monitoring and orchestrating agents more manageable without leaving the terminal.

The single binary and zero-dependency approach make it attractive for those who want a lightweight, Rust-native alternative to tmux with AI awareness. However, its Linux and macOS limitation and the learning curve for using the Unix socket API might restrict adoption.

If you manage AI agents via CLI and want at-a-glance visibility of their status combined with persistent sessions, herdr is worth exploring. It’s less about replacing tmux and more about extending terminal multiplexers with AI agent intelligence and orchestration capabilities.

→ GitHub Repo: ogulcancelik/herdr ⭐ 1,993 · Rust