Zeroshot

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. Failures route back into bounded repair. Delivery happens only after the graph's checks pass.

Delivery is explicit: keep work local, push the managed branch, prepare a mergeable PR, or ship it. PR and ship runs process visible GitHub feedback unless their delivery runtime binding opts out.

Zeroshot v8 is a hard interface cutover. The former Node.js runtime is retired; the native zeroshot executable is the product.

Install

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

The npm package 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. Native archives and checksums are attached to each canonical vX.Y.Z GitHub Release.

The graph is the orchestration

Agent loops hidden inside prompts are difficult to inspect, reproduce, or trust. Zeroshot makes the control flow authored data: sequence, parallel review, retry paths, delivery, and exit conditions are all explicit before a run starts.

The built-in software-change graph:

1. gives the goal to a worker;
2. runs acceptance and code review independently and in parallel;
3. routes rejected evidence to a repair worker and repeats both reviews;
4. with delivery enabled, delivers an accepted change through Git, CI, and merge;
5. routes delivery conflicts back through repair and review.

No runtime agent chooses the next step. The graph is the orchestration. Every transition is bounded, and every event is written to a durable SQLite ledger.

Inspect the built-ins or bring your own graph:

zeroshot template list
zeroshot template show software-change
zeroshot template show auto-research

auto-research runs ten bounded iterations. Explorer, synthesizer, and challenger scouts propose different ways to advance the charter. Evidence, method, and progress judges review the selected experiment. Unanimous adopt keeps its workspace changes; record_only preserves a supported negative or inconclusive result while restoring them, and abort rejects invalid or incomplete evidence. The graph keeps its charter, summary, backlog, state, iteration records, and reversible backups under .zeroshot/research. Its state and summary distinguish the retained workspace and known invariant status from the best historical findings. Run it without delivery to keep results local, or add --push to publish each finalized iteration. A one-time read-only graph preflight enforces the exact scout, judge, and experiment sets before the loop. Finalization and checkpoint audits fail closed, and a delivery repair request stops instead of bypassing review.

One CLI, three environments

The graph and runtime plan stay the same. Only the target changes.

Local: use your subscriptions

Run directly in your Git workspace. Local mode reuses an existing Codex or Claude Code login, including subscription-backed sessions; explicit provider credentials can be bound instead.

zeroshot run \
  --title "Add JSON output with tests" \
  --template software-change \
  --ship \
  --input ./input.json \
  --runtime-config ./runtime.json

Run zeroshot ui to edit profiles and inspect live or completed runs in your browser. Open http://127.0.0.1:4173/ui/. It shares the CLI's saved profiles and history; Ctrl-C stops the UI server while runs continue. Pass --target NAME to read history from a configured direct or hosted target while keeping profiles local. See UI setup.

Experimental: expose a saved local profile as an ACP agent. Each prompt runs the graph as a durable local run while the ACP session keeps the workspace and node sessions alive:

zeroshot acp --profile local:NAME

See Use a local graph as an ACP agent for the narrow preview contract.

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.

Zeroshot Cloud: close the laptop

Use the built-in cloud target at https://api.cloud.zeroshot.sh for a shared team queue and durable run history:

zeroshot target login cloud

Open the printed link to sign in with the device code already filled in. Use --target cloud when submitting runs.

When a failed run has a recoverable workspace, restart its graph on the latest saved files or choose an earlier node boundary:

zeroshot resume RUN_ID
zeroshot checkpoints RUN_ID
zeroshot resume RUN_ID --from-checkpoint CHECKPOINT_ID

Add --target NAME for Docker or Cloud. See Restart or resume a failed run for restore rules and retention.

Reference

• Versioned documentation
• Get started
• ACP agent preview
• CLI reference
• Standalone HTML CLI reference
• Distribution contract
• Target image guide
• Python SDK
• Cluster API reference
• OpenEngine graph contract

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.