Herdr is an open-source, agent-native background server designed to provide a persistent runtime environment for AI coding agents. Unlike traditional terminal multiplexers, Herdr functions as a persistent infrastructure that decouples agent execution from the host machine's terminal interface, allowing sessions to persist across network drops, machine restarts, or lid closures.

Core Architecture and Methodology

The system operates as a background server that manages terminal sessions, providing a unified interface for various AI agents (e.g., Claude Code, Cursor, Codex, Grok). Its architectural methodology centers on the following pillars:

• Agent-Native API: Rather than wrapping existing tools, Herdr acts as a host that exposes a socket API and a CLI, enabling agents to programmatically drive the environment. Agents can spawn terminal panes, prompt for human intervention, and monitor the state of execution.
• Persistent Execution State: The system categorizes terminal panes into three distinct states—working, blocked, or idle. This state management ensures that when an agent hits an execution barrier or requires authorization, it can pause and signal the user, preventing "lost" processes.
• Infrastructure Decoupling: By abstracting the terminal away from the agent's lifetime, Herdr ensures that long-running tasks remain active even when the primary client disconnects. Users can reattach to these sessions from any local terminal or via SSH, restoring the exact state of the agent's environment.
• Platform-Agnostic Implementation: Built primarily in Rust, Herdr avoids electron-based overhead. It provides a lightweight binary that is compatible with existing terminal workflows, supporting both keyboard-centric (tmux-style prefix keys) and mouse-driven interactions.

Technical Implementation

The system is managed through a justfile for build automation and utilizes a Rust-based toolchain (rust-toolchain.toml). The runtime integrates with the operating system at a low level to manage process spawning and socket-based inter-process communication (IPC).

The state management model can be abstracted as:
$$S_{pane} \in \{W, B, I\}$$
Where $S_{pane}$ denotes the state of a terminal pane, representing $W$ (working), $B$ (blocked), or $I$ (idle). The API allows for the transition function $f(A, E) \rightarrow S_{pane}$, where $A$ represents the Agent's instructions and $E$ represents the current execution environment, allowing for deterministic control over how agents interact with the underlying shell sessions.

Extensibility and Integration

Herdr supports a plugin architecture, allowing users to extend the functionality of panes and workflows via an integrated marketplace. The project is designed to be interoperable with existing CLI tools, acting as a substrate that "owns" the terminals while allowing the agents to execute their own logic natively. The project adheres to the Apache License 2.0 and maintains a strict development workflow governed by AGENTS.md and CONTRIBUTING.md to ensure architectural integrity during agent-assisted development.