zeroshot
Docs GitHub

Open source · Independent review and repair for coding agents

The agent that writes the code should not be the one that decides it works.

Zeroshot turns a software goal into an explicit multi-agent graph. One agent implements, independent agents review, rejected work goes through a bounded repair loop, and nothing is delivered until the graph's checks pass.

npm install -g @the-open-engine-company/zeroshot
Run your first task Read the docs GitHub

Runs on Claude Code Codex GitHub Copilot

template software-change
The built-in software-change graph A task goes to a worker. The worker's result goes to an acceptance reviewer and a code reviewer, in parallel. If the work is rejected, both reviews' feedback goes to one repair worker, and the repaired work goes through both reviews again. When both reviewers accept, the work proceeds to optional delivery. task Add JSON output to the status command worker implements the task acceptance review checks the requirements code review checks the code repair fixes rejected work delivery · optional push, PR, or ship

Both reviews run again after a repair. Delivery is optional.

Starred by engineers at Google, Meta, Shopify, Uber, Booking.com, GitHub, Cloudflare, Atlassian and JetBrains

Why Zeroshot

Self-review isn't review.

“We built Zeroshot because we were tired of being gaslit by agents telling us broken code was ready.”

Ask the agent that wrote the code whether it works and you get its opinion of its own work. Zeroshot keeps the roles apart: the implementing agent never approves its own work.

It doesn't replace Claude Code, Codex or Copilot. It runs one of them as the worker and as the reviewers.

Watch a single agent vs. Zeroshot (scripted video)

A single agent

  1. Writes the code
  2. Reviews its own work
  3. Tells you it's ready
    self-reported

Zeroshot

  1. A worker writes the code
  2. Independent reviewers check it, in parallel
  3. Rejected work is repaired, then reviewed again
  4. Delivered only when the graph's checks pass

How it works

The graph is set before the first agent runs.

The graph defines the sequence, parallel steps, retry paths, and exit conditions before execution starts. Runs are bounded, and events are recorded in a durable SQLite ledger.

  1. Implement

    A worker implements the task.

  2. Review independently

    Acceptance and code reviewers check the result independently, in parallel.

  3. Repair

    Rejected work goes to one repair worker with both reviews' feedback, then through both reviews again.

  4. Deliver

    With delivery enabled, accepted work proceeds through the configured Git and CI steps.

  5. Handle conflicts

    Delivery conflicts return through repair and review.

Quickstart

Run your first task

This example uses Codex and keeps delivery local. You need Node.js 18 or newer, and Codex, Claude Code, or GitHub Copilot installed and signed in.

The worker edits the current Git worktree. Start in a clean worktree intended for the task.

  1. Install

    Installs a verified native binary for Linux x64/arm64, macOS x64/arm64, or Windows x64, plus a Zeroshot skill for Codex, GitHub Copilot, and Claude Code at user scope.

    shell
    npm install -g @the-open-engine-company/zeroshot

  2. Describe the task

    Create input.json with a change that fits your repository.

    input.json
    {
  "task": "Add JSON output to the status command and cover it with focused tests."
}

  3. Choose the runtime

    Create runtime.json. Replace YOUR_MODEL_ID with a model your installed Codex CLI supports.

    runtime.json
    {
  "harness": "codex",
  "provider": "openai",
  "model": "YOUR_MODEL_ID",
  "effort": "high"
}

  4. Start the run

    Add --validate-only to check the graph, runtime configuration, and input first.

    shell
    zeroshot run \
  --title "Add JSON status output" \
  --template software-change \
  --input input.json \
  --uniform-runtime-config runtime.json

  5. Watch it work

    In another terminal, start the UI, open http://127.0.0.1:4173/ui/ and go to Runs. Stopping the UI server leaves active runs running. The CLI also has zeroshot list, zeroshot status RUN_ID, and zeroshot logs RUN_ID.

    shell
    zeroshot ui

Make it yours

Bring your own graph.

Use the built-in graph or your own topology. Choose each agent's model and instructions, which steps run in parallel, and when to retry. Then save the setup as a profile for the next task.

Add stages

For example, add stages after the review loop. The review loop, the auto-research graph, and delivery are built in. You define other stages, their tools, services and credentials, and where failures go for repair.

Start from the built-in graph: zeroshot template show software-change

  1. Implementationbuilt in
  2. Code review + acceptance reviewbuilt in
  3. Bugfinder: adversarial testsyours
  4. E2E testsyours
  5. Deliverybuilt in

Pick a model per step

Pass --runtime-config with one binding per node in place of --uniform-runtime-config. Give the reviewers a different model from the worker, or raise the effort where it matters.

Runs with delivery enabled also need a delivery_repair binding. The RuntimePlan reference lists every field.

runtime-config.json
{
  "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" }
  }
  }

Save it as a profile

A profile stores a graph and its runtime settings. Edit and save one under Profiles in the browser UI. The CLI and UI share the same local profiles, so you can keep one per kind of work.

shell
zeroshot run \
  --title "My next task" \
  --profile local:my-profile \
  --input input.json

Delivery

Keep the first result local. Ship when you trust it.

Delivery is opt-in, one flag per level. 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

  • --push

    Push the managed branch

  • --pr

    Prepare a mergeable pull request without merging

  • --ship

    Proceed through PR, CI, and merge

Execution

Run it on your machine or on infrastructure you control.

Graphs can execute locally or on a self-hosted target. Each environment needs its own tools and authentication setup.

Local

Install and sign in to Codex, Claude Code, or GitHub Copilot. Local runs can reuse the harness's existing login, including subscription-backed sessions.

Watch runs in the workspace UI, or from the terminal with zeroshot list, status, and logs.

A failed run with a recoverable workspace can be restarted or resumed.

Self-hosted Docker target

Keep execution and durable state on your own infrastructure. The image includes the native engine plus pinned Codex, Claude, and GitHub Copilot harness CLIs, and serves a profile editor and run viewer at /ui/.

shell
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 image guide covers persistent storage, network isolation, builds, and HTTPS.

Also built in

Auto-research

The auto-research template runs bounded iterations of experiments, ten by default, with independent review of evidence, method, and progress. Adopted, record-only, and aborted results are kept under .zeroshot/research. Add --push to publish each finalized iteration.

Set a positive options.iterations in the run input to choose another count.

  1. Three scouts propose directions.
  2. A planner chooses an experiment and a starting point: the current candidate or a restorable archived one.
  3. Independent judges check the evidence and method.
  4. The progress judge decides whether the result replaces the current candidate under the task charter. A valid result can go into the archive without replacing it.
  5. An auditor checks the ledger, archive, and workspace before the next iteration.

next iteration

shell
zeroshot template show auto-research

FAQ

Questions engineers ask first

Something else? Ask on Discord or open a GitHub issue.

Does Zeroshot replace Claude Code, Codex, or Copilot?

No. Zeroshot runs one of them as the worker and as the reviewers. It supplies the graph: who implements, who reviews, where rejected work goes, and when the run is finished.

Do I need separate API keys?

Local runs can reuse your harness's existing login, including subscription-backed sessions. The installation guide lists harness prerequisites, and Runtimes and connections covers other providers.

What does a passing run guarantee?

That its configured checks accepted the work. Coverage depends on the requirements, reviewers, tests, and environment you provide. If you need adversarial or end-to-end tests, add them as stages in your graph.

Will it push to my repository?

Not unless you pass a delivery flag. Without one, the work stays local. The worker does edit the current Git worktree, so start in a clean one. --push, --pr, and --ship opt in to each level of delivery.

Can a review loop run forever?

No. Runs are bounded, and the graph defines retry paths and exit conditions before execution starts.

Can the worker and the reviewers use different models?

Yes. Pass --runtime-config with one binding per node, each with its own model and effort. See the RuntimePlan reference.

Which platforms are supported?

The npm installer needs Node.js 18 or newer and installs a verified native binary for Linux x64/arm64, macOS x64/arm64, or Windows x64. For self-hosting there is a Docker target image.

I used an earlier version. What changed in v8?

v8 is a hard interface cutover: it replaces the Node.js runtime with a native zeroshot binary. Read the release notes before upgrading.

Is it open source?

Yes, MIT licensed. There is also a Python SDK and a cluster API. Contributions start with CONTRIBUTING.md.

Stop taking the agent's word for it.

Install Zeroshot and give your next task a reviewer that didn't write the code.

npm install -g @the-open-engine-company/zeroshot
Read the docs View on GitHub Join the Discord