ultraswarm

Ultraswarm is a durable multi-worker coding orchestrator for Codex, Claude Code, Cursor Agent, Grok, and shell usage. One standalone Node runner owns decomposition, worker routing, process supervision, isolated Git worktrees, adaptive review, transactional integration, approvals, recovery, and reporting.

What's New In v3.5.1–v3.5.10

Hardening from a full audit of the orchestrator (each fix shipped as its own patch release; see the CHANGELOG for per-version detail):

• Concurrency — fixed a re-entrant limiter deadlock that could hang an entire run, and froze runs deterministically on ≤3-core hosts (CI), whenever a high-risk task fanned out competition/QA work.
• Security — plan contract.commands now reject shell metacharacters (no more npm test; rm -rf ~ reaching the shell); worker env passthrough narrowed from the whole XDG_* namespace to named vars.
• Integration — a no-op squash records a clean skip instead of throwing and blocking the whole wave; a failed per-task commit fails loud instead of reporting ok; post-run cleanup deletes only the current run's branches.
• Recovery — resume judges liveness on a persisted orchestrator identity (pid + boot id), so it can't reap a still-running run or be fooled by PID reuse after a reboot; terminal runs are immutable.
• Brain — Anthropic schema calls extract JSON defensively and fall back to raw text so the validate-and-retry loop works; malformed --plan-file / package.json fail with a clear USAGE error.
• Alias workers in competition — user-defined alias workers can now participate in (and be retried within) high-risk competition; they previously tombstoned as "only N usable worker(s)".

What's New In v3.5

• Functional preflight — preflight runs a cached exec smoke test per CLI (write a file in an isolated temp dir) and excludes workers that pass --version but can't actually run (dead auth, no-op). Routing keys off the functional verdict. See Prerequisites.
• Human-readable output — preflight, plan previews, status, and doctor render aligned tables by default; add --json for the old machine output.
• Live progress + every-agent heartbeat — runs stream per-agent dispatch lines, gate results, and a periodic active/idle heartbeat to stderr so every worker stays visible.
• Tokens-saved summary — the final report estimates the implementation tokens that ran on external CLIs off your Claude context (an honest best-effort floor).
• Repo-local worktrees with deps installed — per-task and integration worktrees default to <repo>/.ultraswarm/worktrees and have dependencies installed before gates run (detected from the lockfile: pnpm/npm/yarn), so build/test gates resolve node_modules even on pnpm workspaces.

What's New In v3.4

• agent worker — the Cursor CLI (agent -p --force) as a headless shell worker for isolated worktree execution. See Cursor Agent Worker.
• Cursor agent host skill — install with scripts/install-cursor-skill.sh so Cursor sessions can orchestrate via the standalone runner. See Cursor Agent.

What's New In v3.3

• small-harness worker — SmallHarness as a built-in worker with MCP integration and multi-backend support. See SmallHarness Worker.

What's New In v3.2

• User-defined harness aliases — register your own CLI entries under a new top-level aliases config key. Each alias extends a built-in (inheriting its binary, timeout, effort flags, and capabilities), overrides only its specialty / models / invocation, and can cap routing with maxTier. Generalizes the previously hardcoded pi-local; strictly opt-in. See Harness Aliases.

What's New In v3.1

• pi worker — the provider-agnostic pi coding CLI (Anthropic Claude spread by default). See Local / Private Models.
• pi-local worker — an always-on local/private worker that drives Ollama models through the same pi binary for fully offline-capable runs.
• Per-task effort levels — the decomposition brain assigns reasoning effort per task, independent of model tier, defaulting to low, with effort-first QA escalation. See Effort Levels.

What Changed In v3

• SQLite state and append-only events under .ultraswarm/state.sqlite
• Capability and repository-metric worker routing with explanations
• Supervised worker process groups, timeouts, cancellation, redacted bounded logs
• Executable task contracts and forbidden-path policy
• Integration branches that do not modify the checked-out branch
• Separate plan and merge approvals
• Crash/status/log/export commands and stale-base recovery
• Generated Claude, Codex, Grok, and Cursor agent skills from one provenance-locked contract

Node 22 or newer is required because ultraswarm uses the built-in node:sqlite API.

Install

git clone https://github.com/fubak/ultraswarm.git ~/projects/ultraswarm
cd ~/projects/ultraswarm
npm install

Codex

bash scripts/install-codex-skill.sh

This creates:

~/.agents/skills/ultraswarm -> ~/projects/ultraswarm/hosts/codex/skills/ultraswarm

