How ogulcancelik/herdr works
Purpose and entry points
Herdr is a Rust terminal-native multiplexer for coding agents: it manages real PTY-backed panes, tracks agent state, persists detachable sessions, and exposes a socket API for automation. The executable starts in src/main.rs, parses commands in src/cli.rs, and routes interactive client/server runtime modes through src/client/mod.rs and src/server/mod.rs.
Runtime topology
A local server owns session state, terminals, PTYs, persistence, and API subscriptions; one or more clients attach to render and control that state. Server discovery/connection uses socket paths and client transport, while headless operation supports remote or noninteractive control. Core boundaries: src/server/socket_paths.rs, src/server/client_transport.rs, src/server/headless.rs.
Application state and workspace model
The app layer coordinates mutable session state: workspaces contain tabs, layouts, panes, terminal targets, and worktrees. Actions from UI, CLI, API, or server events converge here rather than directly mutating terminal processes. Key orchestration paths are src/app/state.rs, src/app/actions.rs, and src/app/session.rs; workspace/Git aggregation lives in src/workspace.rs, src/workspace/aggregate.rs, and src/workspace/git/mod.rs.
Terminal and PTY pipeline
Pane creation attaches a shell or agent process to a PTY actor. Terminal output is interpreted into terminal state, pane metadata, title/state changes, graphics, and agent-detection signals; input travels in the reverse direction through key/mouse encoding to the PTY. Primary components: src/pty/actor.rs, src/pane/terminal.rs, src/terminal/runtime.rs. The project vendors or binds Ghostty terminal functionality through src/ghostty/mod.rs and src/ghostty/bindings.rs.
Interactive client and rendering
The interactive client collects raw terminal input, applies configured keybindings and UI navigation, then renders panes, tabs, sidebars, overlays, and status into the host terminal. This is a terminal UI, not a web application. Important paths: src/client/input.rs, src/app/input/mod.rs, src/ui.rs; visual terminal protocols include src/kitty_graphics.rs and src/protocol/render_ansi.rs.
Agent lifecycle, detection, and integrations
Herdr identifies supported agents from terminal behavior/manifests, presents their working/blocked/done state, and installs or executes integration hooks that report state. Detection definitions are data-driven TOML manifests; integrations contain agent-specific assets and configuration edits. Boundaries: src/pane/agent_detection.rs, src/detect/manifest.rs, src/integration/registry.rs. Agent resume/handoff logic is separated in src/agent_resume.rs and src/handoff_runtime.rs.
Automation API and plugins
A versioned socket API offers control over agents, sessions, panes, tabs, workspaces, worktrees, integrations, and plugins. API schemas define the external contract; event hubs/subscriptions support asynchronous observation and waiting. Relevant paths: src/api/server.rs, src/api/schema.rs, src/api/event_hub.rs. Plugins execute through app-side plugin runtime/context boundaries in src/app/api/plugins/runtime.rs and src/app/api/plugins/context.rs; a separate Cloudflare Worker backs the marketplace at workers/plugin-marketplace/src/index.ts.
Durability and platforms
Session snapshots, restoration, and plugin registry persistence allow detach/reattach and restart recovery. Platform adapters isolate Linux, macOS, and Windows behavior, including PTY differences. Paths: src/persist/snapshot.rs, src/persist/restore.rs, src/platform/mod.rs. The main runtime is one Rust binary; build/release support includes Cargo, Nix (flake.nix), and GitHub Actions (.github/workflows/release.yml).
Main entry points: state.rs Session state · server/mod.rs Local server · runtime.rs Terminal runtime · client/mod.rs Interactive client
Components 21
Runtime
- Herdr binary
src/main.rs - CLI commands
src/cli.rs - Local server · Owns sessions, terminals, PTYs, persistence, and subscriptions.
src/server/mod.rs - Socket transport · Socket paths, client transport, and headless control.
src/server/client_transport.rs - Interactive client
src/client/mod.rs - Raw client input
src/client/input.rs
Application State
- Input & keybindings
src/app/input/mod.rs - App actions · UI, CLI, API, and server events converge into state changes.
src/app/actions.rs - Session state · Coordinates workspaces, tabs, layouts, panes, targets, and worktrees.
src/app/state.rs - Workspace & Git
src/workspace/aggregate.rs
Terminal Pipeline
- PTY actor · Attaches shells and agents to pane PTYs.
src/pty/actor.rs - Terminal runtime · Interprets output and encodes input for PTYs.
src/terminal/runtime.rs - Terminal pane · Tracks pane metadata, title, graphics, and state.
src/pane/terminal.rs - Ghostty bindings
src/ghostty/bindings.rs - Terminal UI · Renders panes, tabs, sidebars, overlays, and status.
src/ui.rs
Automation & Agents
- Agent detection · Derives supported-agent lifecycle signals from terminal behavior.
src/pane/agent_detection.rs - Socket API · Control API and asynchronous event subscriptions.
src/api/server.rs - Plugin runtime
src/app/api/plugins/runtime.rs - Plugin marketplace
workers/plugin-marketplace/src/index.ts
Durability & Platform
- Snapshot & restore · Persists detachable sessions and restores them after restart.
src/persist/snapshot.rs - Platform adapters · Isolates Linux, macOS, and Windows PTY behavior.
src/platform/mod.rs
Connections 27
- Herdr binary → CLI commands: parses
- Herdr binary → Local server: starts
- Herdr binary → Interactive client: starts
- CLI commands → App actions: commands
- Interactive client → Socket transport: attaches via
- Socket transport → Local server: connects
- Interactive client → Raw client input: collects
- Raw client input → Input & keybindings: raw input
- Input & keybindings → App actions: maps to
- App actions → Session state: mutates
- Local server → Session state: owns
- Session state → Workspace & Git: contains
- Session state → Terminal pane: manages panes
- Session state → PTY actor: creates processes
- PTY actor → Terminal runtime: output / input
- Terminal runtime → Ghostty bindings: uses
- Terminal runtime → Terminal pane: updates
- Terminal runtime → Agent detection: signals
- Session state → Terminal UI: render state
- Terminal UI → Interactive client: draws to
- Socket API → App actions: control actions
- Local server → Socket API: hosts
- Socket API → Plugin runtime: plugin controls
- Plugin runtime → Session state: app context
- Plugin marketplace → Plugin runtime: publishes plugins
- Local server → Snapshot & restore: snapshots / restores
- Local server → Platform adapters: OS services