Zeroshot: A CLI That Splits Coding Agent Work Into Executor and Verifier Roles

The Problem: The Author Should Not Be the Reviewer

Most agentic coding tools run a single model that writes code and then declares it done. Zeroshot addresses the obvious conflict: the agent that wrote the code shouldn't be the one that says it works. The project targets engineers who want to delegate a change to an autonomous system but still trust the result in production. It is aimed at teams already using Claude Code, OpenAI Codex, OpenCode, or Gemini CLI, because Zeroshot orchestrates those existing CLIs rather than replacing them. The README frames the core value as independent executor-verifier orchestration, where a separate verifier judges the observable result without sharing the executor's session or reasoning context.

The Executor-Verifier Loop and Its Conductor

Zeroshot runs a conductor that sizes the workflow before any code is written. The conductor scores each task on complexity, TRIVIAL, SIMPLE, STANDARD, or CRITICAL, and on type, INQUIRY, TASK, or DEBUG. That score picks a workflow. A junior model attempts the classification first; if it cannot decide, it answers UNCERTAIN and a senior model takes over. The workflow then drives an executor to implement 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 repeats until the change is verified or the verifier returns a concrete reason it is not. Every step is written to a crash-safe SQLite ledger, which gives you an audit trail of the entire run.

Classification Table: Where Verification Gets Skipped

The README includes a classification table that is the heart of the design. DEBUG tasks above TRIVIAL complexity go to a debug-workflow with investigator, fixer, tester, and completion-detector agents. TRIVIAL TASK or DEBUG with --pr or --ship flags uses a worker-validator pair. TRIVIAL without those flags uses a single worker with no validator at all. SIMPLE uses worker-validator. STANDARD uses a planner, worker, and two validators. CRITICAL uses a planner, worker, meta-coordinator, and four validators in two stages. The TRIVIAL path is the row worth knowing about: one worker, no verifier, so the executor-verifier split does not apply. The conductor is instructed to pick STANDARD whenever it is torn between STANDARD and CRITICAL, because CRITICAL spends a senior model and four validators. That bias toward STANDARD keeps costs predictable but means the most expensive workflow is rare by design.

Workflows Are Just JSON Files on a Message Bus

Each workflow is a JSON file under cluster-templates/base-templates/, and none of them is privileged. Underneath is a message bus where agents subscribe to topics, publish to topics, and the graph is that wiring. 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, including reject-and-retry, though zeroshot config validate fails a ring of three or more unless something in it carries escape logic. Sub-clusters nest five deep. You can list workflows with zeroshot config list, read one with zeroshot config show full-workflow, validate a custom file with zeroshot config validate ./mine.json, and run a task against it with zeroshot run 123 --config ./mine.json. This is a genuinely extensible design, but it means you need to understand the JSON schema and the topic wiring before you can meaningfully customize a workflow.

Getting Started: Install, First Run, and Isolation

Installation is a global npm package: npm install -g @the-open-engine/zeroshot, then run zeroshot. It requires Node 22 or higher and one supported provider. Guided setup detects installed providers, chooses a default, and configures worktree isolation for fresh repositories. Linux and macOS are supported today; Windows is deferred. The first run in a git repository uses a separate worktree by default, so the current checkout is not edited. Use --no-isolation only when you explicitly want the run to modify the current checkout. You can observe progress from another terminal with zeroshot list and zeroshot logs <id> -f. The README claims an unattended run can be 100 times faster than manual work, with a 90-minute run and 5 iterations to approval, but that is a marketing claim from the project, not something I can verify from the material.

Providers, Issue Sources, and Delivery Modes

Provider engines come from a registry: Claude, Codex, bundled Gateway, Gemini, OpenCode, Pi, OMP, Kiro, and Copilot. Model gateways stay behind the single Gateway provider. You can list providers with zeroshot providers, set a default with zeroshot providers set-default codex, or override per run with 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. Delivery flags cascade: --ship implies --pr, which implies --worktree. Git worktree isolation is the guided default, Docker isolation is available with --docker for riskier workloads. The README is truncated before detailing the full delivery modes, so I cannot confirm the exact Docker flag semantics beyond the table shown.

Limitations and Wrong-Tool Cases

The most obvious limitation is the TRIVIAL path: it has no verifier, so the core value proposition does not apply to simple tasks. If your work is mostly small, mechanical edits, Zeroshot adds overhead without the independent review benefit. Windows is deferred, so any Windows-based team cannot use it today. The project requires a supported provider CLI installed and authenticated, so you are dependent on external tools. The README mentions a bundled Gateway provider but does not explain what it does beyond being a model gateway. Custom workflows require understanding the JSON schema and message-bus wiring, which is a learning curve. Also, the project hosts a separate Rust product called Zeroshot Rust with its own CLI and releases, but the README focuses on the Node product, so you need to check which one you are installing if you see two releases.

Alternatives and Maintenance Considerations

A direct alternative is running a single agent like Claude Code or Codex directly without Zeroshot. That approach is simpler, cheaper, and faster for trivial tasks, but it lacks the independent verifier loop and the SQLite audit trail. Another alternative is a CI-based review system where a human or a separate model reviews pull requests, but that is asynchronous and does not force the verifier to reproduce failures in the same loop. Zeroshot's approach is to embed verification into the agent loop itself, which is a meaningful difference. On maintenance: the project is MIT licensed, which is permissive. The README shows active releases, with v6.45.0 and v6.44.0 in August 2026, and a separate Rust release. The Node product requires Node 22, so you must keep your runtime current. The workflow JSON files are versioned with the repo, so upgrading may change default workflows. The crash-safe SQLite ledger is a plus for debugging, but you should verify the ledger schema stability if you plan to rely on it long-term.

Editorial conclusion

Adopt Zeroshot if you want a configurable, provider-agnostic agent loop that separates implementation from verification, and you can accept the overhead of multiple model calls per task. Skip it if your tasks are trivial enough that a single worker without review is acceptable, or if you need Windows support today. Before adopting, verify that your provider CLI is installed and authenticated, test the guided worktree isolation on a non-critical repo, and inspect the workflow JSON files under cluster-templates/base-templates to confirm the validator prompts match your quality bar. The project's own README admits TRIVIAL tasks get no verifier, so you must decide where that line sits for your codebase.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes