How herdrdev/herdr works
Herdr is a terminal-based runtime for coding-agent sessions: a client attaches to a background server, which owns terminal panes and presents their state and layout. Users interact through the terminal UI or CLI/socket API; agents can also issue API commands. The graph preserves the documented branches for session recovery, remote machines, agent detection, plugins, integrations, and workspace/worktree management. Source excerpts are partial, so links for unsampled internals are included only where the README or SOURCE INDEX supports them.
Main entry points: server/mod.rs Background server · client/mod.rs Terminal client · app/mod.rs App orchestration · pane.rs Terminal panes
Components 27
Client interaction
- CLI commands
src/cli.rs - Terminal client
src/client/mod.rs - Interactive UI
src/ui.rs - Input handling
src/input/mod.rs - Socket API
src/api/server.rs - API contract
src/api/schema.rs
Session runtime
- App orchestration
src/app/mod.rs - Background server
src/server/mod.rs - Terminal panes
src/pane.rs - PTY processes
src/pty/actor.rs - Client protocol
src/protocol/wire.rs - Terminal graphics
src/kitty_graphics.rs
Agent capabilities
- Agent detection
src/detect/mod.rs - Agent manifests
src/detect/manifest.rs - Agent integrations
src/integration/mod.rs - Plugins
src/app/api/plugins/runtime.rs
Workspace features
- Workspaces and tabs
src/workspace.rs - Git worktrees
src/worktree.rs - Pane layout
src/layout.rs - Configuration
src/config.rs
Connectivity and persistence
- Session state
src/session.rs - Session persistence
src/persist.rs - Remote attach
src/remote/attach.rs
Other components
- User
- Coding agent
- Host terminal
- SSH machine
Connections 33
- User → Host terminal: uses
README.md - Host terminal → Terminal client: starts
README.md - Terminal client → Background server: attaches to
README.md - User → CLI commands: runs commands
README.md - CLI commands → Socket API: controls
- Coding agent → Socket API: issues commands
README.md - Socket API → API contract: implements
src/api/server.rs - Socket API → App orchestration: dispatches requests
src/api/server.rs - Terminal client → Client protocol: exchanges messages
src/client/mod.rs - Background server → Client protocol: exchanges messages
- Background server → App orchestration: hosts
- App orchestration → Interactive UI: renders
src/server/client_shell.rs - User → Input handling: provides input
README.md - Input handling → Terminal client: routes input
src/client/mod.rs - Background server → Terminal panes: manages panes
- Terminal panes → PTY processes: owns processes
src/pane.rs - Terminal panes → Agent detection: checks agent state
src/pane.rs - Agent detection → Agent manifests: uses manifest
src/detect/mod.rs - Agent detection → Agent integrations: supports hooks
- Coding agent → Plugins: extends workflows
README.md - App orchestration → Plugins: provides plugin runtime
src/app/mod.rs - App orchestration → Workspaces and tabs: manages workspaces
src/app/mod.rs - Workspaces and tabs → Git worktrees: supports worktrees
- Workspaces and tabs → Pane layout: arranges panes
src/app/mod.rs - Configuration → Terminal client: configures
src/client/mod.rs - Background server → Session state: serves named sessions
README.md - Background server → Session persistence: saves layout
README.md - Session persistence → Background server: restores layout
README.md - User → Remote attach: attaches remotely
README.md - Remote attach → SSH machine: connects to
README.md - Remote attach → Terminal client: reconnects endpoint
src/remote/attach.rs - Terminal panes → Terminal graphics: renders images
src/pane/terminal.rs - Background server → Terminal graphics: streams graphics