by fubak
Multi-CLI agent swarm orchestrated by Claude Code: external AI CLIs code in isolated worktrees, Claude verifies and merges
# Add to your Claude Code skills
git clone https://github.com/fubak/ultraswarmultraswarm is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by fubak. Multi-CLI agent swarm orchestrated by Claude Code: external AI CLIs code in isolated worktrees, Claude verifies and merges. It has 53 GitHub stars.
ultraswarm's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/fubak/ultraswarm" and add it to your Claude Code skills directory (see the Installation section above).
ultraswarm is primarily written in JavaScript. It is open-source under fubak on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh ultraswarm against similar tools.
No comments yet. Be the first to share your thoughts!
Unlocks once the catalog security scan passes (runs nightly).
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
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.
Hardening from a full audit of the orchestrator (each fix shipped as its own patch release; see the CHANGELOG for per-version detail):
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.ok; post-run cleanup deletes only
the current run's branches.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.--plan-file / package.json fail with a clear USAGE error.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.preflight, plan previews, status, and doctor render aligned
tables by default; add --json for the old machine output.<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.agent worker — the Cursor CLI (agent -p --force) as a headless shell worker for
isolated worktree execution. See Cursor Agent Worker.scripts/install-cursor-skill.sh so Cursor
sessions can orchestrate via the standalone runner. See Cursor Agent.small-harness worker — SmallHarness as a
built-in worker with MCP integration and multi-backend support. See
SmallHarness Worker.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.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.effort per task,
independent of model tier, defaulting to low, with effort-first QA escalation. See
Effort Levels..ultraswarm/state.sqliteNode 22 or newer is required because ultraswarm uses the built-in node:sqlite
API.
git clone https://github.com/fubak/ultraswarm.git ~/projects/ultraswarm
cd ~/projects/ultraswarm
npm install
bash scripts/install-codex-skill.sh
This creates:
~/.agents/skills/ultraswarm -> ~/projects/ultraswarm/hosts/codex/skills/ultraswarm
Restart Codex and invoke $ultraswarm.
Install the plugin:
/plugin marketplace add fubak/ultraswarm
/plugin install ultraswarm@ultraswarm
Invoke /ultraswarm.
Ultraswarm is published in the official xAI Grok plugin marketplace.
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/).
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).[Unreleased] to the new version + date).npm run validate and npm test must pass.git rev-parse HEAD).sha for ultraswarm, re-run python3 scripts/generate-plugin-index.py, then validate + open PR.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.
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
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.
codex, gemini, grok, agy,
droid, opencode, pi, pi-local, small-harness, and agentclaude CLI for the default QA/decomposition brain, or
ANTHROPIC_API_KEY with ULTRASWARM_BRAIN=anthropic-apiCheck 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.
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 `