A deterministic conductor for DAGs of verified agent work. pleach takes a plan, isolates
each node in a detached git worktree merged from its dependencies' verified branches, enforces
gates, and writes a local node/<id> branch only for work that passed them. It never pushes —
the conductor does — but it says, at run end and after a landing, what exists only on this
machine.
Agents produce; code decides. Close, verify, quarantine and retry are deterministic code paths. Agent output is parsed evidence, never interpreted.
Pleaching: the craft of training and interweaving living branches into a single structure.
Two products have been built this way, plan to landed code, with no human reviewing diffs: a six-feature PDF unifier, and the stem of plotplot, a released Rust binary in another repository and another language (its plans are public).
A Bun CLI. Needs git >= 2.38. Run it without cloning:
bunx github:jahala/pleach validate plan.json
bunx github:jahala/pleach run plan.jsonbunx runs pleach from bun's cache, so it does not make pleach/* imports resolve in your repo.
To import the bundled adapters from a pleach.config.ts, install pleach as a dependency:
bun add -d github:jahala/pleachThe default runner also wants tmux and an umbel binary. --runner direct-cli needs neither,
only the claude and codex CLIs.
Redacting secrets from agent and gate output needs a plotplot binary
(cargo install --locked --git https://github.com/jahala/plotplot). pleach run / land /
audit refuse to start without it; pass --no-redact to opt out explicitly — that choice is
recorded on the run's run-start line and in every receipt. See
docs/guarantees.md.
Every node goes through the same fixed sequence. The agent touches only one step of it.
isolate → setup → work → conflict-marker scan → stage → smoke → cross-provider audit → commit
A conflict marker fails closed. The smoke command is the node's own declared test. The audit runs the check command in a fresh session from a different model vendor, so no model grades its own work. Only a node that clears all of it publishes a branch.
pleach run <plan.json> Execute a plan (--land to land a fully-verified close; --only a,b
to run a named subset and its unbuilt dependencies)
pleach land <plan.json> Merge a verified plan's sinks onto the checked-out branch
pleach audit <plan.json> <node> Re-run only the audit on a quarantined node; a further re-audit
needs a changed accept.audit.command
pleach audit-wrap -- <command> Wrap any check so it prints the block an audit command must print
pleach stop <plan.json> Drain a running plan (--now aborts in-flight nodes)
pleach status <plan.json> Print the latest run's state (JSON on stdout, table on stderr)
pleach wait <plan.json> Block until the run ends; --node / --timeout shape it
pleach validate <plan.json> Parse and validate; print the topo order
pleach schema Emit the plan contract as JSON Schema
pleach receipt <node> Verify a settled node's close receipt
pleach clean Sweep a killed run's stale locks, orphaned worktrees and the
worker sessions its journal names (--dry-run lists without changing)
pleach --help carries every flag, default and exit code.
pleach run --only a,b runs just the named nodes and the unbuilt dependencies they need —
nothing else is scheduled, closed dependencies are used as bases, and an id not in the plan
refuses with exit 2. With --land the named ids become the landing's sinks. A node the subset
left out reads out-of-scope in pleach status/wait (never skipped, never failed).
A plan may be edited while it runs. Before each launch, pleach run re-reads the plan file and
applies the change to nodes that have not started — a conductor can recast an auditor or correct
a prompt without aborting the run, and goal / maxConcurrency take the new values. A node that
has already started keeps what it started with, and a change to the graph (node ids, needs,
source) or a plan that no longer validates is refused: the run carries on with the plan in force.
Work is never silently lost and a verdict is never invented. A node that cannot finish keeps its
tree on quarantine/<id> and writes a receipt.
| Situation | What pleach does |
|---|---|
| The auditor's relay is unreadable, or it dies | Quarantines with gates green; pleach audit re-adjudicates without rebuilding |
| A provider is down | --fallback-provider re-casts on another vendor; an outage is never paid twice |
| The provider needs a person to sign in | Spawn exit 126 settles blocked, never retried on that provider; sign in once outside the conductor, then re-run |
| The network or the provider errors | Waits and retries inside the same attempt; a short outage costs no attempts |
| A worker fails to spawn | Waits and re-spawns inside the same attempt; a spawn error before any work costs no attempts |
| A worker's background job is still writing | Gates wait until the tree is still; one that never settles fails the attempt, naming the paths |
| The plan holds a bare shell operator | Refused at validate, before a worker costs anything |
| A gate command cannot start | Node settles once; no attempt spent, no worker re-prompted |
| You halt the run | stop drains, --now aborts; both keep the tree and write receipts |
| A worker goes quiet | --idle-ms ends the wait; settles blocked, tree kept |
| A worker is stuck | It writes BLOCKED.md and is not asked again |
| A git hook refuses the commit | Gate verdict like any other; tree kept on a snapshot no hook can refuse |
| A git hook changes the commit | The node fails; nothing a gate did not judge is published |
| A landing conflicts | Every conflicting sink is pinned at refs/pleach/rebuild/<id> and rebuilt on the landed stack by the next pleach run — as one group, in plan order — never merged by hand |
| A seam throws mid-node | Settles under seam:<lane>; the verdict names the next step |
| The journal loses lines | Reported as journal-gap at the next run; each run keeps its own copy |
| A worker or gate prints a secret | Redacted ([REDACTED]) before it reaches the journal, the log or a receipt |
| A verified branch or landing is on no remote | run-end and landed name what is local-only; stderr warns to push |
| A killed run leaves sessions behind | pleach clean kills the sessions its journal names, sweeps their worktrees, and clears stale locks; --dry-run lists them without changing |
Full detail, one section each: docs/guarantees.md.
pleach needs a runner (drives an agent per node) and a ledger (tracks which nodes are
verified). With no config it uses umbelRunner + gitLedger, and gitLedger reads node/*
branches from the repo, so a standalone run needs nothing external.
To choose explicitly, drop a pleach.config.ts at the repo root:
import { umbelRunner } from 'pleach/adapters/umbel';
import { gitLedger } from 'pleach/adapters/git';
import type { PleachConfig } from 'pleach/config';
export default {
runner: umbelRunner({ bin: 'umbel', permissionMode: 'bypassPermissions' }),
ledger: gitLedger({ repo: '.' }),
} satisfies PleachConfig;Swap either line for your own implementation of RunnerSeam or LedgerSeam without touching the
plan. Five adapters ship; --tend-module opts into the tend ledger instead.
Contracts and a guide for writing your own: docs/adapters.md.
The repo ships a Claude Code skill, pleach-plan: give it
a goal and a repo and it decomposes the work into a gated DAG, then proves the result with
pleach validate. Agents without it still have pleach schema and pleach --help.
ENGINEERING.md is the binding doctrine.
docs/contract/plan-schema.md is the plan contract, and this repo
is its home. CONTRIBUTING.md covers the runtime substrate and how to run the
tests.
pleach's own development is tracked in its verified garden:
docs/tend2/pleach.tend2.html. The pages are self-contained;
open any of them in a browser.
MIT licensed (LICENSE). A bed in the plotplot
garden, alongside tilth (code intelligence),
weeder (the judge of the diff),
umbel (fans out agent CLIs in tmux),
pollen (agent-to-agent messaging) and
copeca (cost per correct answer). tend2 and petals are built
but not public yet.