# herdrdev/herdr architecture

> Architecture diagram of the GitHub repository herdrdev/herdr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/herdrdev/herdr
- Repository: https://github.com/herdrdev/herdr

## Overview

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: [`src/server/mod.rs`](https://github.com/herdrdev/herdr/blob/master/src/server/mod.rs) (Background server), [`src/client/mod.rs`](https://github.com/herdrdev/herdr/blob/master/src/client/mod.rs) (Terminal client), [`src/app/mod.rs`](https://github.com/herdrdev/herdr/blob/master/src/app/mod.rs) (App orchestration), [`src/pane.rs`](https://github.com/herdrdev/herdr/blob/master/src/pane.rs) (Terminal panes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Client interaction"]
  node_cli["CLI commands<br/>[cli.rs]"]
  node_client["Terminal client<br/>[mod.rs]"]
  node_ui["Interactive UI<br/>[ui.rs]"]
  node_key_input["Input handling<br/>[mod.rs]"]
  node_api["Socket API<br/>[server.rs]"]
  node_api_schema["API contract<br/>[schema.rs]"]
end

subgraph group_runtime["Session runtime"]
  node_app["App orchestration<br/>[mod.rs]"]
  node_server["Background server<br/>[mod.rs]"]
  node_pane["Terminal panes<br/>[pane.rs]"]
  node_pty["PTY processes<br/>[actor.rs]"]
  node_protocol["Client protocol<br/>[wire.rs]"]
  node_graphics["Terminal graphics<br/>[kitty_graphics.rs]"]
end

subgraph group_agent["Agent capabilities"]
  node_agent_detection["Agent detection<br/>[mod.rs]"]
  node_manifest["Agent manifests<br/>[manifest.rs]"]
  node_integrations["Agent integrations<br/>[mod.rs]"]
  node_plugins["Plugins<br/>[runtime.rs]"]
end

subgraph group_workspace["Workspace features"]
  node_workspace["Workspaces and tabs<br/>[workspace.rs]"]
  node_worktree["Git worktrees<br/>[worktree.rs]"]
  node_layout["Pane layout<br/>[layout.rs]"]
  node_config["Configuration<br/>[config.rs]"]
end

subgraph group_connectivity["Connectivity and persistence"]
  node_session["Session state<br/>[session.rs]"]
  node_persist["Session persistence<br/>[persist.rs]"]
  node_remote["Remote attach<br/>[attach.rs]"]
end

node_user(("User"))
node_agent_actor(("Coding agent"))
node_terminal(("Host terminal"))
node_ssh_machine(("SSH machine"))

node_user -->|"uses"| node_terminal
node_terminal -->|"starts"| node_client
node_client -->|"attaches to"| node_server
node_user -->|"runs commands"| node_cli
node_cli -.->|"controls"| node_api
node_agent_actor -->|"issues commands"| node_api
node_api -->|"implements"| node_api_schema
node_api -->|"dispatches requests"| node_app
node_client -->|"exchanges messages"| node_protocol
node_server -->|"exchanges messages"| node_protocol
node_server -->|"hosts"| node_app
node_app -->|"renders"| node_ui
node_user -->|"provides input"| node_key_input
node_key_input -->|"routes input"| node_client
node_server -.->|"manages panes"| node_pane
node_pane -->|"owns processes"| node_pty
node_pane -->|"checks agent state"| node_agent_detection
node_agent_detection -->|"uses manifest"| node_manifest
node_agent_detection -.->|"supports hooks"| node_integrations
node_agent_actor -->|"extends workflows"| node_plugins
node_app -->|"provides plugin runtime"| node_plugins
node_app -->|"manages workspaces"| node_workspace
node_workspace -->|"supports worktrees"| node_worktree
node_workspace -->|"arranges panes"| node_layout
node_config -->|"configures"| node_client
node_server -->|"serves named sessions"| node_session
node_server -->|"saves layout"| node_persist
node_persist -->|"restores layout"| node_server
node_user -->|"attaches remotely"| node_remote
node_remote -->|"connects to"| node_ssh_machine
node_remote -->|"reconnects endpoint"| node_client
node_pane -->|"renders images"| node_graphics
node_server -->|"streams graphics"| node_graphics

click node_cli "https://github.com/herdrdev/herdr/blob/master/src/cli.rs"
click node_client "https://github.com/herdrdev/herdr/blob/master/src/client/mod.rs"
click node_ui "https://github.com/herdrdev/herdr/blob/master/src/ui.rs"
click node_key_input "https://github.com/herdrdev/herdr/blob/master/src/input/mod.rs"
click node_api "https://github.com/herdrdev/herdr/blob/master/src/api/server.rs"
click node_api_schema "https://github.com/herdrdev/herdr/blob/master/src/api/schema.rs"
click node_app "https://github.com/herdrdev/herdr/blob/master/src/app/mod.rs"
click node_server "https://github.com/herdrdev/herdr/blob/master/src/server/mod.rs"
click node_pane "https://github.com/herdrdev/herdr/blob/master/src/pane.rs"
click node_pty "https://github.com/herdrdev/herdr/blob/master/src/pty/actor.rs"
click node_protocol "https://github.com/herdrdev/herdr/blob/master/src/protocol/wire.rs"
click node_agent_detection "https://github.com/herdrdev/herdr/blob/master/src/detect/mod.rs"
click node_manifest "https://github.com/herdrdev/herdr/blob/master/src/detect/manifest.rs"
click node_integrations "https://github.com/herdrdev/herdr/blob/master/src/integration/mod.rs"
click node_plugins "https://github.com/herdrdev/herdr/blob/master/src/app/api/plugins/runtime.rs"
click node_workspace "https://github.com/herdrdev/herdr/blob/master/src/workspace.rs"
click node_worktree "https://github.com/herdrdev/herdr/blob/master/src/worktree.rs"
click node_layout "https://github.com/herdrdev/herdr/blob/master/src/layout.rs"
click node_config "https://github.com/herdrdev/herdr/blob/master/src/config.rs"
click node_session "https://github.com/herdrdev/herdr/blob/master/src/session.rs"
click node_persist "https://github.com/herdrdev/herdr/blob/master/src/persist.rs"
click node_remote "https://github.com/herdrdev/herdr/blob/master/src/remote/attach.rs"
click node_graphics "https://github.com/herdrdev/herdr/blob/master/src/kitty_graphics.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_client,node_ui,node_key_input,node_api,node_api_schema,node_user toneBlue
class node_app,node_server,node_pane,node_pty,node_protocol,node_graphics toneAmber
class node_agent_detection,node_manifest,node_integrations,node_plugins toneMint
class node_workspace,node_worktree,node_layout,node_config toneRose
class node_session,node_persist,node_remote,node_agent_actor,node_terminal,node_ssh_machine toneIndigo
```

## Components

### Client interaction

- [CLI commands](https://github.com/herdrdev/herdr/blob/master/src/cli.rs): `src/cli.rs`
- [Terminal client](https://github.com/herdrdev/herdr/blob/master/src/client/mod.rs): `src/client/mod.rs`
- [Interactive UI](https://github.com/herdrdev/herdr/blob/master/src/ui.rs): `src/ui.rs`
- [Input handling](https://github.com/herdrdev/herdr/blob/master/src/input/mod.rs): `src/input/mod.rs`
- [Socket API](https://github.com/herdrdev/herdr/blob/master/src/api/server.rs): `src/api/server.rs`
- [API contract](https://github.com/herdrdev/herdr/blob/master/src/api/schema.rs): `src/api/schema.rs`

### Session runtime

- [App orchestration](https://github.com/herdrdev/herdr/blob/master/src/app/mod.rs): `src/app/mod.rs`
- [Background server](https://github.com/herdrdev/herdr/blob/master/src/server/mod.rs): `src/server/mod.rs`
- [Terminal panes](https://github.com/herdrdev/herdr/blob/master/src/pane.rs): `src/pane.rs`
- [PTY processes](https://github.com/herdrdev/herdr/blob/master/src/pty/actor.rs): `src/pty/actor.rs`
- [Client protocol](https://github.com/herdrdev/herdr/blob/master/src/protocol/wire.rs): `src/protocol/wire.rs`
- [Terminal graphics](https://github.com/herdrdev/herdr/blob/master/src/kitty_graphics.rs): `src/kitty_graphics.rs`

### Agent capabilities

- [Agent detection](https://github.com/herdrdev/herdr/blob/master/src/detect/mod.rs): `src/detect/mod.rs`
- [Agent manifests](https://github.com/herdrdev/herdr/blob/master/src/detect/manifest.rs): `src/detect/manifest.rs`
- [Agent integrations](https://github.com/herdrdev/herdr/blob/master/src/integration/mod.rs): `src/integration/mod.rs`
- [Plugins](https://github.com/herdrdev/herdr/blob/master/src/app/api/plugins/runtime.rs): `src/app/api/plugins/runtime.rs`

### Workspace features

- [Workspaces and tabs](https://github.com/herdrdev/herdr/blob/master/src/workspace.rs): `src/workspace.rs`
- [Git worktrees](https://github.com/herdrdev/herdr/blob/master/src/worktree.rs): `src/worktree.rs`
- [Pane layout](https://github.com/herdrdev/herdr/blob/master/src/layout.rs): `src/layout.rs`
- [Configuration](https://github.com/herdrdev/herdr/blob/master/src/config.rs): `src/config.rs`

### Connectivity and persistence

- [Session state](https://github.com/herdrdev/herdr/blob/master/src/session.rs): `src/session.rs`
- [Session persistence](https://github.com/herdrdev/herdr/blob/master/src/persist.rs): `src/persist.rs`
- [Remote attach](https://github.com/herdrdev/herdr/blob/master/src/remote/attach.rs): `src/remote/attach.rs`

### Other components

- **User**
- **Coding agent**
- **Host terminal**
- **SSH machine**

## Connections

- User → Host terminal: uses (evidence: `README.md`)
- Host terminal → Terminal client: starts (evidence: `README.md`)
- Terminal client → Background server: attaches to (evidence: `README.md`)
- User → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Socket API: controls
- Coding agent → Socket API: issues commands (evidence: `README.md`)
- Socket API → API contract: implements (evidence: `src/api/server.rs`)
- Socket API → App orchestration: dispatches requests (evidence: `src/api/server.rs`)
- Terminal client → Client protocol: exchanges messages (evidence: `src/client/mod.rs`)
- Background server → Client protocol: exchanges messages
- Background server → App orchestration: hosts
- App orchestration → Interactive UI: renders (evidence: `src/server/client_shell.rs`)
- User → Input handling: provides input (evidence: `README.md`)
- Input handling → Terminal client: routes input (evidence: `src/client/mod.rs`)
- Background server → Terminal panes: manages panes
- Terminal panes → PTY processes: owns processes (evidence: `src/pane.rs`)
- Terminal panes → Agent detection: checks agent state (evidence: `src/pane.rs`)
- Agent detection → Agent manifests: uses manifest (evidence: `src/detect/mod.rs`)
- Agent detection → Agent integrations: supports hooks
- Coding agent → Plugins: extends workflows (evidence: `README.md`)
- App orchestration → Plugins: provides plugin runtime (evidence: `src/app/mod.rs`)
- App orchestration → Workspaces and tabs: manages workspaces (evidence: `src/app/mod.rs`)
- Workspaces and tabs → Git worktrees: supports worktrees
- Workspaces and tabs → Pane layout: arranges panes (evidence: `src/app/mod.rs`)
- Configuration → Terminal client: configures (evidence: `src/client/mod.rs`)
- Background server → Session state: serves named sessions (evidence: `README.md`)
- Background server → Session persistence: saves layout (evidence: `README.md`)
- Session persistence → Background server: restores layout (evidence: `README.md`)
- User → Remote attach: attaches remotely (evidence: `README.md`)
- Remote attach → SSH machine: connects to (evidence: `README.md`)
- Remote attach → Terminal client: reconnects endpoint (evidence: `src/remote/attach.rs`)
- Terminal panes → Terminal graphics: renders images (evidence: `src/pane/terminal.rs`)
- Background server → Terminal graphics: streams graphics