The agent that wrote the code shouldn't be the one that says it works.
Independent executor–verifier orchestration for software changes.
Install
npm install -g @the-open-engine/zeroshot
zeroshot
Requires Node ≥ 22 and one supported provider. Guided setup detects installed providers, chooses a default, and configures worktree isolation for fresh repositories. Linux and macOS today; Windows is deferred.
This repository also contains Zeroshot Rust, the independent native product and zeroshot-rust
CLI. It has its own releases and self-hosted target image; see the
Markdown CLI reference,
standalone HTML CLI reference,
distribution contract, and
target image guide. The remainder of this README describes
the established Node product.
First run
cd your-repo
zeroshot run "Add a --json flag with tests"
In a git repository, the guided default runs in a separate worktree, so the current checkout is not edited. Use --no-isolation only when you explicitly want the run to modify the current checkout.
Observe the result from another terminal:
zeroshot list
zeroshot logs <id> -f
Unattended, 100× speed · 90-minute run · 5 iterations to approval.
How it works
Zeroshot drives a coding agent through an executor–verifier loop. A conductor sizes the workflow, an executor implements the change in an isolated workspace, and a separate verifier judges the observable result. Validators do not share the executor's session or reasoning context; they may receive explicit handoff artifacts and must reproduce reported failures. The loop continues until the change is verified or returns a concrete reason it is not.
Every step is written to a crash-safe SQLite ledger. Bring your own provider and backend: Zeroshot orchestrates their CLIs without storing provider keys.
One run: classify, execute, verify, and repeat when evidence fails.
Classification and routing
The conductor scores every task on complexity (TRIVIAL, SIMPLE, STANDARD, CRITICAL) and type (INQUIRY, TASK, DEBUG) before any code is written, and that score picks the workflow. A junior model runs the pass; when it can't call it, it answers UNCERTAIN and a senior model decides instead.
Rules are evaluated top down, first match wins:
| Classification | Workflow | Agents |
|---|---|---|
| DEBUG above TRIVIAL, any complexity | debug-workflow | investigator, fixer, tester, completion-detector |
TRIVIAL TASK or DEBUG, --pr/--ship | worker-validator | worker, 1 validator |
| TRIVIAL | single-worker | worker only, no validator |
| SIMPLE | worker-validator | worker, 1 validator |
| STANDARD | full-workflow | planner, worker, 2 validators |
| CRITICAL | full-workflow | planner, worker, meta-coordinator, 4 validators in two stages |
TRIVIAL is the row worth knowing about: one worker, no verifier, so the executor–verifier split doesn't apply on that path. CRITICAL is meant to be rare in the other direction, and the conductor is instructed to pick STANDARD whenever it's torn, since CRITICAL spends a senior model and four validators.
Custom workflows
Each workflow above is a JSON file in cluster-templates/base-templates/, and none of them is privileged. Underneath is a message bus: agents subscribe to topics, publish to topics, and the graph is that wiring.
zeroshot config list # available workflows
zeroshot config show full-workflow # read one
zeroshot config validate ./mine.json # check yours
zeroshot run 123 --config ./mine.json # run it
Agent ids, roles, and topic names are free strings, and a trigger can carry a JavaScript predicate deciding whether a message wakes its agent. Cycles are legal, reject-and-retry being one, though zeroshot config validate fails a ring of three or more unless something in it carries escape logic. Sub-clusters nest five deep.
Providers and issue sources
Provider engines come from the registry: Claude, Codex, bundled Gateway, Gemini, OpenCode, Pi, OMP, Kiro, and Copilot. Model gateways stay behind the single Gateway provider.
zeroshot providers
zeroshot providers set-default codex
zeroshot run 123 --provider gemini
Issue sources are auto-detected from repository context or explicit URLs: GitHub, GitLab, Jira, Azure DevOps, and Linear. Each source requires its own authenticated client where applicable. See docs/providers.md for provider installation, model levels, and credentials.
Isolation and delivery
Guided setup defaults fresh repositories to git worktree isolation. Delivery flags cascade: --ship implies --pr, which implies --worktree.
| Mode | Flag | Behavior |
|---|---|---|
| Git worktree | --worktree | isolated branch and checkout; guided default |
| Docker | --docker | container isolation for riskier workloads |
| Current checkout | --no-isolation | explicit escape hatch; modifies the active checkout |
| Pull request | --pr | worktree plus PR creation |
| Ship | --ship | worktree, PR, and merge after approval |
Command reference
zeroshot run <input> # issue, URL, markdown file, or inline text
zeroshot run 123 --docker # container isolation
zeroshot run 123 --pr # worktree + pull request
zeroshot run 123 --ship # worktree + PR + merge after approval
zeroshot run 123 --pr --pr-body $'## Summary\n\nCustom text\n\n{{issue_reference}}'
zeroshot run 123 -d # background run
zeroshot run 123 --config ./mine.json # custom workflow graph
zeroshot list # tasks and clusters (--json)
zeroshot status <id> # detailed status (--json)
zeroshot logs <id> -f # stream logs
zeroshot resume <id> [prompt] # resume a stopped or failed run
zeroshot stop <id> # graceful stop
zeroshot kill <id> # force stop
zeroshot export <id> --format trace --output run.trace.jsonl
zeroshot export <id> --format semantic --output run.semantic.jsonl
zeroshot providers # provider availability and defaults
zeroshot settings # effective settings
zeroshot agents list # available agents
zeroshot config list # workflow graphs (config show / config validate)
--pr-body supplies a deterministic pull-request body for --pr and --ship runs. The
template supports {{issue_number}}, {{issue_title}}, and {{issue_reference}}; all three
expand to empty text for tasks without an issue, so manual runs never emit Closes #unknown.
The unrendered template is retained for detached and resumed runs.
The trace export is a deterministic, provider-neutral research bundle. It preserves the ordered
cluster ledger, exact selected prompts, and exact raw task-log bytes without interpreting a Claude,
Codex, Pi, or other provider protocol. Missing evidence is recorded explicitly in its footer. File
exports are create-only: choose a new output path rather than replacing an existing bundle. Live
tasks are exported only as explicitly incomplete snapshots.
The separate semantic export runs those task bytes through Zeroshot's existing stateful provider
adapters and emits bounded text, thinking, tool_call, tool_result, and result events.
Zeroshot-owned wrapper and stderr records remain native-only. Parser diagnostics affect only
semantic completeness; they do not alter the native trace or run.
Docker credential configuration
Docker mounts and environment forwarding are explicit and provider-aware. Defaults include gh, git, and ssh; provider-specific authentication follows the registry contract.
zeroshot settings set dockerMounts '["gh","git","ssh","aws"]'
zeroshot run 123 --docker --mount ~/.aws:/root/.aws:ro
zeroshot run 123 --docker --no-mounts
See docs/providers.md for details.
Scope and status
Zeroshot performs best when a task has clear acceptance criteria. If you can't say what "done" means, an independent verifier can't confirm it.
| Task | Good fit? | Why |
|---|---|---|
| Add rate limiting (sliding window, per-IP, 429) | Yes | clear requirements |
| Refactor auth to JWT | Yes | defined end state |
| Fix a login bug | Yes | success is measurable |
| "Make the app faster" | No | needs exploration first |
| "Improve the codebase" | No | no acceptance criteria |
- Pre-1.0 in spirit. Interfaces still move between releases; pin your version. (The npm version auto-increments on every merge, so read it as a build counter, not a stability promise.)
- Crash-safe. All state persists to a SQLite ledger;
zeroshot resume <id>continues at any time. - No TUI in this release. Monitor with
zeroshot logs <id> -f,zeroshot list, andzeroshot status <id>.
Architecture, quality gates and command proofs
Zeroshot is a message-driven coordination layer: a conductor classifies each task by complexity and type, a workflow template selects agents and validators, agents publish results to a SQLite ledger, and validators approve or reject with specific findings.
- Required handoff quality gates: in
--pr/--shipflows, the git-pusher fails closed until every configured gate has fresh passing evidence. - Cmdproof: make expensive exact commands reusable across agents with
zeroshot cmdproof check <id>.
See CLAUDE.md for the cluster schema, primitives, and the conductor's classification model.
The Open Engine
Zeroshot is Layer 01 · Verification of The Open Engine, the open stack for autonomous software production. Generating code is easy; trusting it is not. The engine is layered because trust is layered:
| Layer | Status | |
|---|---|---|
| 01 | Verification: Zeroshot | This repo · open · shipping |
| 02 | Constraints: Opcore | Sibling · alpha |
| 03-05 | Intent · Context · Runtime | In development |
Zeroshot runs the loop: an agent writes the change, and independent verifiers decide whether it holds, approving it or rejecting it with the specific objections that blocked it. Opcore is the sibling layer, a deterministic, local, read-only constraints gate for coding agents. Zeroshot packages Opcore 0.2.1 and uses introduced-change validation so existing repository debt never blocks an otherwise clean change. Verification asks "does this meet the goal?"; constraints ask "is this within tolerance?"
Each layer ships the same way: extracted from the platform we run, then opened. Trust nothing. Verify everything.
Contributing
See CONTRIBUTING.md for development setup, CODE_OF_CONDUCT.md before participating, and SECURITY.md for security reports. More in docs/ and CLAUDE.md.
Questions and help: Discord.
License
MIT. The Open Engine Company.