--pr ]` | Validate a claimed issue against its approved base and artifacts (`--base`, if given, must match it), or run checkout-only CI validation against a trusted full base without a claim. `--issue` and `--pr` let an approved `allow_harness_changes` WorkUnit authorize protected changes when its authoritative state records that PR at the checked head. |
| `swarm issue submit [] [--base ] [--acknowledge-gap ]...` | Clean temporary markers, checkpoint and push the worktree branch, and open or reuse its linked Draft PR (targeting the default branch unless `--base` names another) with collapsible artifacts and provenance attestation. Maintainers can repeat `--acknowledge-gap` for every unmet criterion to carry the tester evidence into Known gaps for PR review. |
| `swarm issue status [] [--all]` | Inspect active claims, lease TTL, current phase, and published artifacts. |
| `swarm issue reconcile ` | Record the linked PR outcome and repair its issue label and audit projection. |
| `swarm issue discard-checkpoint --expected-head ` | Maintainers only: abandon an unsubmitted, unclaimed task checkpoint, keeping its commit under a retention ref, so the next claim starts fresh from the approved base. |
| `swarm issue cleanup [--apply]` | Preview task resources; with `--apply`, retire the merged task's worktree and code branches while keeping the issue ledger. |
| `swarm storage cleanup [--apply] [--details] [--json] [--all-repos]` | Preview which finished task worktrees and idle caches can be removed, with a summary by default and `--details` for every item; `--apply` rechecks and removes them for the selected repository or all registered checkouts. |
| `swarm storage report [--details]` | Summarize observed storage by resource class; add `--details` to list individual resources. |
| `swarm issue cleanup --all-merged [--apply]` | Preview or retire the resources of every local issue and PR worktree in one run, with ready, cleaned, kept, and failed task counts. |
| `swarm pr status ` / `swarm pr work [--instructions ]` | Inspect or continue developing a PR linked to an approved WorkUnit, including failing tests and review feedback, in a separate PR worktree. Contributors add `--fork` to revise their own fork PRs. |
| `swarm pr stage [--phase plan\|implement] [--harness ] [--model ] [--handoff] [--json]` | Stage an interactive plan or local implementation checkpoint in the separate managed PR worktree; links artifacts to the original issue without publishing the PR. |
| `swarm pr rebase [--continue\|--abort]` | Rebase onto the PR's approved target base; retain conflicts for deliberate resolution. |
| `swarm pr validate ` / `swarm pr submit ` | Validate the local revision and explicitly publish it to the same PR, refusing to overwrite a concurrent remote update. |
| `swarm repo add`, `swarm repo list`, `swarm repo remove` | Manage the local multi-repository registry (`~/.config/swarm/repos.yaml`). |
| `swarm node init`, `swarm node status`, `swarm node run` | Configure a worker node profile and run concurrent worker pools using the same selection order as `issue claim --next` (`--concurrency`, `--max-jobs`, `--watch`). |
| `swarm issue renew ` / `swarm issue release ` | Extend an active lease's TTL or release a claim back to the queue. |
| `swarm fork-coordinator --event [--json]` | Process a verified `issue_comment.created` fork worker request inside the upstream GitHub Action. |
| `swarm version [--json]` | Print version, commit, and platform metadata. |
Optional for organization repositories: use `swarm issue parent create --epic --title "Roadmap" --body-file ROADMAP.md` or `swarm repo plan --from ROADMAP.md --apply --epic` to request the Epic issue type. `swarm issue epic create` remains a compatibility alias for typed creation.
`swarm issue validate` and `swarm pr validate` always run the required checks. With a released build, `issue submit` and `pr submit` reuse a passing validation from the same worker and claim when the checkpoint content, approved base, trusted policy, and swarm version match exactly. Submit reports the original validation's age and tree SHA and includes that provenance in the PR. Edits, context changes, development builds, and fork submissions run checks again. CI always runs its checks. Checks that run on the host share a persistent SwarmOS-owned Go build cache per repository, so repeat runs stay fast; see [validation policy](docs/project.md#validation-policy-and-protected-paths).
Default `swarm issue work` carries a direct issue through bounded plan revisions, implementation, testing and trusted validation to a checkpoint. Human decisions pause work; publishing uses the separate explicit `swarm issue submit` command. See [workflow recovery](docs/WORKFLOWS.md#recovering-from-a-rejected-agent-plan) for operator feedback, persistent repair allowances and explicit phase boundaries.
Every leaf command accepts `--json` for scripting (for example, `swarm issue claim --json`, `swarm issue status --json`, `swarm repo doctor --json`, and `swarm repo validate --base --json`). Each prints one JSON document with a `kind` field, and failures print `{"kind": ..., "status": "failed", "error": ...}`; the `issue`, `repo`, `pr`, and `node` groups themselves only print help. When `issue work`, `issue submit`, `pr work`, `pr rebase`, or `pr submit` stops because the plan got changes requested, a maintainer needs to approve, or there is a conflict, the failure also carries an advisory `next_action` (`reason`, `argv`, `human_required`). The command then exits with `3`, `4`, or `5` instead of `1`. See [Reacting to stops in scripts](docs/developer.md#reacting-to-stops-in-scripts). Worker commands accept the global `--fork [--fork-remote ]` for personal-fork contributions, and `--upstream-remote ` when the project remote is not `origin`.
To upgrade an existing repository, install the new swarm and rerun `swarm repo init`. It updates every generated file you haven't changed (workflows, their pins, slash commands, prompts, and templates) and lists the customized files it kept. Run `swarm repo init --dry-run --verbose` first to see what will change, including diffs for the files you customized, or run `/swarm-onboard` in your coding agent to merge them with you. Review the diff and commit it like any other change.
For an existing approved WorkUnit PR, use `pr work` to develop or fix its implementation, `pr stage` to record an interactive plan or implementation in the PR worktree, and `pr rebase` to update ancestry. None publishes the candidate branch; only `pr submit` does. Maintainers revise PRs with upstream write access; contributors revise their own fork PRs with `--fork`. See [Continuing an Existing PR](docs/developer.md#continuing-an-existing-pr) for approvals, conflicts, and publication.
---
## Documentation & Guides
- **[Day in the Life of a Repo Admin (`docs/ADMIN_GUIDE.md`)](docs/ADMIN_GUIDE.md)** — Daily maintainer playbook for roadmap decomposition (`swarm repo plan --from`), backlog scanning (`swarm repo plan --scan`), and auditing provenance-attested Draft PRs.
- **[Owning a Busy Repository (`docs/backlog.md`)](docs/backlog.md)** — Turn a big pile of open issues into calm lanes: what to stabilize, likely duplicates, quiet issues, and work that's ready for agents.
- **[GitHub Security, Branching & Agent Authorization (`docs/GITHUB.md`)](docs/GITHUB.md)** — Configure repository rulesets, `SWARM_GITHUB_TOKEN` auth without `gh` CLI, secret-manager tokens via `SWARM_GITHUB_TOKEN_COMMAND`, and role-separated collaborator allowlists.
- **[Fork Mode Guide (`docs/fork-mode.md`)](docs/fork-mode.md)** — Contribute from a personal GitHub fork without upstream push access using the upstream fork coordinator Action.
- **[Working with Grok Bot (`docs/grokbot.md`)](docs/grokbot.md)** — Connect Grok Bot to your repositories, talk to your codebase, run PR reviews, and coordinate SwarmOS workers.
- **[Working with OpenAI Dot & Codex (`docs/openai-dot.md`)](docs/openai-dot.md)** — Configure Codex Cloud environments and remote repositories so your Dot can plan, review, and ship changes.
- **[Agent Harness Guides (`docs/harness/`)](docs/harness/README.md)** — Setup, invocation, isolation boundary, and troubleshooting for Codex, Claude Code, OpenCode 2, and OhMyPi.
- **[Project & Maintainer Setup (`docs/project.md`)](docs/project.md)** — Configure `.swarm/config.yaml`, validation rules, plan gates, and repository protections.
- **[Developer & Worker Guide (`docs/developer.md`)](docs/developer.md)** — Everyday CLI workflows, interactive `swarm issue stage`, agent harness table, reviewer sandboxing, handoffs, and recovery.
- **[Workflows & Review Gates (`docs/WORKFLOWS.md`)](docs/WORKFLOWS.md)** — Role prompts, `PLAN.md` / `TEST_PLAN.md` / `REVIEW.md` artifacts, provenance attestations, and gate transitions.
- **[Architecture (`docs/ARCHITECTURE.md`)](docs/ARCHITECTURE.md)** — Git compare-and-swap state refs, claim fencing, worktree checkpoints, and process boundaries.
- **[Changelog (`CHANGELOG.md`)](CHANGELOG.md)** — What changed in each release.
- **[Security Policy (`SECURITY.md`)](SECURITY.md)** — Trust model, reviewer isolation, vulnerability reporting, and release attestation verification.
- **[Agent & Contributor Guide (`AGENTS.md`)](AGENTS.md)** — Repository conventions, documentation voice guardrails, and review rules for coding agents and contributors.