Zeroshot
The agent that wrote the code
should not be the one
that says it works.
Zeroshot turns a software goal into an explicit graph of agents. One implements, independent agents review, and failures go back to a bounded repair loop. Nothing is delivered until the graph’s checks pass.
It doesn’t replace Claude Code, Codex or Copilot. It runs one of them as the worker and as the reviewers.
npm install -g @the-open-engine-company/zeroshot
One task, run through the built-in graph
“Add JSON output to the status command and cover it with focused tests.”
-
Worker submitted Implements the task in your Git worktree. “Done. All tests pass.”
-
Acceptance review rejected Checks the result, independently of the worker. “No test exercises the JSON output.”Code review accepted Checks it at the same time, on its own.
-
Repair worker resubmitted Gets both reviews’ feedback and fixes the work.
-
Acceptance review accepted Runs again on the repaired work.Code review accepted Runs again too, though it accepted the first time.
-
Delivery optional Accepted work proceeds through the Git and CI steps you configured. Conflicts return through repair and review.
An illustrative run of the built-in software-change graph.
What a pass means
A passing run means its configured checks accepted the work. How much that covers depends on the requirements, reviewers, tests and environment you provide.
What Zeroshot holds fixed is the process. The graph defines the sequence, the parallel steps, the retry paths and the exit conditions before execution starts. Runs are bounded, and events are recorded in a durable SQLite ledger.
Your first run
This example uses Codex and keeps the result local.
The worker edits the current Git worktree. Start in a clean one meant for the task.
-
Install it, and sign in to a harness
Zeroshot drives Codex, Claude Code or GitHub Copilot, so one of them has to be installed and signed in. Local runs can reuse that login, subscription-backed sessions included.
npm install -g @the-open-engine-company/zeroshotNeeds Node.js 18 or newer. Installs a verified native binary for Linux x64/arm64, macOS x64/arm64 or Windows x64, plus one Zeroshot skill for Codex, GitHub Copilot and Claude Code at user scope. Upgrading? v8 is a hard interface cutover: the native binary replaces the Node.js runtime. Harness prerequisites are in the installation guide.
-
Write the task
Create
input.json. Replace the example with a change that fits your repository.input.json { "task": "Add JSON output to the status command and cover it with focused tests." } -
Choose the harness and model
Create
runtime.json. ReplaceYOUR_MODEL_IDwith a model your installed Codex CLI supports.runtime.json { "harness": "codex", "provider": "openai", "model": "YOUR_MODEL_ID", "effort": "high" }Using Claude Code or Copilot instead? See Runtimes and connections.
-
Start the run
Add
--validate-onlyto check the graph, runtime configuration and input first.zeroshot run \ --title "Add JSON status output" \ --template software-change \ --input input.json \ --uniform-runtime-config runtime.json -
Watch it from another terminal
zeroshot uiVisit
http://127.0.0.1:4173/ui/and open Runs. Stopping the UI server leaves active runs running. The CLI also haszeroshot list,zeroshot status RUN_IDandzeroshot logs RUN_ID.
Bring your own graph
The built-in graph is a starting point. Choose each agent’s model and instructions, which steps run in parallel, and when to retry.
- Implementation built in
- Code review + acceptance review built in
- Bugfinder: adversarial tests you define
- E2E tests you define
- Delivery built in
An example topology with two stages added after the review loop. You define those stages, their tools, services and credentials, and where their failures go for repair.
zeroshot template show software-change
Prints the built-in graph to start from. Then see the graph contract for authoring and Prepare a runtime environment for dependencies and services.
A model for every step
Pass --runtime-config with one binding per node in place of --uniform-runtime-config.
{
"harness": "claude",
"provider": "anthropic",
"size": "medium",
"nodes": {
"worker": { "kind": "agent", "model": "WORKER_MODEL_ID", "effort": "high" },
"acceptance": { "kind": "agent", "model": "REVIEW_MODEL_ID", "effort": "high" },
"code": { "kind": "agent", "model": "REVIEW_MODEL_ID", "effort": "max" },
"review_repair": { "kind": "agent", "model": "WORKER_MODEL_ID", "effort": "high" }
}
}
Runs with delivery enabled also need a delivery_repair binding. Every field is in the RuntimePlan reference.
Save the setup as a profile
A profile stores a graph and its runtime settings. Edit and save one under Profiles in the browser UI, then run the next task with it. The CLI and UI share the same local profiles.
zeroshot run \
--title "My next task" \
--profile local:my-profile \
--input input.json
How far a run goes
Keep the first result local. Then enable the delivery mode that fits your process.
PR and ship runs address visible pull request review feedback by default. Pass --no-pr-feedback to ignore it.
-
no flag
Keep the work local.
-
--pushPush the managed branch.
-
--prPrepare a mergeable pull request without merging.
-
--shipProceed through PR, CI and merge.
Run it on infrastructure you control
Graphs execute locally or on a self-hosted target. The Docker target image includes the native engine plus pinned Codex, Claude and GitHub Copilot harness CLIs. Each environment needs its own tools and authentication setup.
docker run --detach --restart unless-stopped --name zeroshot-target \
-p 127.0.0.1:8080:8080 \
-v zeroshot-data:/var/lib/zeroshot \
ghcr.io/the-open-engine/zeroshot-target:latest
zeroshot target add local --url http://127.0.0.1:8080 --direct
The target serves its profile editor and run viewer at http://127.0.0.1:8080/ui/. The target image guide covers persistent storage, network isolation, builds and HTTPS. A failed run with a recoverable workspace can be restarted or resumed.
A second graph, for research
auto-research runs ten bounded iterations by default; set options.iterations in the run input for another count. Three scouts propose directions. A planner chooses an experiment and where it starts from: the current candidate, or an archived one it can restore. Independent judges check the evidence and the method, and a progress judge decides whether the result replaces the current candidate. An auditor checks the ledger, archive and workspace before the next iteration.
zeroshot template show auto-research
Adopted, record-only and aborted results are kept under .zeroshot/research. See Execution for the decision and evidence rules.