# cacarico/pastor architecture

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

- Interactive diagram: https://gitdiagram.com/cacarico/pastor
- Repository: https://github.com/cacarico/pastor

## Overview

pastor is a self-hosted coding-agent orchestrator: users submit tasks or configure scheduled jobs, then a head queues work, selects machines, starts agents in herdr terminals, and retains task state and events. Job processing adds connector-produced items and rendered prompts; separate capabilities manage machine flocks, limits, event hooks, and long-running orchestrators. The README documents the overall runtime flow; source-index references support several internal links, but daemon, machine, and dispatch internals were not sampled, so their detailed interactions are not inferred.

Main entry points: [`src/scheduler.rs`](https://github.com/cacarico/pastor/blob/main/src/scheduler.rs) (Job scheduler), [`src/cli.rs`](https://github.com/cacarico/pastor/blob/main/src/cli.rs) (Pastor CLI), [`src/daemon.rs`](https://github.com/cacarico/pastor/blob/main/src/daemon.rs) (Head daemon), [`src/machine.rs`](https://github.com/cacarico/pastor/blob/main/src/machine.rs) (Machine fleet)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interface"]
  node_cli["Pastor CLI<br/>[cli.rs]"]
  node_ipc["Head IPC<br/>[ipc.rs]"]
  node_connector_admin["Connector management<br/>[cli.rs]"]
end

subgraph group_control["Head control"]
  node_daemon["Head daemon<br/>[daemon.rs]"]
  node_flock_config["Flock config<br/>[flock.rs]"]
end

subgraph group_work["Job workflow"]
  node_job_config["Job config<br/>[job.rs]"]
  node_connector_catalog["Connector catalog<br/>[manifest.rs]"]
  node_connector_runtime["Connector runtime<br/>[process.rs]"]
  node_scheduler["Job scheduler<br/>[scheduler.rs]"]
  node_schedule["Schedule rules<br/>[schedule.rs]"]
  node_task["Task lifecycle<br/>[task.rs]"]
  node_orchestrator["Orchestrators<br/>[orchestrator.rs]"]
  node_manifest["Connector manifest<br/>[manifest.rs]"]
end

subgraph group_fleet["Machines and agents"]
  node_machine["Machine fleet<br/>[machine.rs]"]
  node_herdr["Herdr terminal<br/>[transport.rs]"]
  node_ssh["SSH transport<br/>[ssh.rs]"]
end

subgraph group_state["State and events"]
  node_store[("SQLite history<br/>[store.rs]")]
  node_events["Events and hooks<br/>[events.rs]"]
  node_limits["Agent limits<br/>[limit.rs]"]
end

node_developer(("Developer"))
node_external_jobs(("Job sources"))
node_external_agent(("Coding agent"))

node_developer -->|"submits commands"| node_cli
node_external_jobs -.->|"provides work items"| node_connector_runtime
node_cli -->|"sends requests"| node_ipc
node_ipc -->|"routes requests"| node_daemon
node_daemon -.->|"runs scheduling"| node_scheduler
node_daemon -.->|"manages fleet"| node_machine
node_flock_config -->|"configures machines"| node_machine
node_job_config -->|"defines jobs"| node_scheduler
node_scheduler -->|"requests items"| node_connector_runtime
node_connector_catalog -->|"resolves sources"| node_connector_runtime
node_manifest -->|"describes connector"| node_connector_runtime
node_connector_admin -->|"installs connectors"| node_manifest
node_scheduler -->|"uses schedule rules"| node_schedule
node_scheduler -->|"queues tasks"| node_task
node_scheduler -->|"records runs"| node_store
node_task -->|"uses terminal API"| node_herdr
node_machine -.->|"connects to terminals"| node_herdr
node_herdr -->|"uses remote transport"| node_ssh
node_herdr -->|"hosts agent"| node_external_agent
node_daemon -.->|"keeps history"| node_store
node_events -->|"records events"| node_store
node_events -->|"publishes runtime events"| node_daemon
node_events -->|"tracks task changes"| node_task
node_events -.->|"runs event hooks"| node_connector_runtime
node_scheduler -->|"checks capacity"| node_limits
node_cli -->|"manages orchestrators"| node_orchestrator
node_orchestrator -->|"starts agent sessions"| node_machine
node_task -.->|"persists task state"| node_store
node_cli -->|"views fleet status"| node_machine
node_cli -.->|"reads task history"| node_store

click node_cli "https://github.com/cacarico/pastor/blob/main/src/cli.rs"
click node_ipc "https://github.com/cacarico/pastor/blob/main/src/ipc.rs"
click node_daemon "https://github.com/cacarico/pastor/blob/main/src/daemon.rs"
click node_flock_config "https://github.com/cacarico/pastor/blob/main/src/config/flock.rs"
click node_machine "https://github.com/cacarico/pastor/blob/main/src/machine.rs"
click node_herdr "https://github.com/cacarico/pastor/blob/main/src/herdr/transport.rs"
click node_ssh "https://github.com/cacarico/pastor/blob/main/src/ssh.rs"
click node_job_config "https://github.com/cacarico/pastor/blob/main/src/config/job.rs"
click node_connector_catalog "https://github.com/cacarico/pastor/blob/main/src/connector/manifest.rs"
click node_connector_runtime "https://github.com/cacarico/pastor/blob/main/src/connector/process.rs"
click node_scheduler "https://github.com/cacarico/pastor/blob/main/src/scheduler.rs"
click node_schedule "https://github.com/cacarico/pastor/blob/main/src/schedule.rs"
click node_task "https://github.com/cacarico/pastor/blob/main/src/task.rs"
click node_orchestrator "https://github.com/cacarico/pastor/blob/main/src/orchestrator.rs"
click node_store "https://github.com/cacarico/pastor/blob/main/src/store.rs"
click node_events "https://github.com/cacarico/pastor/blob/main/src/events.rs"
click node_limits "https://github.com/cacarico/pastor/blob/main/src/limit.rs"
click node_connector_admin "https://github.com/cacarico/pastor/blob/main/src/connector/cli.rs"
click node_manifest "https://github.com/cacarico/pastor/blob/main/src/connector/manifest.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_ipc,node_connector_admin toneBlue
class node_daemon,node_flock_config toneAmber
class node_job_config,node_connector_catalog,node_connector_runtime,node_scheduler,node_schedule,node_task,node_orchestrator,node_manifest toneMint
class node_machine,node_herdr,node_ssh toneRose
class node_store,node_events,node_limits,node_developer,node_external_jobs,node_external_agent toneIndigo
```

## Components

### User interface

- [Pastor CLI](https://github.com/cacarico/pastor/blob/main/src/cli.rs): `src/cli.rs`
- [Head IPC](https://github.com/cacarico/pastor/blob/main/src/ipc.rs): `src/ipc.rs`
- [Connector management](https://github.com/cacarico/pastor/blob/main/src/connector/cli.rs): `src/connector/cli.rs`

### Head control

- [Head daemon](https://github.com/cacarico/pastor/blob/main/src/daemon.rs): `src/daemon.rs`
- [Flock config](https://github.com/cacarico/pastor/blob/main/src/config/flock.rs): `src/config/flock.rs`

### Job workflow

- [Job config](https://github.com/cacarico/pastor/blob/main/src/config/job.rs): `src/config/job.rs`
- [Connector catalog](https://github.com/cacarico/pastor/blob/main/src/connector/manifest.rs): `src/connector/manifest.rs`
- [Connector runtime](https://github.com/cacarico/pastor/blob/main/src/connector/process.rs): `src/connector/process.rs`
- [Job scheduler](https://github.com/cacarico/pastor/blob/main/src/scheduler.rs): `src/scheduler.rs`
- [Schedule rules](https://github.com/cacarico/pastor/blob/main/src/schedule.rs): `src/schedule.rs`
- [Task lifecycle](https://github.com/cacarico/pastor/blob/main/src/task.rs): `src/task.rs`
- [Orchestrators](https://github.com/cacarico/pastor/blob/main/src/orchestrator.rs): `src/orchestrator.rs`
- [Connector manifest](https://github.com/cacarico/pastor/blob/main/src/connector/manifest.rs): `src/connector/manifest.rs`

### Machines and agents

- [Machine fleet](https://github.com/cacarico/pastor/blob/main/src/machine.rs): `src/machine.rs`
- [Herdr terminal](https://github.com/cacarico/pastor/blob/main/src/herdr/transport.rs): `src/herdr/transport.rs`
- [SSH transport](https://github.com/cacarico/pastor/blob/main/src/ssh.rs): `src/ssh.rs`

### State and events

- [SQLite history](https://github.com/cacarico/pastor/blob/main/src/store.rs): `src/store.rs`
- [Events and hooks](https://github.com/cacarico/pastor/blob/main/src/events.rs): `src/events.rs`
- [Agent limits](https://github.com/cacarico/pastor/blob/main/src/limit.rs): `src/limit.rs`

### Other components

- **Developer**
- **Job sources**
- **Coding agent**

## Connections

- Developer → Pastor CLI: submits commands
- Job sources → Connector runtime: provides work items
- Pastor CLI → Head IPC: sends requests (evidence: `src/cli.rs`)
- Head IPC → Head daemon: routes requests (evidence: `src/ipc.rs`)
- Head daemon → Job scheduler: runs scheduling (evidence: `src/scheduler.rs`)
- Head daemon → Machine fleet: manages fleet
- Flock config → Machine fleet: configures machines (evidence: `src/config/flock.rs`)
- Job config → Job scheduler: defines jobs (evidence: `src/config/job.rs`)
- Job scheduler → Connector runtime: requests items (evidence: `src/scheduler.rs`)
- Connector catalog → Connector runtime: resolves sources (evidence: `src/connector/mod.rs`)
- Connector manifest → Connector runtime: describes connector (evidence: `src/connector/manifest.rs`)
- Connector management → Connector manifest: installs connectors (evidence: `src/connector/cli.rs`)
- Job scheduler → Schedule rules: uses schedule rules (evidence: `src/scheduler.rs`)
- Job scheduler → Task lifecycle: queues tasks (evidence: `src/scheduler.rs`)
- Job scheduler → SQLite history: records runs (evidence: `src/scheduler.rs`)
- Task lifecycle → Herdr terminal: uses terminal API (evidence: `src/task.rs`)
- Machine fleet → Herdr terminal: connects to terminals
- Herdr terminal → SSH transport: uses remote transport (evidence: `src/herdr/transport.rs`)
- Herdr terminal → Coding agent: hosts agent
- Head daemon → SQLite history: keeps history
- Events and hooks → SQLite history: records events (evidence: `src/events.rs`)
- Events and hooks → Head daemon: publishes runtime events (evidence: `src/events.rs`)
- Events and hooks → Task lifecycle: tracks task changes (evidence: `src/events.rs`)
- Events and hooks → Connector runtime: runs event hooks
- Job scheduler → Agent limits: checks capacity (evidence: `src/scheduler.rs`)
- Pastor CLI → Orchestrators: manages orchestrators (evidence: `src/orchestrator_cli.rs`)
- Orchestrators → Machine fleet: starts agent sessions (evidence: `src/orchestrator.rs`)
- Task lifecycle → SQLite history: persists task state (evidence: `src/store.rs`)
- Pastor CLI → Machine fleet: views fleet status (evidence: `src/cli.rs`)
- Pastor CLI → SQLite history: reads task history