zeroshot

Stop babysitting your agents.

Prompts are suggestions. Graphs are enforced.

zeroshot runs coding, independent review and repairs through the workflow you define.

Choose the agents and models, define what must pass, and decide where rejected work goes for repair.

For example, give a security reviewer the job of checking that users cannot access another account’s data. A rejection sends its findings back to the worker for repair, followed by another review. Save that workflow as a profile and reuse it.

The engine enforces the graph’s review gates and retry limits. Each agent can use its own model and harness (Pi, Claude Code, Codex or Copilot).

On 20 ProgramBench tasks, a small model in a review loop matched a larger model's score at a median 58% of its cost.

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

Example custom workflow. Explore the interactive graphs.

Get started

Run locally

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

Paste this into Claude Code or Codex in your repo:

Use the zeroshot skill to set up a local run for a small issue in this repo.
Work on a fresh branch and stop if there are uncommitted changes.
Show me the task and workflow before starting.
Once I approve, run it, monitor progress, and summarize the result.

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, Pi, and Claude Code at user scope.

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

Run directly from the CLI

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 with a task 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. A failed run with a recoverable workspace can be restarted or resumed.

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 →

Build your own graph

Choose each agent's model and instructions, which steps run in parallel, and when to retry. This example routes changes to auth, payments, or migrations through a blast-radius map and security review before acceptance and code review. Other changes go straight to review.

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

Start with Build a review loop, a complete example with two independent reviewers and a repair loop. Adapt the reviewers’ instructions to your project. See the graph contract for supported graph structures 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.

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. For shared team configurations, see organization profiles.

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 returns to the same 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.

The graph keeps adopted, record-only, and aborted results under .zeroshot/research; add --push when each finalized iteration should be published. Inspect it with zeroshot template show auto-research, and see Execution for the research workflow's decision and evidence rules.

Choose delivery and execution

Runs keep the work local unless you pass a delivery flag:

Delivery	Behavior
No delivery 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

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. Local GitHub PR and ship runs also need the GitHub CLI (gh) on PATH. 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, GitHub Copilot, and Pi 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.

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

Opcore gives coding agents feedback on each edit while they write code.

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.