# rokbenko/quackd architecture

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

- Interactive diagram: https://gitdiagram.com/rokbenko/quackd
- Repository: https://github.com/rokbenko/quackd

## Overview

quackd is a command-line and service layer for connecting heterogeneous robots, piloting them with language models, and coordinating them as flocks. The main run accepts a goal from the CLI, chat, or a .duck task, resolves a registered robot and its declared capabilities, then repeatedly observes, chooses one action, enforces run limits, and executes it through the robot adapter. The repository also documents flock coordination, perception, simulation, and remote LeRobot policy serving. Some subsystems are represented from README claims and the file tree; their internal wiring is omitted where source evidence was not provided.

Main entry points: [`quackd/agent/loop.py`](https://github.com/rokbenko/quackd/blob/main/quackd/agent/loop.py) (Agent loop), [`quackd/cli.py`](https://github.com/rokbenko/quackd/blob/main/quackd/cli.py) (CLI), [`quackd/safety.py`](https://github.com/rokbenko/quackd/blob/main/quackd/safety.py) (Safety executor), [`quackd/verbs/core.py`](https://github.com/rokbenko/quackd/blob/main/quackd/verbs/core.py) (Core verbs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and tasks"]
  node_cli["CLI<br/>[cli.py]"]
  node_duckfile["Task files<br/>[parser.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
end

subgraph group_pilot["Pilot and controls"]
  node_agent["Agent loop<br/>[loop.py]"]
  node_providers["LLM providers"]
  node_decision["Decision pilots"]
  node_safety["Safety executor<br/>[safety.py]"]
  node_verbs["Verb registry<br/>[registry.py]"]
  node_coreverbs["Core verbs<br/>[core.py]"]
end

subgraph group_robots["Robot runtime"]
  node_perception["Perception"]
  node_manifest["Robot manifest<br/>[manifest.py]"]
  node_adapters["Robot adapters<br/>[base.py]"]
  node_transport["Transport<br/>[base.py]"]
  node_registry[("Robot registry<br/>[registry.py]")]
  node_sim["2D simulator<br/>[world.py]"]
end

subgraph group_flock["Flock coordination"]
  node_flocktask["Flock task<br/>[schema.py]"]
  node_coordinator["Flock coordinator<br/>[coordinator.py]"]
  node_member["Flock member<br/>[member.py]"]
  node_bus["Flock message bus<br/>[bus.py]"]
end

subgraph group_policy["LeRobot policy"]
  node_policyclient["Policy client<br/>[client.py]"]
  node_policyserver["Policy server<br/>[server.py]"]
  node_pipeline["Checkpoint pipeline<br/>[pipeline.py]"]
  node_runner["Policy runner<br/>[runner.py]"]
end

node_operator(("Robot operator"))
node_human(("Human approver"))

node_operator -->|"submits goal"| node_cli
node_operator -.->|"pilots by chat"| node_mcp
node_duckfile -->|"provides task"| node_cli
node_cli -->|"starts run"| node_agent
node_cli -->|"selects robot"| node_registry
node_agent -->|"requests model choice"| node_providers
node_agent -->|"optionally scores choices"| node_decision
node_agent -->|"enforces action"| node_safety
node_safety -->|"checks allowlist"| node_verbs
node_verbs -->|"registers templates"| node_coreverbs
node_coreverbs -->|"sends intents"| node_transport
node_coreverbs -->|"detects targets"| node_perception
node_agent -->|"observes"| node_perception
node_adapters -->|"returns capabilities"| node_manifest
node_adapters -->|"implements interface"| node_transport
node_registry -.->|"resolves registered body"| node_adapters
node_sim -.->|"simulates transport"| node_transport
node_safety -->|"requests approval"| node_human
node_cli -->|"starts flock run"| node_coordinator
node_flocktask -->|"configures roles"| node_coordinator
node_coordinator -.->|"dispatches work"| node_member
node_member -->|"exchanges messages"| node_bus
node_member -.->|"runs robot pilot"| node_agent
node_policyclient -->|"sends policy requests"| node_policyserver
node_policyserver -->|"loads checkpoint"| node_pipeline
node_pipeline -->|"builds runner"| node_runner
node_policyclient -.->|"requests action chunks"| node_runner

click node_cli "https://github.com/rokbenko/quackd/blob/main/quackd/cli.py"
click node_duckfile "https://github.com/rokbenko/quackd/blob/main/quackd/duckfile/parser.py"
click node_mcp "https://github.com/rokbenko/quackd/blob/main/quackd/mcp_server.py"
click node_agent "https://github.com/rokbenko/quackd/blob/main/quackd/agent/loop.py"
click node_providers "https://github.com/rokbenko/quackd/tree/main/quackd/agent/providers"
click node_decision "https://github.com/rokbenko/quackd/tree/main/quackd/agent/decision"
click node_safety "https://github.com/rokbenko/quackd/blob/main/quackd/safety.py"
click node_verbs "https://github.com/rokbenko/quackd/blob/main/quackd/verbs/registry.py"
click node_coreverbs "https://github.com/rokbenko/quackd/blob/main/quackd/verbs/core.py"
click node_perception "https://github.com/rokbenko/quackd/tree/main/quackd/perception"
click node_manifest "https://github.com/rokbenko/quackd/blob/main/quackd/adapters/manifest.py"
click node_adapters "https://github.com/rokbenko/quackd/blob/main/quackd/adapters/base.py"
click node_transport "https://github.com/rokbenko/quackd/blob/main/quackd/transport/base.py"
click node_registry "https://github.com/rokbenko/quackd/blob/main/quackd/registry.py"
click node_sim "https://github.com/rokbenko/quackd/blob/main/quackd/sim2d/world.py"
click node_flocktask "https://github.com/rokbenko/quackd/blob/main/quackd/duckfile/schema.py"
click node_coordinator "https://github.com/rokbenko/quackd/blob/main/quackd/flock/coordinator.py"
click node_member "https://github.com/rokbenko/quackd/blob/main/quackd/flock/member.py"
click node_bus "https://github.com/rokbenko/quackd/blob/main/quackd/flock/bus.py"
click node_policyclient "https://github.com/rokbenko/quackd/blob/main/adapters/lerobot/src/quackd_lerobot/policy/client.py"
click node_policyserver "https://github.com/rokbenko/quackd/blob/main/adapters/lerobot/src/quackd_lerobot/policy/server.py"
click node_pipeline "https://github.com/rokbenko/quackd/blob/main/adapters/lerobot/src/quackd_lerobot/policy/pipeline.py"
click node_runner "https://github.com/rokbenko/quackd/blob/main/adapters/lerobot/src/quackd_lerobot/policy/runner.py"

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_duckfile,node_mcp toneBlue
class node_agent,node_providers,node_decision,node_safety,node_verbs,node_coreverbs toneAmber
class node_perception,node_manifest,node_adapters,node_transport,node_registry,node_sim toneMint
class node_flocktask,node_coordinator,node_member,node_bus toneRose
class node_policyclient,node_policyserver,node_pipeline,node_runner,node_operator,node_human toneIndigo
```

## Components

### Entry and tasks

- [CLI](https://github.com/rokbenko/quackd/blob/main/quackd/cli.py): `quackd/cli.py`
- [Task files](https://github.com/rokbenko/quackd/blob/main/quackd/duckfile/parser.py): `quackd/duckfile/parser.py`
- [MCP server](https://github.com/rokbenko/quackd/blob/main/quackd/mcp_server.py): `quackd/mcp_server.py`

### Pilot and controls

- [Agent loop](https://github.com/rokbenko/quackd/blob/main/quackd/agent/loop.py): `quackd/agent/loop.py`
- [LLM providers](https://github.com/rokbenko/quackd/tree/main/quackd/agent/providers): `quackd/agent/providers`
- [Decision pilots](https://github.com/rokbenko/quackd/tree/main/quackd/agent/decision): `quackd/agent/decision`
- [Safety executor](https://github.com/rokbenko/quackd/blob/main/quackd/safety.py): `quackd/safety.py`
- [Verb registry](https://github.com/rokbenko/quackd/blob/main/quackd/verbs/registry.py): `quackd/verbs/registry.py`
- [Core verbs](https://github.com/rokbenko/quackd/blob/main/quackd/verbs/core.py): `quackd/verbs/core.py`

### Robot runtime

- [Perception](https://github.com/rokbenko/quackd/tree/main/quackd/perception): `quackd/perception`
- [Robot manifest](https://github.com/rokbenko/quackd/blob/main/quackd/adapters/manifest.py): `quackd/adapters/manifest.py`
- [Robot adapters](https://github.com/rokbenko/quackd/blob/main/quackd/adapters/base.py): `quackd/adapters/base.py`
- [Transport](https://github.com/rokbenko/quackd/blob/main/quackd/transport/base.py): `quackd/transport/base.py`
- [Robot registry](https://github.com/rokbenko/quackd/blob/main/quackd/registry.py): `quackd/registry.py`
- [2D simulator](https://github.com/rokbenko/quackd/blob/main/quackd/sim2d/world.py): `quackd/sim2d/world.py`

### Flock coordination

- [Flock task](https://github.com/rokbenko/quackd/blob/main/quackd/duckfile/schema.py): `quackd/duckfile/schema.py`
- [Flock coordinator](https://github.com/rokbenko/quackd/blob/main/quackd/flock/coordinator.py): `quackd/flock/coordinator.py`
- [Flock member](https://github.com/rokbenko/quackd/blob/main/quackd/flock/member.py): `quackd/flock/member.py`
- [Flock message bus](https://github.com/rokbenko/quackd/blob/main/quackd/flock/bus.py): `quackd/flock/bus.py`

### LeRobot policy

- [Policy client](https://github.com/rokbenko/quackd/blob/main/adapters/lerobot/src/quackd_lerobot/policy/client.py): `adapters/lerobot/src/quackd_lerobot/policy/client.py`
- [Policy server](https://github.com/rokbenko/quackd/blob/main/adapters/lerobot/src/quackd_lerobot/policy/server.py): `adapters/lerobot/src/quackd_lerobot/policy/server.py`
- [Checkpoint pipeline](https://github.com/rokbenko/quackd/blob/main/adapters/lerobot/src/quackd_lerobot/policy/pipeline.py): `adapters/lerobot/src/quackd_lerobot/policy/pipeline.py`
- [Policy runner](https://github.com/rokbenko/quackd/blob/main/adapters/lerobot/src/quackd_lerobot/policy/runner.py): `adapters/lerobot/src/quackd_lerobot/policy/runner.py`

### Other components

- **Robot operator**
- **Human approver**

## Connections

- Robot operator → CLI: submits goal (evidence: `README.md`)
- Robot operator → MCP server: pilots by chat (evidence: `README.md`)
- Task files → CLI: provides task (evidence: `README.md`)
- CLI → Agent loop: starts run (evidence: `quackd/cli.py`)
- CLI → Robot registry: selects robot (evidence: `quackd/cli.py`)
- Agent loop → LLM providers: requests model choice (evidence: `quackd/agent/loop.py`)
- Agent loop → Decision pilots: optionally scores choices (evidence: `quackd/agent/loop.py`)
- Agent loop → Safety executor: enforces action (evidence: `quackd/agent/loop.py`)
- Safety executor → Verb registry: checks allowlist (evidence: `quackd/safety.py`)
- Verb registry → Core verbs: registers templates (evidence: `quackd/verbs/registry.py`)
- Core verbs → Transport: sends intents (evidence: `quackd/verbs/core.py`)
- Core verbs → Perception: detects targets (evidence: `quackd/verbs/core.py`)
- Agent loop → Perception: observes (evidence: `quackd/agent/loop.py`)
- Robot adapters → Robot manifest: returns capabilities (evidence: `quackd/adapters/base.py`)
- Robot adapters → Transport: implements interface (evidence: `quackd/adapters/base.py`)
- Robot registry → Robot adapters: resolves registered body
- 2D simulator → Transport: simulates transport
- Safety executor → Human approver: requests approval (evidence: `README.md`)
- CLI → Flock coordinator: starts flock run (evidence: `README.md`)
- Flock task → Flock coordinator: configures roles (evidence: `quackd/duckfile/schema.py`)
- Flock coordinator → Flock member: dispatches work
- Flock member → Flock message bus: exchanges messages (evidence: `quackd/flock/member.py`)
- Flock member → Agent loop: runs robot pilot
- Policy client → Policy server: sends policy requests (evidence: `adapters/lerobot/src/quackd_lerobot/policy/client.py`)
- Policy server → Checkpoint pipeline: loads checkpoint (evidence: `adapters/lerobot/src/quackd_lerobot/policy/server.py`)
- Checkpoint pipeline → Policy runner: builds runner (evidence: `adapters/lerobot/src/quackd_lerobot/policy/pipeline.py`)
- Policy client → Policy runner: requests action chunks (evidence: `adapters/lerobot/src/quackd_lerobot/policy/client.py`)
