How execution works¶
Your graph decides what runs next. After each step, zeroshot validates the result, updates the shared state and follows the graph's rules. Agents cannot add steps or increase retry limits.
For example, a graph can send a worker's change to two reviewers, return rejected work for repair and stop after four attempts. The reviewers judge the change; zeroshot enforces the route and limit. Build a review loop implements that example.
Before a run starts¶
A run needs four inputs:
| Input | Purpose |
|---|---|
| Title | Identifies the run in lists and status output |
| Graph | Defines steps, shared state, routes, limits and results |
| Initial input | Supplies the task in the format the graph expects |
| Runtime plan | Chooses each agent's harness, provider, model and connections |
Before starting a local controller or submitting to a target, zeroshot checks the graph, runtime
bindings and input. For a target-stored profile, it fetches the profile first and applies the same
checks. --validate-only runs these checks without starting a run.
Graph nodes¶
step and verifier nodes do the work. Groups control their execution:
| Group | Behavior |
|---|---|
seq |
Runs children in order |
choice |
Selects a branch from the declared signals |
par |
Runs branches concurrently and joins their results |
loop |
Repeats a body within a fixed limit |
map |
Runs a bounded body for array items |
succeed and fail |
End the graph |
Routes and conditions are structured data, not executable code or prompt instructions. The graph contract defines their fields.
Which checks are deterministic¶
The engine enforces the order, routes and retry limits. What a step decides depends on its
binding. Agent steps and verifiers are model judgement. A step can instead run a
script you own, which takes the step's JSON input and
returns its JSON output, so that step's result comes from your program, not a model. A non-zero
exit is an error, and the graph's error and retry rules apply. Script steps are local only for now.
Outside the graph, delivery waits on your CI and required checks and cannot override them, and local runs can add a delivery check command.
How results choose the next step¶
Each agent returns a value through its declared output channel. zeroshot validates that value, updates state using the graph's bindings, then evaluates what runs next.
In a repair loop, a reviewer returns a decision and feedback. The graph routes an acceptance
onward or a rejection back for repair. maxIterations still applies if an agent asks to continue.
Working in parallel¶
Parallel agents share a workspace. Coordinate writers so they do not overwrite each other's changes, and place reviewers after the writers when they need the finished result. Reviewers see the same dependencies, generated files and services as workers.
Put Git delivery after all writing and review branches have joined. Graph validation rejects concurrent delivery alongside another executable node, or inside a map that can have multiple items.
Run history and cleanup¶
Each run has an ID and a SQLite ledger. Closing the terminal, disconnecting a client or cancelling
a Python await does not stop the controller. Reconnect to inspect the run or stop it explicitly;
see Observe and control runs.
The controller cleans up execution activity when the run ends. Cleanup guarantees differ by OS; process cleanup describes detached child processes.
Built-in templates are ordinary graphs¶
Use a built-in graph as it is, or export it to make your own:
template show prints a tree, marking executable nodes with *. Add --json or redirect stdout
to export the complete GraphSpec.
| Template | Purpose |
|---|---|
software-change |
Implement, review, repair and deliver a change |
single-worker |
Run one agent without a review loop |
pr-review |
Review a PR and post a concise comment |
code-review |
Review a PR in depth and post verified findings |
issue-review |
Review an issue proposal |
auto-research |
Run experiments and retain results accepted by a reviewer |
software-change opens a PR by default. Choose delivery with:
| Option | Result |
|---|---|
--delivery none |
Keep the accepted change local |
--push |
Push the run branch without opening a PR |
--pr |
Open or update a PR, address feedback and wait for CI; leave merging to you |
--ship |
Follow the same review loop, then merge under the repository's policy |
Required approval blocks --ship, but not --pr.
Breaking change: local delivery commits on the checked-out branch and publishes the remote
branch of the same name, including existing unpushed commits. In-place runs create no managed
zeroshot/v2-… branch. --pr and --ship target a different upstream branch when configured,
otherwise the remote's default branch. Starting on that target is refused before agents start;
use a feature branch or --worktree. Explicit --push can publish main; delivery never force-pushes.
Add --worktree to work on a managed run branch in a separate, retained Git worktree. Its default
base is the invoking branch's exact local HEAD. --worktree-base remote fetches its upstream and
requires one to be configured. Delivery commits and publishes the matching managed run branch;
PR/MR targets remain the invoking branch's upstream, or its name when none is set. The invoking
checkout stays unchanged. Worktrees contain committed files only, with no dependency setup or
untracked resources copied. Resume reuses the worktree and keeps HEAD attached without rewinding
shared branch tips. Remove the worktree explicitly when finished. See
source and delivery setup.
PR feedback is enabled by default and restricted to repository writers. --no-pr-feedback
disables it; feedback rules cover permission checks.
auto-research runs ten rounds by default; options.iterations changes the count. Results stay in
.zeroshot/research; --push publishes each accepted round. See
research rounds and repair for the full behavior.