- Notifications
You must be signed in to change notification settings - Fork98
Your autonomous engineering team in a CLI. Point Zeroshot at an issue, walk away, and return to production-grade code. Supports Claude Code, OpenAI Codex, OpenCode, and Gemini CLI.
License
covibes/zeroshot
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
🎉 New in v5.4: Now supportsOpenCode CLI! Use Claude, Codex, Gemini, or OpenCode as your AI provider. Also supportsGitHub, GitLab, Jira, and Azure DevOps as issue backends. SeeProviders andMulti-Platform Issue Support.
npm install -g @covibes/zeroshot
Demo (100x speed, 90-minute run, 5 iterations to approval)
Zeroshot is an open-source AI coding agent orchestration CLI that runs multi-agent workflows to autonomously implement, review, test, and verify code changes.
It runs aplanner, animplementer, and independentvalidators in isolated environments, looping until changes areverified orrejected with actionable, reproducible failures.
Built for tasks where correctness matters more than speed.
- Plan: translate a task into concrete acceptance criteria
- Implement: make changes in an isolated workspace (local, worktree, or Docker)
- Validate: run automated checks with independent validators
- Iterate: repeat until verified, or return actionable failures
- Resume: crash-safe state persisted for recovery
zeroshot run 123# GitHub issue numberzeroshot run feature.md# Markdown filezeroshot run"Add dark mode"# Inline text
Or describe a complex task inline:
zeroshot run"Add optimistic locking with automatic retry: when updating a user,retry with exponential backoff up to 3 times, merge non-conflicting field changes,and surface conflicts with details. Handle the ABA problem where version goes A->B->A."
| Approach | Writes Code | Runs Tests | Blind Validation | Iterates Until Verified |
|---|---|---|---|---|
| Chat-based assistant | ✅ | ❌ | ❌ | |
| Single coding agent | ✅ | ❌ | ||
| Zeroshot (multi-agent) | ✅ | ✅ | ✅ | ✅ |
- Autonomous AI code refactoring
- AI-powered pull request automation
- Automated bug fixing with validation
- Multi-agent code generation for software engineering
- Agentic coding workflows with blind validation
- Senior engineers who care about correctness and reproducibility
- Teams automating PR workflows and code review gates
- Infra/platform teams standardizing agentic workflows
- Open-source maintainers working through issue backlogs
- AI power users who want verification, not vibes
Platforms: Linux, macOS. Windows (native/WSL) is deferred while we harden reliability and multi-provider correctness.
npm install -g @covibes/zeroshot
Requires: Node 18+, at least one provider CLI (Claude Code, Codex, Gemini, Opencode).
# Install one or more providersnpm i -g @anthropic-ai/claude-codenpm i -g @openai/codexnpm i -g @google/gemini-cli# Opencode: see https://opencode.ai# Authenticate with the provider CLIclaude login# Claudecodex login# Codexgemini auth login# Geminiopencode auth login# Opencode# GitHub auth (for issue numbers)gh auth login
Zeroshot shells out to provider CLIs. Pick a default and override per run:
zeroshot providerszeroshot providers set-default codexzeroshot run 123 --provider gemini
Seedocs/providers.md for setup, model levels, and Docker mounts.
Single-agent sessions degrade. Context gets buried under thousands of tokens. The model optimizes for "done" over "correct."
Zeroshot fixes this with isolated agents that check each other's work. Validators can't lie about code they didn't write. Fail the check? Fix and retry until it actually works.
- Blind validation - Validators never see the worker's context or code history
- Repeatable workflows - Task complexity determines agent count and model selection
- Accept/reject loop - Rejections include actionable findings, not vague complaints
- Crash recovery - All state persisted to SQLite; resume anytime
- Isolation modes - None, git worktree, or Docker container
- Cost control - Model ceilings prevent runaway API spend
Zeroshot performs best when tasks have clear acceptance criteria.
| Scenario | Use | Why |
|---|---|---|
| Add rate limiting (sliding window, per-IP, 429) | Yes | Clear requirements |
| Refactor auth to JWT | Yes | Defined end state |
| Fix login bug | Yes | Success is measurable |
| Fix 2410 lint violations | Yes | Clear completion criteria |
| Make the app faster | No | Needs exploration first |
| Improve the codebase | No | No acceptance criteria |
| Figure out flaky tests | No | Exploratory |
Rule of thumb: if you cannot describe what "done" means, validators cannot verify it.
# Runzeroshot run 123# GitHub issuezeroshot run feature.md# Markdown filezeroshot run"Add dark mode"# Inline text# Isolationzeroshot run 123 --worktree# git worktreezeroshot run 123 --docker# container# Automation (--ship implies --pr implies --worktree)zeroshot run 123 --pr# worktree + create PRzeroshot run 123 --ship# PR + auto-merge on approval# Background modezeroshot run 123 -dzeroshot run 123 --ship -d# Controlzeroshot listzeroshot status<id>zeroshot logs<id> -fzeroshot resume<id>zeroshot stop<id>zeroshotkill<id>zeroshot watch# Providerszeroshot providerszeroshot providers set-default codex# Agent libraryzeroshot agents listzeroshot agents show<name># Maintenancezeroshot cleanzeroshot purge
Zeroshot works withGitHub, GitLab, Jira, and Azure DevOps. Just paste the issue URL or key.When working in a git repository, zeroshot automatically detects the issue provider from your git remote URL. No configuration needed!
# GitHubzeroshot run 123zeroshot run https://github.com/org/repo/issues/123# GitLab (cloud and self-hosted)zeroshot run https://gitlab.com/org/repo/-/issues/456zeroshot run https://gitlab.mycompany.com/org/repo/-/issues/789# Jirazeroshot run PROJ-789zeroshot run https://company.atlassian.net/browse/PROJ-789# Azure DevOpszeroshot run https://dev.azure.com/org/project/_workitems/edit/999
Requires: CLI tools (gh,glab,jira, oraz) for the platform you use. Seeissue-providers README for setup and self-hosted instances.
Important for--pr mode: Run zeroshot from the target repository directory. PRs are created on the git remote of your current directory. If you run from a different repo, zeroshot will warn you and skip the "Closes #X" reference (the PR is still created, but won't auto-close the issue).
Zeroshot is a message-driven coordination layer with smart defaults.
- The conductor classifies tasks by complexity and type.
- A workflow template selects agents and validators.
- Agents publish results to a SQLite ledger.
- Validators approve or reject with specific findings.
- Rejections route back to the worker for fixes.
┌─────────────────┐ │ TASK │ └────────┬────────┘ │ ▼ ┌────────────────────────────────────────────┐ │ CONDUCTOR │ │ Complexity × TaskType → Workflow │ └────────────────────────┬───────────────────┘ │ ┌─────────────────────────────┼─────────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ TRIVIAL │ │ SIMPLE │ │ STANDARD+ │ │ 1 agent │──────────▶ │ worker │ │ planner │ │ (level1) │ COMPLETE │ + 1 valid.│ │ + worker │ │ no valid. │ └─────┬─────┘ │ + 3-5 val.│ └───────────┘ │ └─────┬─────┘ ▼ │ ┌─────────────┐ ▼ ┌──▶│ WORKER │ ┌─────────────┐ │ └──────┬──────┘ │ PLANNER │ │ │ └──────┬──────┘ │ ▼ │ │ ┌─────────────────────┐ ▼ │ │ ✓ validator │ ┌─────────────┐ │ │ (generic check) │ ┌──▶│ WORKER │ │ └──────────┬──────────┘ │ └──────┬──────┘ │ REJECT │ ALL OK │ │ └──────────────┘ │ │ ▼ │ │ ┌──────────────────────┐ │ │ │ ✓ requirements │ │ │ │ ✓ code (STANDARD+) │ │ │ │ ✓ security (CRIT) │ │ │ │ ✓ tester (CRIT) │ │ │ │ ✓ adversarial │ │ │ │ (real execution) │ │ │ └──────────┬───────────┘ │ │ REJECT │ ALL OK │ └──────────────┘ │ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ COMPLETE │ └─────────────────────────────────────────────────────────────────────────────┘| Task | Complexity | Agents | Validators |
|---|---|---|---|
| Fix typo in README | TRIVIAL | 1 | None |
| Add dark mode toggle | SIMPLE | 2 | Generic validator |
| Refactor auth system | STANDARD | 4 | Requirements, code |
| Implement payment flow | CRITICAL | 7 | Requirements, code, security, tester, adversarial |
| Complexity | Planner | Worker | Validators |
|---|---|---|---|
| TRIVIAL | - | level1 | - |
| SIMPLE | - | level2 | 1 (level2) |
| STANDARD | level2 | level2 | 2 (level2) |
| CRITICAL | level3 | level2 | 5 (level2) |
Levels map to provider-specific models. Configure withzeroshot providers setup <provider> orsettings.providerSettings. (LegacymaxModel applies to Claude only.)
Custom Workflows (Framework Mode)
Zeroshot is message-driven, so you can define any agent topology.
- Expert panels: parallel specialists -> aggregator -> decision
- Staged gates: sequential validators, each with veto power
- Hierarchical: supervisor dynamically spawns workers
- Dynamic: conductor adds agents mid-execution
Coordination primitives:
- Message bus (pub/sub topics)
- Triggers (wake agents on conditions)
- Ledger (SQLite, crash recovery)
- Dynamic spawning (CLUSTER_OPERATIONS)
Start your provider CLI and describe your cluster:
Create a zeroshot cluster config for security-critical features:1. Implementation agent (level2) implements the feature2. FOUR parallel validators: - Security validator: OWASP checks, SQL injection, XSS, CSRF - Performance validator: No N+1 queries, proper indexing - Privacy validator: GDPR compliance, data minimization - Code reviewer: General code quality3. ALL validators must approve before merge4. If ANY validator rejects, implementation agent fixes and resubmits5. Use level3 for security validator (highest stakes)Look at cluster-templates/base-templates/full-workflow.jsonand create a similar cluster. Save to cluster-templates/security-review.jsonBuilt-in validation checks for missing triggers, deadlocks, and invalid type wiring before running.
SeeCLAUDE.md for the cluster schema and examples.
All state is persisted in the SQLite ledger. You can resume at any time:
zeroshot resume cluster-bold-panther
zeroshot run 123 --worktree
Lightweight isolation using git worktree. Creates a separate working directory with its own branch. Auto-enabled with--pr and--ship.
zeroshot run 123 --docker
Full isolation in a fresh container. Your workspace stays untouched. Useful for risky experiments or parallel runs.
| Scenario | Recommended |
|---|---|
| Quick task, review changes yourself | No isolation (default) |
| PR workflow, code review | --worktree or--pr |
| Risky experiment, might break things | --docker |
| Running multiple tasks in parallel | --docker |
| Full automation, no review needed | --ship |
Default behavior: Agents modify files only; they do not commit or push unless using an isolation mode that explicitly allows it.
Docker Credential Mounts
When using--docker, zeroshot mounts credential directories so agents can access provider CLIs and tools like AWS, Azure, and kubectl.
Default mounts:gh,git,ssh (GitHub CLI, git config, SSH keys)
Available presets:gh,git,ssh,aws,azure,kube,terraform,gcloud,claude,codex,gemini
# Configure via settings (persistent)zeroshot settingsset dockerMounts'["gh", "git", "ssh", "aws", "azure"]'# View current configzeroshot settings get dockerMounts# Per-run overridezeroshot run 123 --docker --mount~/.aws:/root/.aws:ro# Provider credentialszeroshot run 123 --docker --mount~/.config/codex:/home/node/.config/codex:rozeroshot run 123 --docker --mount~/.config/gemini:/home/node/.config/gemini:ro# Disable all mountszeroshot run 123 --docker --no-mounts# CI: env var overrideZEROSHOT_DOCKER_MOUNTS='["aws","azure"]' zeroshot run 123 --docker
Seedocs/providers.md for provider CLI setup and mount details.
Custom mounts (mix presets with explicit paths):
zeroshot settingsset dockerMounts'[ "gh", "git", {"host": "~/.myconfig", "container": "$HOME/.myconfig", "readonly": true}]'
Container home: Presets use$HOME placeholder. Default:/root. Override with:
zeroshot settingsset dockerContainerHome'/home/node'# Or per-run:zeroshot run 123 --docker --container-home /home/node
Env var passthrough: Presets auto-pass related env vars (for example,aws ->AWS_REGION,AWS_PROFILE). Add custom:
zeroshot settingsset dockerEnvPassthrough'["MY_API_KEY", "TF_VAR_*"]'
- CLAUDE.md - Architecture, cluster config schema, agent primitives
docs/providers.md- Provider setup, model levels, and Docker mountsdocs/context-management.md- Context selection, context packs, and state snapshots- Discord - Support and community
zeroshot export <id>- Export conversation to markdownsqlite3 ~/.zeroshot/*.db- Direct ledger access for debugging
Troubleshooting
| Issue | Fix |
|---|---|
claude: command not found | npm i -g @anthropic-ai/claude-code && claude auth login |
codex: command not found | npm i -g @openai/codex && codex login |
gemini: command not found | npm i -g @google/gemini-cli && gemini auth login |
gh: command not found | Install GitHub CLI |
--docker fails | Docker must be running:docker ps to verify |
| Cluster stuck | zeroshot resume <id> to continue |
| Agent keeps failing | Checkzeroshot logs <id> for actual error |
zeroshot: command not found | npm install -g @covibes/zeroshot |
| Agents misbehave | /analyze-cluster-postmortem <id> in Claude Code (creates issue if fix is generalizable) |
SeeCONTRIBUTING.md for development setup and guidelines.
Please readCODE_OF_CONDUCT.md before participating.
For security issues, seeSECURITY.md.
Ratatui (Rust) is the only supported TUI. Entry points:
zeroshot(TTY + no args)zeroshot tuizeroshot watch
The Rust TUI spawns a Node backend over stdio. Run both while iterating.
Single command dev loop (auto-rebuild + restart):
cargo install cargo-watchnpm run dev:tui
Install deps
npm ci
Build the TUI backend in watch mode
npm run build:tui-backend -- --watch# ornpx tsc -p tsconfig.tui-backend.json -wRun the Rust TUI (second terminal)
cd tui-rscargo run -p zeroshot-tui -- --ui disruptive
If you wantzeroshot to run from the dev branch globally:
npm run dev:link
One command to link + run the TUI dev loop:
npm run dev:bootstrap
Use the Node CLI to launch your local Rust binary:
cd tui-rscargo build -p zeroshot-tuicd ..ZEROSHOT_TUI_BINARY_PATH="$PWD/tui-rs/target/debug/zeroshot-tui" node cli/index.js tui
ZEROSHOT_TUI_BACKEND_PATHpoints to a specificlib/tui-backend/server.jsZEROSHOT_TUI_BINARY_PATHpoints to a local Rust binaryZEROSHOT_TUI_UI=classic|disruptiveforces UI variant
MIT -Covibes
Built onClaude Code by Anthropic.
About
Your autonomous engineering team in a CLI. Point Zeroshot at an issue, walk away, and return to production-grade code. Supports Claude Code, OpenAI Codex, OpenCode, and Gemini CLI.
Topics
Resources
License
Code of conduct
Contributing
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Contributors7
Uh oh!
There was an error while loading.Please reload this page.