# Herdr

> A terminal-native agent runtime and multiplexer that adds tmux-style persistence, mouse-native panes, semantic agent state, and a socket API to your existing terminal setup.

Herdr is a terminal-native agent runtime built in Rust that runs inside your existing terminal emulator. It adds persistent sessions, mouse-native panes, workspace organization, and a CLI/socket API that agents can use to orchestrate their own environment — without replacing your shell, SSH setup, fonts, or keybindings. The project is dual-licensed under AGPL-3.0 and a commercial license, with source code publicly available on GitHub.

## What It Is

Herdr sits between tmux-style terminal multiplexers and desktop agent dashboards. It is a lightweight TUI process that runs real PTY sessions, tracks agent state (blocked, working, done, idle), and exposes a newline-delimited JSON socket API so agents can create panes, run commands, read output, and wait for state changes without human intervention. The homepage describes it as "tmux persistence, agent awareness, no terminal replacement."

## How the Agent Awareness Layer Works

The sidebar shows each agent's current state rolled up per workspace, so the full session is scannable at a glance:

- 🔴 **Blocked** — agent needs input or approval
- 🟡 **Working** — agent is actively running
- 🔵 **Done** — work finished, not yet reviewed
- 🟢 **Idle** — done and seen

Detection works via process name matching and terminal output heuristics with zero configuration. Official socket API integrations are available for pi, Claude Code, Codex, OpenCode, Hermes, and qodercli, which provide more reliable state reporting and native agent session restore after a server restart.

## Supported Agents and Integrations

Herdr ships with automatic detection for a broad set of terminal agents. The GitHub README lists full idle/done/working/blocked detection for Claude Code, Codex, Amp, Droid, OpenCode, Grok CLI, Hermes, Cursor agent, Antigravity CLI, Kimi Code CLI, GitHub Copilot CLI, qodercli, and kiro CLI. Any terminal agent works as a basic multiplexer target; custom integrations can report agent labels over the socket API.

## Deployment and Setup Path

Herdr ships as a single Rust binary with no Electron dependency and no hosted control plane. Installation options include:

- `curl -fsSL https://herdr.dev/install.sh | sh`
- `brew install herdr` (Homebrew)
- Nix flake
- Direct binary download from GitHub Releases

It runs locally, inside any SSH session, or as a thin client pointing at a remote host via `herdr --remote workbox`. The session server persists pane processes after client detach, and the TUI adapts to narrow screens for SSH use from mobile devices.

## Architecture Tradeoffs vs. tmux and GUI Managers

The GitHub README positions Herdr against three categories: tmux/Zellij (persistent sessions, no agent awareness), GUI agent managers (agent state, but leave the terminal), and worktree orchestrators (workflow-owned). Herdr's stated differentiator is combining persistent PTY sessions, mouse-native layout, semantic agent state, and an agent-callable API in a single binary that stays inside the terminal. It works inside tmux if needed.

## Update: v0.6.6

The latest release is v0.6.6, published on 2026-05-31, according to the GitHub repository. The project was created in March 2026 and has seen rapid iteration, with the repository showing 3,494 stars and 226 forks as of early June 2026. The `herdr update` command handles in-place binary updates; an experimental `--handoff` flag attempts live pane migration from old to new server versions without stopping foreground processes.

## Features
- Persistent PTY sessions that survive client detach
- Mouse-native panes, tabs, and workspaces
- Semantic agent state: blocked, working, done, idle
- Workspace rollups showing most urgent agent state
- CLI and newline-delimited JSON socket API for agent orchestration
- Remote SSH attach via herdr --remote
- Direct agent attach to server-owned terminals
- 18 built-in themes including Catppuccin, Tokyo Night, Gruvbox, and more
- Keyboard copy mode with vim-style navigation
- Session restore after full server restart with opt-in screen history replay
- Native agent session resume for supported integrations
- Experimental live pane handoff during updates
- Responsive TUI for narrow screens and mobile SSH
- Named sessions as separate server namespaces
- Configurable keybindings, notifications, and scrollback

## Integrations
Pi, Claude Code, OpenAI Codex, Droid (Factory AI), Amp, OpenCode, Grok CLI, Hermes Agent, Cursor, Antigravity CLI, Kimi Code CLI, GitHub Copilot CLI, qodercli, Kiro CLI, Homebrew, Nix

## Platforms
MACOS, LINUX, IOS, WEB, API, JETBRAINS_PLUGIN, CLI

## Pricing
Open Source, Free tier available

## Version
v0.6.6

## Links
- Website: https://herdr.dev
- Documentation: https://herdr.dev/docs
- Repository: https://github.com/ogulcancelik/herdr
- EveryDev.ai: https://www.everydev.ai/tools/herdr