One-shot mode runs a selected set of tasks through your AI provider. You can select a hosted project board or an accepted local plan. Local plan execution does not require a SwarmCraft account.
For hosted boards, it prepares the repository, runs selected board tasks through the shared packet contract, syncs supported updates, and moves accepted work to done by default.
Choose it for a controlled, bounded terminal run. Use VS Code delivery when a person should guide each task through separate implementation, checking, and review stages.
If you prefer to start from VS Code, run SwarmCraft: Run One-Shot with CLI after the CLI is installed and signed in. VS Code launches the same swarmcraft one-shot command and records the manifest path in the SwarmCraft output channel.
Complete the Node.js/npm and CLI prerequisites, including native PowerShell instructions on Windows. The extension checks CLI readiness before one-shot launch; CLI account authentication and AI-provider configuration remain separate.
Install and verify the CLI
You need Node.js 20.19 or newer, npm, Git, a local Git repository, and a supported AI agent command on PATH. Hosted board execution also requires a SwarmCraft account. Install the published package, then verify it:
npm install -g @swarmcraftai/cli
swarmcraft --help
For hosted board execution, sign in without putting a password or step-up code in the command itself:
swarmcraft auth login
In your browser: sign in with the same method you used for your SwarmCraft account, such as Google, then choose Approve sign-in. Return to the terminal and check that it says Signed in as with your email address.
If the browser does not open, use the link printed in the terminal. You can also run swarmcraft auth login --no-browser to open the link yourself. For a SwarmCraft email/password account, swarmcraft auth login --method password keeps login in the terminal; your Google password is not a SwarmCraft password.
Back in the terminal, from the intended repository, check the API, Git workspace, runtime, and agent provider:
swarmcraft doctor --workspace . --agent-provider codex
swarmcraft projects list
swarmcraft init --project <project-id> --workspace . --agent-provider codex
Choose --agent-provider codex for Codex CLI, --agent-provider copilot for GitHub Copilot CLI, or --agent-provider claude for Claude Code CLI. Install and sign in to your chosen CLI using Set up your AI provider before running tasks.
Use --agent-provider managed only when the quote is shown and you deliberately choose Managed AI. Managed AI sends delivery calls through SwarmCraft and pays for their AI usage from your SwarmCraft credit balance. See How SwarmCraft credits and AI usage work for how credits are reserved and charged.
During a run, the CLI prints task and stage progress. Agent output is written under:
.swarmcraft/runs/<run-id>/logs/
Upgrade an existing repository's guidance
Updating the CLI does not automatically update files already seeded into your repo. With CLI 0.7.1 or later, you can update those workflow files without signing in or running an agent.
In your terminal, from the project repository:
- Run
swarmcraft upgrade --workspace . --checkand review the listed changes. - Run
swarmcraft upgrade --workspace .to apply them. - Review the result and
git diff, resolve any preserved conflicts, then commit the changes you accept. Exit 2 means conflicts remain; exit 1 means a blocker or failure.
Upgrade keeps the repo's saved AI provider, owner files such as CLAUDE.md, and locally
edited managed guidance. It updates unchanged static guidance and unfinished/provisional
packet metadata while preserving progress. Completed packets and server-derived project
context remain unchanged by default. Use --include-completed only when you also want
to migrate completed packet metadata.
Upgrade does not change the project board or create Git commits. Optional sync from a
running extension is separate. In VS Code, SwarmCraft: Update Repo Guidance offers
the same project upgrade with a preview. Operate repositories use swarmcraft operate upgrade --workspace . --check instead. Run swarmcraft upgrade --help for preservation
and recovery details; help itself never signs in or executes the command.
Start from a clean repository
Commit or stash unrelated changes first:
git status --short
The CLI refuses a dirty workspace by default because one-shot work may edit many files. Use --allow-dirty only when you intentionally want the run to start from existing local changes.
Run an accepted local plan
This path requires a CLI whose one-shot --help lists --plan, --packet, and
--preview. If those options are absent, update to a release that supports local
plan execution before continuing. The plan must contain stable phase anchors and
Packet links lists. Its unfinished packets need V4 recommendedOrder metadata and
explicit dependsOn UUID arrays; [] means no prerequisites.
In your terminal, from the repository:
-
Commit preparation changes and confirm the working tree is clean. Local runs do not support a dirty-worktree override.
-
Preview the exact scope and policy:
swarmcraft one-shot --workspace . --plan docs/plans/migration-plan.md --agent-provider claude --checking off --reviewing off --commit-policy done --preview -
Inspect the selected tasks, order and prerequisites. Repeat the same command without
--previewwhen that scope and policy are authorised. -
Read the reported run status and inspect the task commits. Exit 0 means the selected scope completed; exit 2 means a workflow/budget stop or pending human review; exit 130 means you interrupted it; exit 1 means an execution error.
Local runs default to checking and reviewing on. The explicit off choices above
skip those separate stages while retaining implementation validation. Skipped
checklist items remain unchecked, and the packet records the execution policy
rather than claiming human visual approval.
Use repeatable --phase <anchor> to select phases, or repeatable --packet <path>
instead of --plan for direct tasks. Prerequisites outside that scope must already
be complete. Do not combine local selectors with --project, hosted --task,
delegation or Managed AI. A local packet's saved project ID does not force sign-in.
For legacy packets, preview a scoped migration with
swarmcraft upgrade --workspace . --ordered-packets --packet <path> --check, then
repeat without --check to apply. Declare prerequisites from the accepted plan
before execution; migration never assumes independence or renames files.
The run freezes scope and policy. Resume with the usual resume command. Inspect
intentional packet edits before adding --accept-packet-changes, and inspect an
interrupted stage's log before adding --retry-interrupted. A changed plan needs
a new reviewed run. Local logs live directly under .swarmcraft/runs/<run-id>/.
Board connection can happen later through the extension.
Run the board
Start with a limited run when you are proving a new customer setup. The multiline examples use Bash. In PowerShell, join the lines and remove the trailing \ characters; use swarmcraft.cmd for an npm installation. For example:
swarmcraft.cmd one-shot --project "YOUR_PROJECT_ID" --workspace . --agent-provider codex --task-limit 1 --max-agent-requests 6 --commit-policy done
Replace the project placeholder with your project ID. In Bash:
swarmcraft one-shot \
--project <project-id> \
--workspace . \
--agent-provider codex \
--task-limit 1 \
--max-agent-requests 6 \
--commit-policy done
Run the full board after the first task proves the setup:
swarmcraft one-shot \
--project <project-id> \
--workspace . \
--agent-provider codex \
--max-agent-requests 100 \
--commit-policy done
Use --agent-provider copilot for Copilot CLI or --agent-provider claude for Claude Code. Use --agent-provider custom --agent-command '<command with {command}>' for a reviewed local wrapper, or --agent-provider managed for optional credit-funded Managed AI. Never put an API key in --agent-command.
Check provider permissions
Default one-shot permissions differ by provider:
| Provider | Default behavior |
|---|---|
| Codex | Uses the workspace-write sandbox and your Codex approval configuration. |
| Copilot | Enables all tools and disables user questions (--allow-all-tools --no-ask-user). |
| Claude Code | Uses the seeded .claude/settings.json and your other Claude permissions; dontAsk denies anything not allowed. |
Review these settings before unattended work. A custom --agent-command can change these defaults.
For Claude Code, SwarmCraft seeds .claude/settings.json when you choose Claude. Claude applies its allow rules only in a folder you have trusted, so run claude once in the repository and accept the trust prompt before one-shot. If a stage log shows Ignoring … permissions.allow entries … this workspace has not been trusted, do that, then run resume. It allows file edits, read-only inspection, local Git commits and the swarmcraft CLI. When your project's build profile names a stack, it also allows that stack's build and test tools, such as pnpm or ./gradlew. It denies git push, curl, wget, reading environment variables and reading real .env files. One-shot passes its run settings, such as delivery mode and whether checking is on, in each stage prompt, so agents never need to read environment variables. Upgrades only add missing rules. A rule you move to deny or ask is not allowed again, and SwarmCraft leaves the file in place if you switch provider.
To allow more, open claude in the repository and use /permissions. Commit shared rules in .claude/settings.json, or keep personal rules in .claude/settings.local.json; see Claude permission configuration. One-time approvals do not carry into one-shot. Claude retains its own login and sandbox configuration.
Lane policies
The hosted-board CLI one-shot default policy is:
- implementation runs in
doing - checking is off
- reviewing is off
- completed tasks move to
done - no local commit is created unless
--commit-policy doneis supplied
Enable extra lanes only when an internal or customer run explicitly needs them:
swarmcraft one-shot \
--project <project-id> \
--workspace . \
--agent-provider codex \
--checking on \
--reviewing on
--checking on runs the checking lane. With checking off, the driver ignores the implementation skill's normal checking handoff, syncs its evidence, and moves accepted work directly to done. --reviewing on stops accepted work in reviewing instead of moving it to done. --commit-policy done creates a local git commit for completed task changes.
Budgets and credentials
Limit the number of agent stages:
swarmcraft one-shot \
--project <project-id> \
--workspace . \
--agent-provider codex \
--max-agent-requests 100
--max-agent-requests bounds SwarmCraft agent invocations, not the provider’s internal model requests. Your provider subscription still has its own usage limits.
If the selected agent writes cost telemetry, require and cap it:
swarmcraft one-shot \
--project <project-id> \
--workspace . \
--agent-provider custom \
--agent-command '<command with {command}>' \
--agent-api-key-env-name MY_AGENT_KEY \
--agent-env-file .env/agent.env \
--require-cost-telemetry \
--max-agent-spend-usd 25
Missing dollar-cost telemetry remains unknown and is not treated as zero; --require-cost-telemetry fails if no adapter supplies it. A provider cost estimate is not your subscription bill.
The CLI passes a restricted environment to agent processes. For Codex, Copilot, or custom commands that require an explicit credential, use --agent-api-key-env-name. Claude subscription runs reject this flag and --agent-env-file; use the local Claude login instead.
Customer-supplied Codex, Copilot, Claude Code, and custom providers use credentials and billing you manage outside SwarmCraft. Managed AI shows a credit estimate before the run and pauses before an unfunded call without discarding completed work.
Resume and status
Each run writes a manifest under:
.swarmcraft/runs/<run-id>/manifest.json
Check progress:
swarmcraft status --run <run-id> --workspace .
Resume after a failed command, terminal cancellation, or machine restart:
swarmcraft resume --run <run-id> --workspace .
Resume works only through the tasks the run selected when it started. Resuming a --task-limit 10 run that stopped at task 4 finishes the remaining 6. Completed tasks are skipped. A task whose work was already accepted finishes its move to Done and its commit without running the agent again.
status and every run end with where the run stopped and the exact command to continue it. Exit codes:
| Exit | Meaning |
|---|---|
| 0 | The selected tasks completed. |
| 2 | A task is blocked, or tasks are waiting for human review. |
| 3 | Paused by a provider usage limit or a SwarmCraft API outage. |
| 130 | Interrupted with Ctrl+C, SIGTERM or SIGHUP. |
| 1 | Unexpected error. |
Stop a run
Press Ctrl+C once. The CLI stops the agent and any processes it started, then records the interrupted stage. Press Ctrl+C again only if you need to exit immediately. To continue, inspect the stage log under .swarmcraft/runs/<run-id>/logs/, then resume with --retry-interrupted:
swarmcraft resume --run <run-id> --workspace . --retry-interrupted
The task's partial changes stay with that task and are included in its commit. Files you changed before the run, or while it was stopped, are never committed by it. Resume asks for --allow-dirty only when you changed files outside the run, and still leaves those files out of task commits.
Usage limits and API outages
When Claude Code, Codex or Copilot reports a usage limit, the run pauses and prints when the limit resets, if the provider said. Running out of monthly credits or hitting a spending cap also pauses the run, without a reset time. Resume after that time, or let the CLI wait:
swarmcraft resume --run <run-id> --workspace . --wait-for-usage-reset --usage-wait-max 6h
If SwarmCraft's API is briefly unavailable, the CLI retries with backoff for up to 15 minutes per call, honouring the server's Retry-After. Change the limit with --api-retry-max-wait 30m. If the API stays down, the run pauses. Resume once SwarmCraft is reachable; finished agent work is not repeated.
If the run reached its request ceiling, explicitly extend that ceiling while resuming:
swarmcraft resume --run <run-id> --workspace . --max-agent-requests 100
VS Code starts with a 100-request limit. Before launch it estimates the capacity required by unfinished tasks and the selected checking policy; when that estimate is higher, it asks you to approve the larger limit instead of starting a run that is expected to stop partway through.
Recovery
If SwarmCraft reports a stale revision, refresh the project board, inspect the packet, and rerun resume. A stale revision means the board changed after the packet was written.
If an agent stage fails, read the terminal output and the run manifest. Check the selected provider’s login, available usage and tool permissions using provider troubleshooting, fix the cause, then run resume.
If the repository has partial local changes, review git status --short before resuming. Commit, stash, or discard only changes you understand.
If a packet identity or lane mismatch appears, stop and inspect the packet frontmatter before editing the board. The CLI blocks these cases to avoid syncing the wrong task.
Runs started by CLI 0.9.4 or earlier
Older CLIs didn't record which tasks a run selected, so resuming would pick tasks again from the board. Upgrade the CLI, then either:
- resume with the remaining tasks named explicitly:
swarmcraft resume --run <run-id> --workspace . --task <task-id> --task <task-id>; or - recover by hand: check the interrupted task's diff, commit it as
Complete <task-id>: <title>, move that task to Done on the board if it isn't already, and start a newone-shotwith--taskfor the remaining tasks.
If credits stop a Managed AI run, add credits in Billing, then resume the same run. For broader setup, authentication, stale-revision, and delivery recovery, use Troubleshoot SwarmCraft.
Success check
Run swarmcraft status --run <run-id> --workspace . and inspect git status --short. Refresh the board when the run is connected; local-only work does not require board confirmation. Completed tasks should have matching packet state and, when --commit-policy done was used, one reviewed local commit per completed task. Review those changes before deployment.
Support bundle
Collect a redacted support bundle when you need help diagnosing a run:
swarmcraft support-bundle --run <run-id> --workspace .
The bundle is written under:
.swarmcraft/runs/<run-id>/support-bundle/
It includes a redacted manifest, run id, selected policy, failed stage details, and artifact paths. Review the files before sharing them with support.
Continue with Review and apply generated changes.
Hand completed work to a reviewer
Inspect the actual run policy and evidence. Explicitly skipped task review is not human approval. Use Review changes for task-level decisions and Merge requests for the completed branch and its integration evidence. A successful run does not authorise a merge, target push or deployment.
