Parallel Works
View as Markdown
Share:

Non-Interactive Mode

With the -p (--prompt) flag, pw code runs a single prompt to completion and exits (these docs also call this a one-shot run): no full-screen interface, no follow-up questions. This is the mode to use in scripts, CI jobs, and anywhere you want the agent's answer as program output.

pw code -p "find all TODO comments" owner:provider-name/model-name

A model is required in one-shot mode. Pass it as the positional argument or with -m. Organization provider models also require --allocation (there is no picker to fall back to). List available model IDs with pw ai models ls.

Press Ctrl+C to cancel a run in flight.

What Goes to stdout vs. stderr

In the default text output, the streams are separated so the result stays clean:

  • stdout carries only the model's answer, streamed as it is generated.
  • stderr carries everything else: tool activity as it happens (a ● ToolName(...) line per call with a condensed result line beneath it), the final usage summary, and the session/resume hint.

That means command substitution and pipes capture just the answer:

RESULT=$(pw code -p "summarize the changes in HEAD in one sentence" owner:provider-name/model-name)
echo "$RESULT"

Add 2>/dev/null to silence the progress output entirely, or 2>progress.log to keep it. Progress lines are colorized only when stderr is a terminal, so redirected logs never contain escape codes.

JSON Output

Pass -o json to get a single structured result object on stdout instead of streamed text (no progress is printed for the answer itself in this mode):

pw code -p "list the Go files in this repo" -o json owner:provider-name/model-name
{
  "message": "The repository contains ...",
  "model": "owner:provider-name/model-name",
  "session_id": "20260719-153045-a1b2c3d4",
  "iterations": 4,
  "usage": {
    "input_tokens": 18000,
    "output_tokens": 1200,
    "total_tokens": 19200
  },
  "estimated_cost": "$0.0480"
}
FieldDescription
messageThe model's final answer.
modelThe model ID the run used.
session_idThe local session ID, usable with pw code -r.
iterationsHow many model requests the agent loop made to finish the prompt.
usage.input_tokensTotal input (prompt) tokens across the run.
usage.output_tokensTotal output (completion) tokens across the run.
usage.total_tokensInput plus output tokens.
estimated_costEstimated cost as a dollar string, e.g. "$0.0480", based on platform-configured model rates.

Extract fields with jq:

pw code -p "how many source files are in src/?" -o json owner:provider-name/model-name \
  | jq -r '.message, .estimated_cost'

Permissions in One-Shot Runs

One-shot runs use the same permission modes as interactive sessions, but there is no one to answer a prompt: any action that would normally ask for approval is denied automatically (it fails closed). The agent sees the denial and continues, working around the restriction or reporting it in its answer.

The same applies to workspace configuration: a one-shot run never prompts to approve a workspace's settings, MCP servers, commands, or agent definitions, so unapproved files are ignored with a notice on stderr. Launch pw code interactively once to approve them. See Workspace Trust.

For scripting, that means:

  • --permission-mode read-only is the safe choice for analysis and question-answering runs.
  • The default accept-edits mode auto-approves file edits inside the workspace, but shell commands that would normally prompt are denied unless pre-approved.
  • --allowedTools pre-approves specific tools or commands, e.g. --allowedTools 'Bash(git status:*)',ReadFile.
  • --permission-mode bypass-permissions runs every tool without prompting.

bypass-permissions runs everything

bypass-permissions gives the agent unrestricted tool access, including arbitrary shell commands. Use it only in environments where that is acceptable, such as a disposable CI container.

Subagents in One-Shot Runs

The agent may delegate parts of the prompt to subagents. In non-interactive mode, subagents always run inline: requests to run a task in the background are forced to block until the task finishes, so no work is lost when the process exits.

  • Progress on stderr is coarse: one ● Task(...)-style start line naming the subagent and its task, and one condensed result line when it completes. The subagent's individual tool calls are not streamed.
  • Permission-gated commands a subagent runs fail closed, just like the main agent's.
  • The JSON output contains only aggregate usage: subagent tokens and cost roll up into the run's usage and estimated_cost totals, and there is no per-subagent breakdown field.

Resuming a One-Shot Session

Every one-shot run is saved as a local session. In text mode, stderr ends with the session ID and a ready-to-run resume command:

Session: 20260719-153045-a1b2c3d4
Resume:  pw code -r 20260719-153045-a1b2c3d4 -m owner:provider-name/model-name

Run that command to reopen the conversation interactively, with the one-shot exchange as history. The reverse also works: combine -r with -p to continue a saved session with another non-interactive prompt, or use -r latest for the most recent session. See Sessions & Resume.

Related Documentation