# ogulcancelik/herdr architecture

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

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

## Overview

#### 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: [`src/app/state.rs`](https://github.com/ogulcancelik/herdr/blob/master/src/app/state.rs) (Session state), [`src/server/mod.rs`](https://github.com/ogulcancelik/herdr/blob/master/src/server/mod.rs) (Local server), [`src/terminal/runtime.rs`](https://github.com/ogulcancelik/herdr/blob/master/src/terminal/runtime.rs) (Terminal runtime), [`src/client/mod.rs`](https://github.com/ogulcancelik/herdr/blob/master/src/client/mod.rs) (Interactive client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main{{"Herdr binary<br/>Rust entrypoint<br/>[main.rs]"}}
  node_cli["CLI commands<br/>command parser<br/>[cli.rs]"]
  node_server["Local server<br/>session runtime<br/>[mod.rs]"]
  node_transport["Socket transport<br/>client discovery"]
  node_client["Interactive client<br/>terminal client<br/>[mod.rs]"]
  node_client_input["Raw client input<br/>input collector<br/>[input.rs]"]
end

subgraph group_app["Application State"]
  node_app_input["Input &amp; keybindings<br/>action mapper<br/>[mod.rs]"]
  node_actions["App actions<br/>mutation boundary<br/>[actions.rs]"]
  node_state["Session state<br/>state coordinator<br/>[state.rs]"]
  node_workspace["Workspace &amp; Git<br/>workspace aggregate<br/>[aggregate.rs]"]
end

subgraph group_terminal["Terminal Pipeline"]
  node_pty["PTY actor<br/>process host<br/>[actor.rs]"]
  node_terminal_runtime["Terminal runtime<br/>terminal interpreter<br/>[runtime.rs]"]
  node_pane_terminal["Terminal pane<br/>pane model<br/>[terminal.rs]"]
  node_ghostty["Ghostty bindings<br/>terminal backend<br/>[bindings.rs]"]
  node_ui["Terminal UI<br/>renderer<br/>[ui.rs]"]
end

subgraph group_automation["Automation &amp; Agents"]
  node_agent_detection["Agent detection<br/>agent classifier<br/>[agent_detection.rs]"]
  node_api["Socket API<br/>versioned API server<br/>[server.rs]"]
  node_plugins["Plugin runtime<br/>app plugin host<br/>[runtime.rs]"]
  node_marketplace{{"Plugin marketplace<br/>Cloudflare Worker<br/>[index.ts]"}}
end

subgraph group_durability["Durability &amp; Platform"]
  node_persistence[("Snapshot &amp; restore<br/>session durability<br/>[snapshot.rs]")]
  node_platform["Platform adapters<br/>OS abstraction<br/>[mod.rs]"]
end

node_main -->|"parses"| node_cli
node_main -->|"starts"| node_server
node_main -->|"starts"| node_client
node_cli -->|"commands"| node_actions
node_client -->|"attaches via"| node_transport
node_transport -->|"connects"| node_server
node_client -->|"collects"| node_client_input
node_client_input -->|"raw input"| node_app_input
node_app_input -->|"maps to"| node_actions
node_actions -->|"mutates"| node_state
node_server -->|"owns"| node_state
node_state -->|"contains"| node_workspace
node_state -->|"manages panes"| node_pane_terminal
node_state -->|"creates processes"| node_pty
node_pty -->|"output / input"| node_terminal_runtime
node_terminal_runtime -->|"uses"| node_ghostty
node_terminal_runtime -->|"updates"| node_pane_terminal
node_terminal_runtime -->|"signals"| node_agent_detection
node_state -->|"render state"| node_ui
node_ui -->|"draws to"| node_client
node_api -->|"control actions"| node_actions
node_server -->|"hosts"| node_api
node_api -->|"plugin controls"| node_plugins
node_plugins -->|"app context"| node_state
node_marketplace -.->|"publishes plugins"| node_plugins
node_server -->|"snapshots / restores"| node_persistence
node_server -->|"OS services"| node_platform

