quackd: Give Your Microduck an LLM Brain — Any LLM, One .duck File

Project Positioning: The Missing "Brain Daemon" for Microduck

quackd (pronounced "quacked") is an open-source brain daemon independently developed by rokbenko for Pollen Robotics' Microduck bipedal robot — named as a sibling of the robot's onboard daemons robotd, mediad, padd, and tofd. It connects the small robot to any large language model (Claude, OpenAI, Gemini, Grok, or a local open-source model via llama.cpp/vLLM/Ollama/LM Studio), turning plain-language requests like "find the ball and kick it" into the right sequence of the robot's existing skills, watches what happens, and keeps going until the job is done or clearly impossible.

The core insight is about layering: a modern small robot is not short of skills — Microduck's onboard controllers already balance it, walk, kick, sit, stand up after a fall, and scoop with its beak, each a trained policy running at 50 Hz without any AI model. What the robot lacks is any idea of what those skills are for. quackd is exactly this connective layer: the LLM does the planning, and the robot's own controllers do the moving.

Working Principle: Verb Contracts + Closed-Loop Observation

The architecture is a tight perception-plan-action loop: the LLM looks at the camera frame, the robot's state, and the last result, then picks ONE skill (a verb) and its parameters; quackd checks the rules (allowed? budget left? needs confirmation?) and runs the verb; the robot or simulator executes the skill with its own controllers; quackd observes the result and loops until done or impossible.

The verbs the model can pick from are real, existing capabilities and nothing more:

Kind	Verbs	What They Are
Built-in	walk sit stand stand_up stop kick grab gaze quack get_frame	One per behaviour the robot ships with; each an intent executed by the robot's own controllers
Composite	search_scan walk_to approach_and	Plain Python over built-in verbs and the camera — the steering loop
Learned	(none yet)	v2: policies trained from LLM-written rewards, registered like any other verb

walk_to deserves special mention: it is a small closed loop written in plain Python that steers toward whatever the camera sees, ten times a second, without asking the model. The LLM says "go to the ball" — it never has to say "turn 4° left". This division of labor (LLM at goal granularity, controllers at millisecond granularity) is the design core of the whole project.

The .duck File: A Contract the Model Cannot Talk Its Way Out Of

A task file is a contract plus instructions, deliberately shaped like a SKILL.md: the YAML frontmatter is enforced by quackd, while the Markdown body is read by the model. The frontmatter defines the verb allowlist (verbs.allow), verbs requiring human confirmation (confirm), budgets (max_steps/max_minutes/max_llm_calls), success criteria, abort conditions, and persona. This is a hard contract layer: which skills are allowed, how many steps, when a human must say yes, when to abort — none of it can be negotiated away by prompt injection.

The repo ships six starter tasks: hello-world (smoke test), find-and-kick (flagship, ground truth checked in tests), patrol-and-quack, follow-me, fetch (experimental, the scoop is open-loop and fails ~40% of the time in sim, by design), and flock-kick (flock mode).

Flock Mode: Contract Net Auction Across Multiple Ducks

v0.3 introduces multi-robot coordination: multiple simulated Microducks talk over an in-process message bus (TASK/BID/CLAIM/ROLE/HB/RESULT messages, every one logged in flock.jsonl), and a deterministic Contract Net auction decides which duck acts, based on each duck's own camera distance estimate. The first choreography is a kick: split the search, auction, one actor. Two points of restraint are worth noting: the LLM contributes at most one planning call per run, and each duck still enforces the .duck contract on itself; the outcome is judged from sim ground truth, not from a model's claim. The coordination machinery is task-agnostic — what a flock can do is bounded by its skills, not by the ball.

Engineering and Ecosystem

• 60-second trial: uvx quackd run find-and-kick --provider fake runs the bundled cartoon simulator with a scripted pilot (no API key); every run leaves a GIF and a transcript;
• Local model support: Ollama/vLLM/llama.cpp/LM Studio, no API key needed; cloud providers see the camera frame as an image, local models get text detections by default (--vision adds the frame);
• MCP server: quackd serve-mcp exposes eight duck_* tools over stdio, so Claude Code or Claude Desktop can drive the duck interactively with the same allowlists and budgets;
• Honest engineering culture: the hero GIF is the scripted pilot (the repo was built without an API key); real model code paths are tested against stubbed SDK clients; the limitations section enumerates unverified assumptions one by one (jsonrpc transport unverified end-to-end, default model IDs for some providers unverified, local model quality unmeasured).

Roadmap and Assessment

The roadmap is clear: hardware transport validated when Microducks ship (Christmas 2026); more flock choreographies plus a LAN bus (MQTT) implementing the same Bus protocol; v1 = five starter tasks on a real duck on video; v2 = learned verbs — LLM-written rewards (Eureka/DrEureka style) training new policies in microduck_rl that register as one more verb (the registry hook exists today).

quackd is one of the cleanest open implementations of the "LLM as high-level planner + robot's own policies as low-level execution" paradigm: the verb abstraction keeps the model's authority bounded, the .duck contract turns safety into an enforceable spec rather than a prompt convention, the simulator-first approach lets the whole agent loop be developed before hardware exists, and MCP integration makes it immediately drivable from coding agents. For teams building agent harnesses for small robots or robot-dialogue interfaces, this is currently one of the most complete reference implementations. Apache 2.0 licensed, installable from PyPI, tests run with no network and no keys.