zeroshot – Automated AI‑agent coding & review pipelines

What it is – zeroshot is a CLI‑driven engine that lets you orchestrate AI coding agents (Codex, Claude Code, GitHub Copilot, Pi, etc.) in a graph of review, repair, and delivery steps. You define a workflow (a directed graph) that specifies which agent does the work, which independent reviewers must approve it, how many retries are allowed, and what happens to rejected output. The engine enforces the graph at runtime, records everything in a SQLite ledger, and can run locally, in Docker, or via the hosted zeroshot Cloud.

---

Core concepts

Concept	What it does
Agent / Harness	A coding model (e.g., OpenAI Codex, Anthropic Claude, GitHub Copilot, Pi) that actually writes or modifies code.
Graph	A declarative workflow describing nodes (worker, reviewers, testers, delivery) and edges (pass/fail routes, retry limits).
Profile	Saved combination of a graph + per‑node runtime configuration (model, effort level, session scope).
RuntimePlan	JSON that tells each node which model to use, how much effort, and any node‑specific options.
Delivery flags	--push, --pr, --ship control whether the result stays local, is pushed to a branch, opened as a PR, or merged after CI.
Ledger	Durable SQLite DB (.zeroshot/) that logs every event, decision, and artifact for auditability.

---

Key features (as described in the README)

• Independent review loops – Workers produce code, then one or more reviewers run in parallel. Rejections are automatically routed back to the worker with feedback for repair.
• Model‑per‑node flexibility – Each node can use a different LLM provider and size; you can mix Codex, Claude, Copilot, etc.
• Retry limits & bounded runs – The graph can specify how many times a node may be retried before the whole run is considered failed.
• Built‑in templates – software-change, auto-research, and others provide ready‑made graphs for common tasks.
• Self‑hosted Docker target – Run the engine and its state on your own infrastructure via the zeroshot-target container.
• Local UI – zeroshot ui starts a web UI (default http://127.0.0.1:4173/ui/) to monitor runs, view logs, and edit profiles.
• CLI‑first workflow – All actions (run, list, status, logs, template show) are available from the command line.
• Open‑source, MIT‑licensed – The core engine, UI, and a Python SDK are released under MIT.

---

Typical use cases

1. Automated code change with safety gates – A developer asks an LLM to implement a feature; the engine runs security, acceptance, and code‑review agents before committing.
2. Research loops – The auto‑research template runs multiple “scout → planner → judge” iterations to explore solutions, automatically archiving successful candidates.
3. Team‑wide review policies – Organizations can encode mandatory review steps (e.g., security audit + UI audit) and enforce them for every AI‑generated change.
4. Cost‑effective scaling – Small, cheap models can be placed in a review loop to achieve the quality of larger models at lower expense (as shown on ProgramBench tasks).
5. Self‑hosted CI for regulated environments – Run the Docker target inside a secure network, keeping all code and logs on‑premises.

---

Getting started (quick‑start)

# Install the CLI globally (requires Node 18+)
npm install -g @the-open-engine-company/zeroshot

1. Create a task description – input.json with a task field.
2. Define a runtime – runtime.json that selects a harness (e.g., codex) and model ID.
3. Run –

   zeroshot run \
     --title "Add JSON status output" \
     --template software-change \
     --input input.json \
     --uniform-runtime-config runtime.json
   

4. Watch progress – Open another terminal and run zeroshot ui (or visit http://127.0.0.1:4173/ui/).
5. Optional delivery – add --push, --pr, or --ship to push the changes to a remote repo.

For cloud usage, connect GitHub and supply your model API keys via the Zeroshot Cloud UI.

---

Architecture snapshot

• CLI (Node.js) – parses commands, builds the run plan, launches the native engine, serves the UI.
• Native engine (Rust) – executes the graph, talks to model harness CLIs, writes to the SQLite ledger, and runs the Docker target when self‑hosted.
• Harness CLIs – thin wrappers around Codex, Claude, Copilot, Pi that expose a uniform API for the engine.
• Python SDK – allows programmatic interaction with the cluster API (not covered in the README but listed).

---

Community & support

• Discord community, GitHub issues, and a public road‑map.
• Documentation site: https://zeroshot.sh/docs/
• Self‑hosted Docker image: ghcr.io/the-open-engine/zeroshot-target:latest.

---

License

MIT – see the repository’s LICENSE file.