zeroshot

Build your own open-source software factory.

Turn a task into a reviewed pull request through a workflow you control. Choose the agents and models, define what must pass, and decide where rejected work goes for repair.

Start with the built-in software-change graph: implementation → independent review → repair → optional delivery. Or design your own topology. Add security reviewers, test agents, and parallel checks, then save the workflow as a profile and reuse it.

The agent that writes the code cannot approve its own work. The engine enforces the graph's review gates and retry limits. Think of it as CI for coding agents, starting before the code is written. zeroshot runs Claude Code, Codex, or Copilot as the worker and reviewers, with a separate harness and provider available for each agent.

The CLI is free and MIT licensed. Run locally, self-host, or use zeroshot Cloud.

Workflow illustration: both reviews run again after a repair. Git delivery is optional.

Static diagram

We want to explore how much task decomposition and validation loops can narrow the gap between open models and closed frontier systems. The graph, review rules, and repair paths are open for anyone to inspect, change, and test on real work.

▶ Video: a single agent vs. zeroshot (scripted)

Questions, ideas, or a run worth showing? Join the zeroshot community on Discord.

Get started

Prefer Cloud? Cloud setup →

Run locally

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

The installer requires Node.js 18 or newer and installs a verified native binary for Linux x64/arm64, macOS x64/arm64, or Windows x64. It also installs one zeroshot skill for Codex, GitHub Copilot, and Claude Code at user scope.

For local execution, install and sign in to Codex, Claude Code, or GitHub Copilot. Local runs can reuse the harness's existing login, including subscription-backed sessions. See the installation guide for harness prerequisites.

Run your first task

This example uses Codex and keeps delivery local. The worker edits the selected folder; Git is optional. Add --cwd FOLDER to select another folder; input files stay relative to the invoking folder.

Create input.json, replacing the example task with a change appropriate for your project:

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

Create runtime.json. Replace YOUR_MODEL_ID with a model identifier supported by your installed Codex CLI:

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

Start the run. Add --validate-only to 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

Open another terminal to inspect the run:

zeroshot ui

Visit http://127.0.0.1:4173/ui/ and open Runs. Stopping the UI server leaves active runs running. The CLI also provides zeroshot list, zeroshot status RUN_ID, and zeroshot logs RUN_ID.

For other harnesses and providers, see Runtimes and connections.

Run in the cloud

Connect GitHub and bring your own model API keys. Cloud setup guide →

What the built-in workflow does

1. A worker implements the task.
2. Acceptance and code reviewers check the result independently, in parallel.
3. Rejected work goes to one repair worker with both reviews' feedback, then through both reviews again.
4. With delivery enabled, accepted work proceeds through the configured Git and CI steps.
5. Delivery conflicts return through repair and review.

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. A passing run means its configured checks accepted the work; coverage depends on the requirements, reviewers, tests, and environment you provide.

Auto-research

The built-in auto-research template runs ten iterations by default; set a positive options.iterations value in the run input to choose another count. Three scouts propose directions, then a planner chooses an experiment and either the current candidate or a restorable archived candidate as its starting point. Independent judges check the evidence and method, while the progress judge decides whether the result should replace the current candidate under the task charter. A valid result can go into the archive without replacing it. An auditor checks the ledger, archive, and workspace before the next iteration.

Inspect the graph with zeroshot template show auto-research.

Bring your own graph topology

Choose each agent's model and instructions, which steps run in parallel, and when to retry. Example topology, adding stages after the review loop:

Implementation
      ↓
Code review + acceptance review
      ↓
Bugfinder: adversarial tests
      ↓
E2E tests
      ↓
Delivery

The software-change review loop, auto-research graph, and delivery are built in. You define other stages, their tools, services and credentials, and where failures go for repair.

Inspect the built-in graph as a starting point:

zeroshot template show software-change

See the graph contract for custom graph authoring and Prepare a runtime environment for dependency and service setup.

Save and reuse a profile

Each step can use its own model. 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", "sessionScope": "node_instance" },
    "acceptance": { "kind": "agent", "model": "REVIEW_MODEL_ID", "effort": "high" },
    "code": { "kind": "agent", "model": "REVIEW_MODEL_ID", "effort": "max" }
  }
}

The same worker handles implementation, review repairs, and delivery repairs in one session. Both reviewers start fresh on every pass. Run zeroshot template show software-change to list the node names. See the RuntimePlan reference for every field.

A profile stores a graph and its runtime settings. Use Profiles in the browser UI to edit and save your configuration. Keep different profiles for different kinds of work, or reuse one for the next task.

Once you've saved a local profile named my-profile, run another task with it:

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

The CLI and UI share the same local profiles. See UI setup.

Choose delivery and execution

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.

Push needs a committed Git checkout and an HTTPS or SSH remote. PR and ship additionally need a forge adapter; GitHub is maintained today. Docker and cloud runs require an exact Git source. See targets and source credentials for setup.

Self-hosted: run the Docker target

Keep execution and durable state on infrastructure you control. The target image includes the native engine plus pinned Codex, Claude, and GitHub Copilot harness CLIs.

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 also serves its profile editor and run viewer at http://127.0.0.1:8080/ui/.

See the target image guide for persistent storage, network isolation, builds, and HTTPS.

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

Research graph

zeroshot also includes an auto-research graph for ten bounded iterations of experiments with independent review of evidence, method, and progress. It keeps adopted, record-only, and aborted results under .zeroshot/research; add --push when each finalized iteration should be published.

zeroshot template list
zeroshot template show auto-research

See Execution for the research workflow's decision and evidence rules.

Community

• Discord: ask questions, share runs and graphs, and talk to the team.
• GitHub Issues: reproducible bugs and feature requests.

Reference

• Versioned documentation
• Get started
• CLI reference
• Target image guide
• Python SDK
• Cluster API reference
• Graph contract

Also check out: Opcore.

Development

npm ci
npm run check
cargo test --workspace # Unix; Windows: powershell -NoProfile -File scripts/test-windows.ps1

Node.js builds the static UI and supports repository tooling and npm delivery; Rust serves the UI. See UI development, CONTRIBUTING.md, PUBLISHING.md, and SECURITY.md.

License

MIT. See LICENSE.