Overview

Pinard is a distributed engine for orchestrating fleets of LLM agents through semi-deterministic loops — deterministic runbooks that drive non-deterministic agents, coordinated over NATS across many repositories and machines.

One conductor. Many agents. One harvest.

The idea

A raw LLM agent is powerful but unpredictable: it wanders, forgets, and can’t be resumed. Pinard wraps each agent in a semi-deterministic loop — a defined sequence of steps where the control flow is deterministic code and only the work inside a step is left to the model. The result is agent work that is

  • reliable — the loop decides what happens next, not a hopeful prompt;
  • resumable — every step is journaled, so a crashed run picks up where it left off;
  • auditable — you can read exactly which steps ran and why;
  • distributed — loops run as agents spread across repos and machines, coordinated over NATS.

Three pillars hold it up:

Deterministic control (the loop) · Non-deterministic agents (the model) · Persistent memory (recall across sessions)

Automating code review — turning GitLab issues into merged MRs — is just one built-in loop. It is an application of the engine, not the engine itself.

The mental model

Pinard borrows its vocabulary from winemaking. Everything below is a role or a place in the estate:

A sketched vineyard estate divided into work plots, with an estate manager, plot foremen, harvest workers, and harvest streams converging in a blending vessel. Vignoble Vigne · repository Parcelle · outlined workstream Régisseur Maître Vendangeurs · workers Cuvée main
The Pinard estate. The vineyard vocabulary describes real boundaries of scope, responsibility, and work.
  • Vignoble / vigne / parcelle — workspace, repository, and persistent workstream.
  • Régisseur / maître / vendangeur — estate conductor, workstream conductor, and task worker.
  • Cuvée → main — several worker branches blend before one final merge.
TermMeaning
VignobleA workspace (an “estate”) — one directory that groups the repos and workstreams you orchestrate.
VigneA single repository (“vine”) registered in the vignoble.
ParcelleA named, persistent workstream — a plot of related work that spans many tasks, agents, and days.
CuvéeAn intermediate branch that batches several agents’ outputs before they reach main.
RégisseurThe estate manager — the top-level conductor for the whole vignoble.
MaîtreA parcelle-scoped conductor — one per active parcelle.
Vendangeur 🧺A harvester — a worker agent that runs one loop to completion, then is reaped.

A note on “worker” vs “vendangeur”. User-facing surfaces (dashboards, status lines, tool labels) call the harvester a vendangeur. The code keeps the name worker — CLI flags (--worker), env vars, tool names (list_workers), config keys. When these docs describe CLI or code they say worker; when they describe what you see they say vendangeur.

The pieces

Pinard is a handful of cooperating processes that talk exclusively over NATS JetStream (wss://) — never direct HTTP between components.

  • Daemon (aoc daemon) — the always-on engine. Watches events, evaluates schedules, auto-spawns agents, dispatches work to running loops, and owns the per-vignoble memory serve. It runs without any LLM and is the part that must always be up.
  • Régisseur & maîtres — optional, LLM-powered conductors (Opus) that give you a conversational way to steer. The system functions without them; they add orchestration and interaction.
  • Vendangeurs (workers) — agents (Sonnet) that each run one semi-deterministic loop — often in an isolated git worktree — and are cleaned up when done.
  • CLI (aoc) — the Go binary that scaffolds vignobles, spawns agents, runs the daemon, and exposes everything else.

How work flows

At the core, every unit of work is a loop run by an agent:

  1. A trigger arrives — a schedule fires, an event is published, or you (or a conductor) start a task.
  2. The daemon spawns a vendangeur running the appropriate babysitter process (the loop definition) with a stable run id.
  3. The loop advances step by step — each step is deterministic code or a bounded LLM turn — journaling its state as it goes.
  4. If the agent crashes or the host reboots, the run resumes from its journal.
  5. What the agent learns is written to memory, so the fleet improves over time.
  6. When the loop completes, the vendangeur is reaped.

The SWE process is the reference loop: issue → change → MR → merge. But you write your own loops for whatever your fleet does.

Where to go next