Run a first task

This example runs the built-in software-change graph in the current Git worktree, with pull-request and merge delivery disabled.

The worker edits the current worktree

Commit or stash work you want to protect, and run the command from the repository you intend to change.

1. Write the input

The template expects an object with a task string:

input.json

{
  "task": "Add JSON output to the status command and cover it with focused tests."
}

2. Choose the runtime

A uniform runtime applies one agent configuration to every agent node. Replace the model placeholder with an identifier accepted by the selected provider.

runtime.json

{
  "harness": "codex",
  "provider": "openai",
  "model": "YOUR_MODEL_ID",
  "effort": "high"
}

Zeroshot passes model identifiers to the provider unchanged and does not keep its own model catalog. For this local run, Zeroshot reuses the installed Codex CLI's login and provider configuration; no placeholder API key or openai connection is required. A Docker or cloud run instead derives the canonical OPENAI_API_KEY requirement and resolves it from the submission environment or the target's connection store because it cannot inherit host login state.

3. Check the request without starting it

--validate-only materializes the template and uniform runtime, then admits the request with its initial input. It does not contact a target or start a run.

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

Successful validation writes {"valid":true}. A rejected request names the input, graph, or runtime problem; the selected target checks connection availability later, when it receives the submission.

4. Start the run

Remove --validate-only:

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

The foreground command streams newline-delimited JSON while the run advances. Ctrl-C closes that stream without stopping the controller; another terminal can read the durable state:

zeroshot list
zeroshot status RUN_ID
zeroshot logs RUN_ID

For a graph view with node transcripts, open zeroshot ui and select the run in Runs.

Normal completion happens when the graph reaches a terminal node. An explicit zeroshot force-stop RUN_ID also closes the run, while engine or target failures can produce a terminal failure result.

Try the smaller template

single-worker has one agent node and no independent review loop:

zeroshot template show single-worker

zeroshot template show software-change prints the exact graph behind the first example as the same GraphSpec accepted by --graph and the Python SDK.

zeroshot template show auto-research prints the research graph with its default of ten iterations. Supply a positive options.iterations integer in the run input to set the admitted loop bound. It keeps adopted, record-only, and aborted results under .zeroshot/research; add --push to a run when every finalized iteration should be published.