Yoke turns a goal into acceptance-tested stories, coordinates one or more coding agents, and commits work only after the configured checks pass. Run a normal backlog to completion, or optionally let Yoke explore for evidence-backed improvements and continue the same verified loop.
Version 1.23 adds local yoke usage [dir] --json and yoke tools-preflight [dir] --json diagnostics. Browser smoke now requires smoke.sourceIdentity with an app-specific same-origin path and the lowercase SHA-256 of its served bytes. Pin a stable source response and refresh it deliberately after source changes; see browser delivery configuration. Local version preparation and validation limits are recorded in 1.23 validation.
flowchart LR
A[Goal and acceptance criteria] --> B[PRD stories and dependencies]
B --> C[Agent workers in isolated worktrees]
C --> D{Acceptance tests and configured gates}
D -- needs work --> C
D -- passes --> E[Commit and local proof]
E -. explore enabled .-> F[Evidence-backed next tasks]
F --> B
Each story carries observable acceptance criteria and targeted test commands. Parallel workers take independent stories; Yoke checks their integrated result before committing. Proof is saved under .yoke/proof/.
| Capability | What it does for you |
|---|---|
| Verified completion | Checks acceptance criteria, the project verify command, and any configured completion, review, quality, or browser gates before accepting work. |
| Parallel execution | Schedules independent stories in isolated worktrees, respects dependencies and write scopes, and coordinates a shared worker limit across projects. |
| Durable goals | Binds objectives to executable acceptance, shares worker capacity, records budgets, and optionally resumes native Codex goal threads. |
| Measured routing | Keeps hard attempt budgets independent of statistics, accounts for planning and reviews, and uses comparable complete evidence for optional economic model selection. |
| Delivery evidence | Records executable user journeys, acceptance results and stable declared build artifacts with their source and acceptance fingerprints. |
| Long-running autonomy | Recovers from provider failures and blocked work. Optional exploration discovers new, repository-evidenced tasks after the planned backlog drains. |
| A choice of agents | Uses the native CLI for Claude, Codex, Gemini, Qwen, OpenCode, Kilo, Pi, or Hermes. Install and authenticate the CLI you choose; Yoke does not bundle model runtimes or credentials. |
| Project visibility | A local dashboard shows project status, Workspace analytics, History, and controls such as Queue a change, safe-boundary pause/resume, and operator notes. It runs with the local Yoke process. Dark and light themes are available. |
| Optional Pi efficiency | An opt-in SoL-Pi integration exposes per-project mechanism settings for Pi. It is off by default; benchmark results are not a savings guarantee. |
Use yoke loop wait [dir] --timeout=60 --json to wait for a terminal handoff without a model call. Use --until=change --since=<cursor> for a resumable semantic update. Timeouts return exit code 3; waiting does not start a run.
New PRD drafts include objective-bound requirement and invariant coverage, executable proof references, and explicit write ownership. Keep their requirements ledger and approved plan with the PRD. Secondary references are bounded; binding requirements remain intact. Independent review still needs to judge whether the criteria and tests satisfy the original intent.
Criterion reuse is off by default. Set verify.reusableCommands only for exact pure commands whose inputs are local and stable. Yoke hashes local inputs, including ignored files; linked/large inputs disable reuse. Full verification, integration and completion stay fresh. See validation and migration limits.
Requires Node.js 20+ and Git. Install Yoke and create a project with a draft backlog:
npm install --global @hecer/yoke
yoke new my-app --idea="A reading list app" --agent=codex --runner=codexSet verify.command in my-app/.yoke/config.yaml to the project's real test command, then run:
yoke loop on my-app
yoke loop run my-app --isolate --parallel=autoFor an existing project, run yoke setup ., set verify.command, and draft a backlog with yoke prd draft . --idea="...". Add --review when an independent reviewer is configured.
PRD format (.yoke/prd.yaml):
- id: STORY-1
title: Add a health endpoint
priority: 1
acceptance:
- id: health-returns-200
text: GET /health returns 200
verify: [npm run test:health-returns-200]
- id: health-rejects-post
text: POST /health returns 405
verify: [npm run test:health-rejects-post]
passes: falseYoke requires 2–5 behavioral criteria on new stories by default. Each criterion needs an approved test command containing its ID. See the PRD schema.
Exploration is off by default. Add --explore to keep the supervisor active after the current backlog drains. It proposes bounded work from repository evidence; accepted tasks still pass through the project's normal tests and configured gates.
yoke loop run my-app --explore --parallel=auto --explore-limit=3d
yoke loop status my-app
yoke loop pause my-appWithout --explore-limit, exploration has no time limit. A limit such as 12h, 3d, or 2w requests a pause at the next safe boundary; active stories finish their normal gates and integration first, so the process can run past the deadline while that work completes. The supervisor requires an available machine, running process, and usable providers. Read the continuous exploration guide for discovery rules, retries, stop detection, and recovery.
Use --parallel=auto or --parallel=N to run independent stories together. The scheduler observes story dependencies, collision areas, and declared write scopes. A shared user-level pool admits up to three worker units by default; YOKE_MAX_PARALLEL_WORKERS adjusts that ceiling from 1 to 8. See parallel execution for admission, integration, and recovery details.
Register projects and start the loopback-only dashboard:
yoke projects add /path/to/project
yoke dashboardThe dashboard is a local control room. It does not discover every process or run arbitrary shell commands. See the dashboard guide for data coverage and measurement limits.
| Guide | Details |
|---|---|
| Harnesses | CLI setup, permissions, provider/model selection, and telemetry limits |
| SoL-Pi for Pi | Opt-in settings, supported runtime, project trust, data handling, and paper evidence |
| Parallel execution | Worker scheduling, shared capacity, integration, and recovery |
| Continuous exploration | Autonomous discovery, runtime limits, pause/resume, and stop detection |
| Project workflows | Setup, verification, goals, and execution defaults |
| Verified goals | Acceptance binding, native Codex goals, budgets, and resource admission |
| Economic routing | Durable attempt budgets, per-call costs, capability floors, and conservative model selection |
| Delivery journeys | Browser steps, project acceptance, artifact hashes, and proof limits |
| Code Intelligence | Optional Graphify, Serena, and Graft evidence providers |
| Dashboard | Project views, history, controls, and reporting boundaries |
| Benchmarks | Direct Codex comparison, routing studies, sample limits, and integration findings |
| Benchmark manifests | Comparable inputs, model identity, build provenance, and legacy-data limitations |
| Changelog | Release features, behavior changes, and migration notes |
- A green result means the configured checks passed; the project remains responsible for meaningful tests and acceptance criteria.
- Harness permissions differ. Some CLIs do not provide an OS-level sandbox; use Yoke's read-only profile for inspection and review.
- Exploration filters proposals but cannot guarantee product maturity or model quality. Time limits pause at safe boundaries; they do not kill an active story mid-integration.
- SoL-Pi is an optional Pi extension. Its pinned upstream lists Node.js 22.19+ and
@earendil-works/pi-coding-agent@0.84.2as the tested baseline; Yoke does not enforce the Pi version. Pi project trust may be required. See SoL-Pi limits.
git clone https://github.com/HECer/yoke.git
cd yoke
npm ci
npm run lint
npm run build
npm test
npm run docs:checkYoke is released under the MIT License.