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

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.

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 |

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 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, and zeroshot status <id>.

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/--ship flows, 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.