Zeroshot
Zeroshot executes an explicit graph of software agents. Workers make changes; independent verifiers judge the evidence, and the graph decides when to repair or deliver. A successful run means the graph reached its declared outcome; it does not always mean a pull request was created or merged.
Use the connected server's tool schemas for MCP calls and installed CLI help for CLI commands.
Choose access
Keep execution target and transport separate. An explicit MCP or plugin request uses the connected
Zeroshot server; if disconnected, help the user connect it rather than switching to CLI or local
execution. An explicit CLI request, including --target platform, keeps native CLI login and needs
no MCP connection. Otherwise use the available access for the user's chosen target. Never turn a
Platform request into local execution because remote access is missing.
For MCP, use Shape the task and Platform through MCP below. The remaining command examples apply
to CLI access. Use the server's logical tool names; discover their client-qualified names instead
of assuming a prefix such as mcp__zeroshot__. If plugin and user-scope copies of this skill both
exist, follow one workflow and submit once.
Shape the task
Before submitting, inspect the request, repository guidance, existing issue, and enough code to know:
- the desired behavior and observable success;
- material constraints and behavior that must remain unchanged;
- whether a separate worker could implement it and a verifier could judge it.
Fill gaps from available evidence. Choose routine technical details without interrogating the user. If an unresolved product choice would materially change the outcome, propose the narrowest supported interpretation and ask one focused question. Do not submit while that decision remains unanswered. Suggest separate tasks only for independently useful outcomes or real prerequisites.
A browser chat has no implied checkout. Use repository context supplied by the host, attachments, or the user, and ask for missing evidence needed to shape the task. Do not claim to have inspected unavailable files or invent a source revision. A plan can remain a draft while execution waits for the required context.
When the work is vague or large enough to need agreed acceptance criteria, suggest planning it first
with the separate zeroshot-plan skill and let the user choose; do not start planning unasked. When
a plan file exists (.zeroshot/plans/<id>.md), use its Goal, Context, Acceptance criteria,
Constraints, Decided approach and Decisions as the task. Criteria marked Check (manual): need a
person or another environment: tell the run to list them rather than verify them. If the plan lists
depends_on, confirm with the user that those plans are built and merged before starting it, and
include any constraints they share that the plan does not repeat, or submit the dependent plans
together as a stack on Platform (see Submit a stack).
Never start a Zeroshot run merely because the skill is available. The user must ask to use Zeroshot. A worker already executing inside a Zeroshot run should perform its assigned work directly, not start another run. A failed Platform run does not authorize silently implementing the task locally.
Platform through MCP
- Prefer an existing profile. Use
list_profilesandget_profilein the intended user or org scope; inspect its input schema, runtime, and delivery behavior.get_authoring_catalogsupplies authoring schemas, templates, and workspace identity. If a graph needs changing, validate the concrete graph/runtime withvalidate_profile; usesave_profileonly when saving is requested. - Obtain the exact repository, branch, and committed revision, plus input matching the selected profile. The remote run receives that revision, not local uncommitted files. Confirm only unresolved source or delivery choices; a request to run an agreed profile already authorizes its agreed delivery. Never push missing source or change delivery merely to make submission work.
- Use
list_connectionsto check required named connections in the relevant scope. Missing provider credentials lead to Platform Connections, not secret values in chat or tool arguments.start_github_connectionandstart_github_installationreturn browser setup URLs when that setup is requested.check_connectionmay refresh stored credentials; it is not a read-only inspection. A saved environment can be inspected withget_environment; use the submission schema's concreteenvironmentor separateenvironmentRefwhen needed. - Submit with
submit_profile_runusingprofile: {scope, name}, title,initialInput, source, and a stable nonsecretsubmissionKey. Usesubmit_runfor a concrete validated graph/runtime when no saved profile fits. Its schema nests the authored definition undersubmission; do not wrap either tool in a genericrequestoraction. Run IDs may be omitted. Retain the complete submitted payload and key. If the response is lost, replay those identical values to recover the original run receipt; do not invent a new key or require a client-generated run ID. If replay cannot establish acceptance, report the uncertainty and stop rather than submitting new work. - Keep the returned
runId. Useget_run,wait_for_runwith its status cursor, andread_run_logswith its history cursor. Wait accepts at most 30 seconds; timeout or client disconnect leaves the run running. Read bounded history pages until the required output is available, keeping status, history, and checkpoint cursors separate. Report terminal outcome and observed delivery receipts; admission alone is not completion. list_run_checkpointsinspects recovery choices. Callresume_runonly for requested recovery, with the chosenfromselector and a fresh explicit UUIDv7successorRunId; retain both for identical retries. Generate the UUID with host tooling or use one supplied by the user; when neither is available, direct the user to Platform recovery. Never reuse the original run ID as its successor. Usestop_runordiscard_run_workspaceonly when the user intends that action.
The same server exposes typed environment and Memory operations. Before those writes, capture
workspace_id from get_authoring_catalog and supply current revisions where required; do not
guess them. Native organization and human-only Memory permissions still apply. Use each discovered
tool schema for its fields, and never send inline provider or Git credentials. MCP does not submit
stacks, resolve issue/PR URLs into pinned source, initialize local history, or expose ACP. Offer the
supported CLI path when the user asks for one of those workflows; do not claim remote support.
Choose the target
- Local execution omits
--target.--cwd DIRselects a folder (default: invoking folder); Git worktrees use their root. File arguments stay relative to the invoking folder. Runs without Git delivery need no repository. Keep workspace and active Zeroshot state disjoint; use an externalZEROSHOT_STATE_DIRwhen necessary. - Zeroshot Platform is built in. Sign in once with
zeroshot target login platform, then use--target platformexplicitly on Platform commands. Platform setup (organizations, GitHub App, connections) is documented at https://app.zeroshot.sh/docs. - Do not add or set up the built-in Platform target. Named targets store endpoints and login identity, not repository configuration.
Reuse profiles and connections
For a guided interview to design or revise a graph, use the zeroshot-graph-design skill.
Prefer a saved profile over inventing a graph or runtime. Inspect its input, runtime, and delivery behavior before constructing a run. Local profiles need no login; a local default profile applies when a run names no profile, graph, or runtime:
zeroshot profile list
zeroshot profile show NAME
zeroshot profile list --target platform --scope user
zeroshot profile list --target platform --scope org
zeroshot profile show NAME --target platform --scope org
zeroshot connection list --target platform --scope user
zeroshot connection list --target platform --scope org
Inspect saved profiles to see their delivery behavior. New software-change templates default to
pull-request delivery. Use --delivery none for local-only changes, --push for branch publication,
or --ship when merge delivery is intended. Custom graphs and saved profiles own their delivery.
Run locally without a profile
When no saved profile fits and the user has not asked for Platform, run the built-in
software-change graph locally. Its default publishes a PR. For local-only work, use
--delivery none as shown below; that mode needs only the harness's native login.
The worker edits the selected folder in place. Stop if it has uncommitted changes, and start from a fresh branch when the folder is a Git repository.
Write the shaped task to an input file outside the workspace, for example
{"task": "Add JSON output to the status command and cover it with focused tests."}.Write a uniform runtime file for the harness you are running in, with your own model identifier unless the user names another. Local Claude Code and Codex lanes reuse their native login:
{ "harness": "claude", "provider": "anthropic", "model": "MODEL_ID", "effort": "high" }{ "harness": "codex", "provider": "openai", "model": "MODEL_ID", "effort": "high" }Validate, then submit the same command without
--validate-only. This example keeps the work local; omit--delivery nonefor PR delivery, or use--shipwhen the user asks to merge:zeroshot run --title "TASK" --template software-change --delivery none \ --input INPUT.json --uniform-runtime-config RUNTIME.json --validate-onlyFollow the run with
zeroshot status RUN_IDandzeroshot logs RUN_ID. The user can watch it inzeroshot uiathttp://127.0.0.1:4173/ui/.Report what each reviewer rejected and what each repair changed, not only the final state. If the run exposed a gap the built-in reviewers do not cover, name one reviewer worth adding.
Offer to save the setup as the default, so later requests need no files:
zeroshot profile set NAME --template software-change --delivery none \ --uniform-runtime-config RUNTIME.json --default
Review an issue or pull request
The pr-review, code-review and issue-review templates post reports as comments by default.
PR review classifies whether reproduction is necessary, runs required full-stack checks (including
a browser for UI changes), then checks the diff and linked issue coverage. Its final report is concise. code-review takes the same PR input and runs parallel specialist reviewers whose verified findings become one comment. Both PR templates use comment delivery; issue review also supports --delivery none for a report without publication. Supply an issue or PR URL through --task-from, which resolves
title/body and pins source before execution:
zeroshot run --title "Review PR 123" --template pr-review \
--task-from https://github.com/OWNER/REPOSITORY/pull/123 \
--uniform-runtime-config RUNTIME.json --cwd /path/to/pr-checkout \
--submission-key review-pr-123
Use issue-review for an issue URL; its basic issue workflow is separate. PR intake captures linked
issue text before execution. Local reviews require clean tracked files and, for a PR, a checkout already at its head. Comment
publication uses the declared github.GH_TOKEN connection. Use --target platform for hosted source
preparation and credential resolution. With a saved review profile, use --profile instead of the
template/runtime/delivery flags. Validate first with --validate-only; retry uncertain submission
using the same key and configuration. A successful review may report defects; success confirms
publication. Ordinary --input FILE passes the graph's JSON input unchanged and excludes
--task-from. Worker nodes have no mandatory task field.
Adapt the graph
When the user wants to change what gets checked, start from the built-in graph rather than writing one from scratch:
Export it with
zeroshot template show software-change > graph.json.Make the change the user asked for: add a reviewer with one job (security, an end-to-end test that boots the app, design), or change the loop's
maxIterations. Different models or harnesses per node need a full--runtime-configplan instead of the uniform file. The review loop guide shows the node shapes and a cross-vendor plan.Validate by replacing
--template software-changewith--graph graph.jsonin the run command above, then run it.Save it so later requests use it, with
--runtime-config PLAN.jsonin place of the uniform file when nodes use different models or harnesses:zeroshot profile set NAME --graph graph.json \ --uniform-runtime-config RUNTIME.json --defaultWhen runs keep failing the same way, or a problem gets past the reviewers, suggest the reviewer that would catch it and ask before changing the graph.
Prepare the execution environment
Environments belong to a run, independently of its profile. A local:NAME profile can run on a
Docker target with its own environment. For Docker or Platform, pass
--environment environment.json with a flat definition such as:
{
"setup": "apt-get update && apt-get install -y jq",
"startup": "npm ci",
"variables": { "CI": "true" }
}
Platform resolves an omitted environment from the repository's User default, then Org default, then
Base. --no-environment bypasses defaults. Choose saved environments through Platform's UI or API;
the CLI accepts a concrete JSON file. Local runs use the invoking machine and reject setup/startup
and hook connections.
Setup runs as root before checkout or restoration, so it cannot read repository files. Startup runs as the workspace user in the checkout; workers and reviewers share its dependencies and services. Both hooks rerun on resume, so startup must tolerate existing workspace files. Checkpoints restore files and graph progress, not running services or agent conversations.
Put shared executables in $ZEROSHOT_TOOLS/bin and project dependencies in the workspace.
Snapshots include ignored directories such as target/ and node_modules/. Without cloning or
reflinks, allow space for another full workspace copy during staging, plus checkpoint storage.
Before large or parallel runs on tight disks, warn users and suggest cleaning build artifacts or
keeping generated directories outside the workspace where practical.
Shell exports do not persist between hooks or agents; use variables for nonsecret values and
connections for required secret field names. Hook connections and node connections are separate.
On a direct Docker target, root setup changes the container shared by its runs.
Preparation failures stop before agent execution without spending repair attempts. Inspect the failed phase and logs; fix the environment instead of requesting unrelated code repairs. Resume reuses the accepted definition, so an edited environment requires a new run. For a pinned Node installation and service/Docker conventions, see the environment guide.
Expose a profile over ACP
Start zeroshot acp only when the user explicitly asks to expose a Zeroshot graph as an ACP agent.
The experimental endpoint is local-only and owns stdio until its client disconnects:
zeroshot acp --profile local:NAME
Check the profile first. It must accept exactly one required string named task; every success node
must return exactly one required string named response. The runtime must use a registered local harness for
every node, and every executable node must have an agent binding with sessionScope: node_instance.
Maps, delivery, runtime connections, MCP servers, and session reload are unsupported.
Each ACP prompt is a separate durable local run. The outer ACP session keeps the workspace and
node provider sessions alive across prompts. Inspect the returned run ID with zeroshot status or
zeroshot logs; zeroshot ui includes the run in local history.
Validate and submit
Put profile input in a JSON file matching the profile's declared schema. Use a stable, non-secret submission key for safe retries:
zeroshot run --title "TASK" --profile org:NAME --input input.json \
--target platform --submission-key KEY --validate-only
zeroshot run --title "TASK" --profile org:NAME --input input.json \
--target platform --submission-key KEY
--validate-only materializes and validates without starting a run. A named Platform profile must
still be fetched from the target first, so this command requires Platform access. It does not prove
connection availability.
For named targets, --cwd selects the client Git checkout. Zeroshot prefers its attached upstream,
then a unique eligible HTTPS/SSH remote. Docker and Platform still require an exact committed Git
source. Detached worktrees require repository and branch overrides. --repository accepts GitHub
owner/name or a credential-free HTTPS/SSH clone URL. Override source only when needed:
--target platform --repository OWNER/REPOSITORY --branch BRANCH --revision SHA
Git push uses shared transport and needs no GitHub API. PR and merge require a registered forge;
GitHub is maintained today. --source-connection KEY authorizes source-only HTTPS
(GIT_USERNAME, GIT_PASSWORD) or pinned SSH (GIT_SSH_PRIVATE_KEY, GIT_SSH_KNOWN_HOSTS)
credentials. Generic forms require the target's openengine.git-transport/v1 capability.
Named targets receive the remote revision, not uncommitted files. Check dirty or unpushed work and never push or omit it without authorization. Confirm the exact repository, branch, revision, target, profile, and delivery intent reported for the run.
Submit a stack
A stack submits several dependent tasks to Platform at once, for example the stack manifest the
zeroshot-plan skill writes as .zeroshot/plans/<id>.stack.json. It is atomic and immutable: every
run uses one repository, base branch and profile, and needs decides which runs must succeed before
another starts without passing output between them. Submit one only when the user asks. The
manifest's delivery is required; when it is still a placeholder, ask the user to choose:
merge: each run merges into the base branch before the runs that need it start. The profile needs exactly one Git merge delivery node,merge@2ormerge@3(--shiptemplates usemerge@3).stacked_pull_requests: Zeroshot puts the runs in one line, in dependency order with ties broken by run name, and each run opens a pull request against the branch of the run before it. Nothing merges; the stack is done when every pull request is open. The profile needs exactly onepr@2delivery node, thesoftware-changedefault.
Agent bindings in the profile must not declare GH_TOKEN. Validate, show the user the printed order
for stacked pull requests, then submit with a stable key and follow it:
zeroshot stack validate STACK.json
zeroshot stack submit STACK.json --target platform --submission-key KEY
zeroshot stack status STACK_ID --target platform
zeroshot stack --help documents the manifest. Stacked pull requests are reviewed and merged from
the bottom up. GitHub moves a child pull request onto the base branch when its merged parent's
branch is deleted; a squash-merged parent, or a parent changed during review, leaves the pull
requests above it to rebase by hand. zeroshot stack force-stop stops every unfinished run; use it
only when the user intends to stop the stack.
Observe and troubleshoot
Keep the run ID and target:
zeroshot status RUN_ID --target platform
zeroshot watch RUN_ID --target platform
zeroshot logs RUN_ID --target platform
A foreground run streams events. Ctrl-C detaches observation without stopping the run. Use
zeroshot force-stop RUN_ID --target platform only when the user explicitly intends to stop it.
For command errors, check zeroshot --version and the relevant --help; do not revive removed
commands such as target setup. If login cannot retain credentials, fix the credential store before
requesting another device code; zeroshot target login --help lists the supported
ZEROSHOT_CREDENTIAL_STORE modes.
For connection_unavailable, list connections for the same target and both relevant scopes. A
static connection set replaces the whole named connection, so supply every required field through
repeated --field prompts or JSON stdin. Never put secret values in arguments, task files, runtime
configuration, issues, or logs.
After an uncertain submission response, reconcile by submission key before retrying. Do not create a second logical run. Report submitted, running, verified, delivered, failed, and stopped states accurately; submission alone is not completion.
Initialize Active Memory
For initialization or backfill from local run history, use the separate zeroshot-memory-init
skill. It orchestrates isolated discovery followed by graph and repository maintenance through the
resumable zeroshot memory init command.