skkap/yad

YAD is one small binary for a Mac or a Linux box. It notices which coding-agent
harnesses are installed — Claude Code, Codex — and connects **out** to one or
more **hubs**: the systems that decide what work exists. When a hub has work,
YAD claims a run, prepares a working directory, drives the harness in a session
it keeps on disk, streams everything that happens, and reports how it ended.
It survives restarts and usage limits, fails over between your accounts, and
never opens a port.
Why YAD
YAD is for work you want a coding agent to do unattended: your own software
hands out the task, and a machine you prepared for it does the work and
reports back.
- **Work comes from your own projects.** Add the hub side of the protocol to
anything that needs tasks run — a tracker, a bot, a pipeline, an internal
service — and it can hand work to runners. HUB.md is the whole
contract, and yad hub is a ready-made hub if you would rather not build one.
- **It runs in an environment you prepared.** A runner lives on a machine you
set up for the job: a VM or a remote box with the tools, repositories, data
access and credentials that work needs, and nothing it does not.
machines/ builds such a machine from a spec you keep
in a repository, and docs/containers.md does the same
with a container.
- **Not tied to one harness or one account.** A run says which harness it
wants — Claude Code or Codex today — and a runner can hold several accounts
for each, moving to the next when one hits its usage limit. Accounts can be
added, logged in and removed from the machine or from the hub.
- **Control stays with the machine's owner.** Runners connect out and never
listen, and what a harness may do on a machine is decided there, never by a
hub. docs/run-it-safely.md says where the edges are.
How it works
- **A hub** is anything that serves the runner protocol: Zumino,
the task tracker; yad hub, the same binary in server mode; or your own —
HUB.md is the whole contract.
- **The runner** is yad, running as you. Every 5 to 60 seconds, as each hub
asks — every 3 while a hub holds work waiting for it — it tells the hub what
it holds, and the hub's answer carries the runs it offers. It serves any number of hubs at once and shares its capacity fairly
between them. Nothing ever connects to it.
- **A harness** is the coding agent itself. YAD drives it headless with the
logins already on the machine — it keeps no harness token of its own — in a
**session** whose workdir, a git worktree or a folder, is kept between runs.
The hub's next run in that session continues the same conversation.
The life of a run
A hub queues a run and offers it in its answer to the runner's next sync. The
runner claims it by listing it back, builds the workdir, runs the repository's
own setup hook, starts the harness and streams every
event as it happens. When an account hits its usage limit the run waits — for
another of your accounts, or for the reset — rather than failing. How it ended,
and the tokens it used, go back in the result.
What you get
- **Many hubs, one runner.** Fair shares of the machine's capacity between
hubs, with a cap per harness.
- **Nothing lost to a restart.** Sessions, events not yet delivered and results
not yet acknowledged live in SQLite. A restarted runner delivers them first
and reports the runs it was holding when it died.
- **Your accounts, used well.** Several logins per harness: a run takes the one
whose usage window refills soonest, and moves to another when it runs out.
- **Secrets that do not linger.** A hub can hand one run a short-lived secret.
It reaches that harness process alone and is deleted when the run ends.
- **A plain report of the machine.** yad doctor lists every harness it knows,
installed or not, and says which it can drive.
- **A protocol you can check.** The OpenAPI documents are generated from the Go
types, and yad conformance tests any hub against them.