Restart Codex and invoke $ultraswarm.

Claude Code

Install the plugin:

/plugin marketplace add fubak/ultraswarm
/plugin install ultraswarm@ultraswarm

Invoke /ultraswarm.

Grok Build (xAI Plugin Marketplace)

Ultraswarm is published in the official xAI Grok plugin marketplace.

• Grok Build can proactively suggest the skill for complex multi-step coding tasks.
• Install directly from the Grok marketplace / plugin browser (searches for "ultraswarm").
• Invocation inside Grok: follow the skill (typically ultraswarm or /ultraswarm).

The skill delegates to the standalone runner (do not re-implement orchestration inside the host).

For direct/shell or non-Grok use:

node ~/projects/ultraswarm/bin/ultraswarm.mjs run ...
# or the installed bin after `npm install -g` equivalent

See the generated Grok host contract: hosts/grok/skills/ultraswarm/SKILL.md.

Plugin source + details: https://github.com/fubak/ultraswarm (manifests in .grok-plugin/ + .claude-plugin/).

Maintaining the plugin after publication

1. Bump the version in every manifest so they agree (validate Check 3): package.json, package-lock.json (run npm install --package-lock-only), .claude-plugin/plugin.json and .grok-plugin/plugin.json (keep byte-identical — cp one to the other), and both version fields in .claude-plugin/marketplace.json (metadata.version + plugins[0].version).
2. Update docs + CHANGELOG (move [Unreleased] to the new version + date).
3. npm run validate and npm test must pass.
4. Push to main.
5. Capture the new commit SHA (git rev-parse HEAD).
6. In the plugin-marketplace repo, update the sha for ultraswarm, re-run python3 scripts/generate-plugin-index.py, then validate + open PR.
7. scripts/validate.sh now also validates .grok-plugin/plugin.json (parse + version match) and enforces that the two manifests are byte-identical.

This addresses review feedback on packaging validation and sync risk.

Cursor Agent

bash scripts/install-cursor-skill.sh

This creates:

~/.cursor/skills/ultraswarm -> ~/projects/ultraswarm/hosts/agent/skills/ultraswarm

Restart Cursor and invoke the ultraswarm skill. The host prepares plans and delegates execution to bin/ultraswarm.mjs; it does not implement feature work directly.

Install the Cursor CLI separately if you also want agent as a worker:

curl https://cursor.com/install -fsS | bash
agent --version

Grok Or Shell (non-Grok hosts)

See the full Grok Build (xAI Plugin Marketplace) section (and the maintenance subsection) above. For direct execution outside Grok:

node ~/projects/ultraswarm/bin/ultraswarm.mjs ...

The generated Grok host contract is at hosts/grok/skills/ultraswarm/SKILL.md.

Prerequisites

• A Git repository
• Node 22+
• At least two authenticated worker CLIs from codex, gemini, grok, agy, droid, opencode, pi, pi-local, small-harness, and agent
• An authenticated claude CLI for the default QA/decomposition brain, or ANTHROPIC_API_KEY with ULTRASWARM_BRAIN=anthropic-api

Check readiness:

# Functionally verify each CLI (cached smoke test — proves a worker can actually write a file,
# not just that `--version` succeeds). Workers shown UNUSABLE are excluded from routing.
node ~/projects/ultraswarm/bin/ultraswarm.mjs preflight

# Policy, gates, and worker capabilities (add --json for machine-readable output):
node ~/projects/ultraswarm/bin/ultraswarm.mjs doctor
node ~/projects/ultraswarm/bin/ultraswarm.mjs workers

preflight is the recommended first step: a CLI can pass --version yet fail every real run (dead auth, no-op output). The smoke test catches that and routing skips non-functional workers automatically. Verdicts are cached in .ultraswarm/functional-probe.json (24h TTL, keyed by binary version); preflight --smoke forces a re-probe.

Run

Create a plan:

{
  "tasks": [
    {
      "id": "api-tests",
      "description": "Add regression coverage for the API",
      "files": ["test/api.test.mjs"],
      "complexity_score": 25,
      "risk": "routine",
      "effort": "low",
      "dependencies": [],
      "prompt": "Add focused regression tests for invalid request handling.",
      "contract": {
        "commands": ["npm test"],
        "assertions": ["Invalid requests return 400"],
        "allowed_paths": ["test"]
      }
    }
  ]
}

cli, model_tier, and effort are optional. When `