click node_main "https://github.com/ogulcancelik/herdr/blob/master/src/main.rs"
click node_cli "https://github.com/ogulcancelik/herdr/blob/master/src/cli.rs"
click node_server "https://github.com/ogulcancelik/herdr/blob/master/src/server/mod.rs"
click node_transport "https://github.com/ogulcancelik/herdr/blob/master/src/server/client_transport.rs"
click node_client "https://github.com/ogulcancelik/herdr/blob/master/src/client/mod.rs"
click node_client_input "https://github.com/ogulcancelik/herdr/blob/master/src/client/input.rs"
click node_app_input "https://github.com/ogulcancelik/herdr/blob/master/src/app/input/mod.rs"
click node_actions "https://github.com/ogulcancelik/herdr/blob/master/src/app/actions.rs"
click node_state "https://github.com/ogulcancelik/herdr/blob/master/src/app/state.rs"
click node_workspace "https://github.com/ogulcancelik/herdr/blob/master/src/workspace/aggregate.rs"
click node_pty "https://github.com/ogulcancelik/herdr/blob/master/src/pty/actor.rs"
click node_terminal_runtime "https://github.com/ogulcancelik/herdr/blob/master/src/terminal/runtime.rs"
click node_pane_terminal "https://github.com/ogulcancelik/herdr/blob/master/src/pane/terminal.rs"
click node_ghostty "https://github.com/ogulcancelik/herdr/blob/master/src/ghostty/bindings.rs"
click node_ui "https://github.com/ogulcancelik/herdr/blob/master/src/ui.rs"
click node_agent_detection "https://github.com/ogulcancelik/herdr/blob/master/src/pane/agent_detection.rs"
click node_api "https://github.com/ogulcancelik/herdr/blob/master/src/api/server.rs"
click node_plugins "https://github.com/ogulcancelik/herdr/blob/master/src/app/api/plugins/runtime.rs"
click node_marketplace "https://github.com/ogulcancelik/herdr/blob/master/workers/plugin-marketplace/src/index.ts"
click node_persistence "https://github.com/ogulcancelik/herdr/blob/master/src/persist/snapshot.rs"
click node_platform "https://github.com/ogulcancelik/herdr/blob/master/src/platform/mod.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_main,node_cli,node_server,node_transport,node_client,node_client_input toneBlue
class node_app_input,node_actions,node_state,node_workspace toneAmber
class node_pty,node_terminal_runtime,node_pane_terminal,node_ghostty,node_ui toneMint
class node_agent_detection,node_api,node_plugins,node_marketplace toneRose
class node_persistence,node_platform toneIndigo
```

## Components

### Runtime

- [Herdr binary](https://github.com/ogulcancelik/herdr/blob/master/src/main.rs): Rust entrypoint · `src/main.rs`
- [CLI commands](https://github.com/ogulcancelik/herdr/blob/master/src/cli.rs): command parser · `src/cli.rs`
- [Local server](https://github.com/ogulcancelik/herdr/blob/master/src/server/mod.rs): session runtime · Owns sessions, terminals, PTYs, persistence, and subscriptions. · `src/server/mod.rs`
- [Socket transport](https://github.com/ogulcancelik/herdr/blob/master/src/server/client_transport.rs): client discovery · Socket paths, client transport, and headless control. · `src/server/client_transport.rs`
- [Interactive client](https://github.com/ogulcancelik/herdr/blob/master/src/client/mod.rs): terminal client · `src/client/mod.rs`
- [Raw client input](https://github.com/ogulcancelik/herdr/blob/master/src/client/input.rs): input collector · `src/client/input.rs`

### Application State

- [Input & keybindings](https://github.com/ogulcancelik/herdr/blob/master/src/app/input/mod.rs): action mapper · `src/app/input/mod.rs`
- [App actions](https://github.com/ogulcancelik/herdr/blob/master/src/app/actions.rs): mutation boundary · UI, CLI, API, and server events converge into state changes. · `src/app/actions.rs`
- [Session state](https://github.com/ogulcancelik/herdr/blob/master/src/app/state.rs): state coordinator · Coordinates workspaces, tabs, layouts, panes, targets, and worktrees. · `src/app/state.rs`
- [Workspace & Git](https://github.com/ogulcancelik/herdr/blob/master/src/workspace/aggregate.rs): workspace aggregate · `src/workspace/aggregate.rs`

### Terminal Pipeline

- [PTY actor](https://github.com/ogulcancelik/herdr/blob/master/src/pty/actor.rs): process host · Attaches shells and agents to pane PTYs. · `src/pty/actor.rs`
- [Terminal runtime](https://github.com/ogulcancelik/herdr/blob/master/src/terminal/runtime.rs): terminal interpreter · Interprets output and encodes input for PTYs. · `src/terminal/runtime.rs`
- [Terminal pane](https://github.com/ogulcancelik/herdr/blob/master/src/pane/terminal.rs): pane model · Tracks pane metadata, title, graphics, and state. · `src/pane/terminal.rs`
- [Ghostty bindings](https://github.com/ogulcancelik/herdr/blob/master/src/ghostty/bindings.rs): terminal backend · `src/ghostty/bindings.rs`
- [Terminal UI](https://github.com/ogulcancelik/herdr/blob/master/src/ui.rs): renderer · Renders panes, tabs, sidebars, overlays, and status. · `src/ui.rs`

### Automation & Agents

- [Agent detection](https://github.com/ogulcancelik/herdr/blob/master/src/pane/agent_detection.rs): agent classifier · Derives supported-agent lifecycle signals from terminal behavior. · `src/pane/agent_detection.rs`
- [Socket API](https://github.com/ogulcancelik/herdr/blob/master/src/api/server.rs): versioned API server · Control API and asynchronous event subscriptions. · `src/api/server.rs`
- [Plugin runtime](https://github.com/ogulcancelik/herdr/blob/master/src/app/api/plugins/runtime.rs): app plugin host · `src/app/api/plugins/runtime.rs`
- [Plugin marketplace](https://github.com/ogulcancelik/herdr/blob/master/workers/plugin-marketplace/src/index.ts): Cloudflare Worker · `workers/plugin-marketplace/src/index.ts`

### Durability & Platform

- [Snapshot & restore](https://github.com/ogulcancelik/herdr/blob/master/src/persist/snapshot.rs): session durability · Persists detachable sessions and restores them after restart. · `src/persist/snapshot.rs`
- [Platform adapters](https://github.com/ogulcancelik/herdr/blob/master/src/platform/mod.rs): OS abstraction · Isolates Linux, macOS, and Windows PTY behavior. · `src/platform/mod.rs`

## Connections

- 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
