ultraswarm

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

• 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 — per-task worktrees default to <repo>/.ultraswarm/worktrees so Node build gates resolve the repo's node_modules.

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