{"id":47588402,"url":"https://github.com/moonrunnerkc/swarm-orchestrator","last_synced_at":"2026-05-14T02:01:43.943Z","repository":{"id":334637207,"uuid":"1140182359","full_name":"moonrunnerkc/swarm-orchestrator","owner":"moonrunnerkc","description":"Verification and governance layer for AI coding agents. Parallel orchestration with evidence-based quality gates for Copilot, Claude Code, and Codex.","archived":false,"fork":false,"pushed_at":"2026-04-19T04:16:33.000Z","size":12382,"stargazers_count":80,"open_issues_count":16,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-19T06:23:49.478Z","etag":null,"topics":["ai-agents","ai-orchestration","claude-code","cli","codex","cost-governance","github-action","github-copilot","parallel-execution","quality-gates","typescript","verification"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moonrunnerkc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-22T23:48:58.000Z","updated_at":"2026-04-19T04:16:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/moonrunnerkc/swarm-orchestrator","commit_stats":null,"previous_names":["moonrunnerkc/copilot-swarm-orchestrator","moonrunnerkc/swarm-orchestrator"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/moonrunnerkc/swarm-orchestrator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonrunnerkc%2Fswarm-orchestrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonrunnerkc%2Fswarm-orchestrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonrunnerkc%2Fswarm-orchestrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonrunnerkc%2Fswarm-orchestrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moonrunnerkc","download_url":"https://codeload.github.com/moonrunnerkc/swarm-orchestrator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonrunnerkc%2Fswarm-orchestrator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32456168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-orchestration","claude-code","cli","codex","cost-governance","github-action","github-copilot","parallel-execution","quality-gates","typescript","verification"],"created_at":"2026-04-01T16:54:49.458Z","updated_at":"2026-05-14T02:01:43.924Z","avatar_url":"https://github.com/moonrunnerkc.png","language":"Python","funding_links":[],"categories":["Applications","Automated PR Agents"],"sub_categories":["Multi-Agent Task Solver Projects"],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/header.svg\" alt=\"Swarm Orchestrator\" width=\"100%\"\u003e\n\n### Deterministic-first verification and falsification engine for code changes.\n\n\u003cp\u003e\nHand-authored contracts, externally-sourced patches, verifier-gated commits,\u003cbr/\u003e\nappend-only evidence ledgers, and optional model providers for local or hosted\u003cbr/\u003e\ngeneration.\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-ISC-blue?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"package.json\"\u003e\u003cimg alt=\"Node\" src=\"https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/moonrunnerkc/swarm-orchestrator/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/moonrunnerkc/swarm-orchestrator/ci.yml?branch=main\u0026label=ci\u0026style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"package.json\"\u003e\u003cimg alt=\"Version\" src=\"https://img.shields.io/github/package-json/v/moonrunnerkc/swarm-orchestrator?style=flat-square\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"#quick-start\"\u003e\u003cb\u003eQuick start\u003c/b\u003e\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#providers\"\u003e\u003cb\u003eProviders\u003c/b\u003e\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#how-it-works\"\u003e\u003cb\u003eHow it works\u003c/b\u003e\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#adapters\"\u003e\u003cb\u003eAdapters\u003c/b\u003e\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#cli-reference\"\u003e\u003cb\u003eCLI\u003c/b\u003e\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#github-action\"\u003e\u003cb\u003eGitHub Action\u003c/b\u003e\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#documentation\"\u003e\u003cb\u003eDocs\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n`swarm` separates patch generation from verification.\n\nThe default deterministic provider runs entirely offline with no model installs,\nAPI keys, or network access. It validates hand-authored contracts against\nexternally-supplied patches and runs the same verification pipeline used by\nmodel-backed sessions.\n\nOptional providers let you generate patches through:\n\n- local OpenAI-compatible endpoints\n- Ollama\n- llama.cpp\n- vLLM\n- Anthropic Claude\n\nThe verifier, falsifiers, ledger, manifests, rollback system, and quality gates\nare provider-agnostic. The verifier never knows where patches came from.\n\nAfter a patch satisfies its obligation, falsifier adapters attempt to break it\nbefore merge. Every action is recorded in an append-only hash-chained ledger for\nreplay, auditing, and resume support.\n\nThe architectural rule is simple:\n\n\u003e Nothing commits unless the obligation verifier and quality gates pass.\n\n---\n\n## Status\n\n\u003cp align=\"center\"\u003e\n\u003csub\u003e\u003cb\u003eVersion\u003c/b\u003e \u003ccode\u003e8.0.3\u003c/code\u003e \u0026nbsp;·\u0026nbsp; \u003cb\u003eNode\u003c/b\u003e \u003ccode\u003e\u0026gt;= 20\u003c/code\u003e \u0026nbsp;·\u0026nbsp; \u003cb\u003eCI matrix\u003c/b\u003e 20, 22 \u0026nbsp;·\u0026nbsp; \u003cb\u003eLicense\u003c/b\u003e ISC\u003c/sub\u003e\n\u003c/p\u003e\n\nv8.0.3 changed the default provider from `anthropic` to `deterministic`. If you\nupgraded from an earlier release and your workflow assumed a hosted model,\nopt back in with `--extractor anthropic --session anthropic` (or the\n`EXTRACTOR_PROVIDER` / `SESSION_PROVIDER` env vars). See\n[`docs/migration.md`](docs/migration.md).\n\nv8 is the default architecture. These commands dispatch directly to v8 without a\nversion prefix:\n\n```text\nswarm compile\nswarm run\nswarm resume\nswarm stats\nswarm doctor\n```\n\nThe legacy verified-branch pipeline remains available through `swarm run --v6`,\nor the older `swarm swarm` / `swarm execute` commands. The `swarm v8 \u003ccmd\u003e` form\nis still accepted for compatibility.\n\n---\n\n## Quick start\n\nRequires:\n\n- Node `\u003e= 20`\n- git `\u003e= 2.40`\n\nThe default provider requires no model, no API key, and no network access.\n\n```bash\ngit clone https://github.com/moonrunnerkc/swarm-orchestrator.git\ncd swarm-orchestrator\n\nnpm install\nnpm run build\nnpm link\n```\n\nAuthor a contract:\n\n```bash\ncat \u003e contract.yaml \u003c\u003c'EOF'\nobligations:\n  - type: test-must-pass\n    command: npm test\nEOF\n```\n\nCompile it:\n\n```bash\nswarm compile \"verify the test command exits zero\" \\\n  --contract-file contract.yaml \\\n  --out .swarm/contracts/local\n```\n\nProvide externally-generated patches:\n\n```bash\necho -n \"\" \u003e patches.jsonl\n```\n\nRun verification:\n\n```bash\nswarm run .swarm/contracts/local \\\n  --external-patches-queue patches.jsonl\n```\n\nResume a stopped run:\n\n```bash\nswarm resume \u003crun-id\u003e\n```\n\n---\n\n## Providers\n\nAll providers implement the same extractor and session interfaces. The verifier,\nfalsifiers, ledger, manifests, rollback system, tournament logic, and quality\ngates are shared across providers.\n\n### Deterministic (default)\n\nOffline verification with no model dependency.\n\nUse when:\n\n- contracts are hand-authored\n- patches are generated externally\n- reproducibility matters more than generation\n\nPatch sources can include humans, external models, recorded sessions, generated\ndiff queues, or stdin streams.\n\n```bash\nswarm compile \"\u003cgoal\u003e\" \\\n  --contract-file contract.yaml \\\n  --out \u003cdir\u003e\n\nswarm run \u003cdir\u003e \\\n  --external-patches-queue patches.jsonl\n```\n\nAdditional inputs:\n\n- `--external-patches-dir \u003cdir\u003e`\n- `--external-patches-stdin`\n\n### Local provider\n\nUse any compatible local or self-hosted endpoint.\n\nSupported backends:\n\n- OpenAI-compatible APIs\n- Ollama\n- llama.cpp\n- vLLM\n\n```bash\nexport LOCAL_LLM_BACKEND=openai-compatible\nexport LOCAL_LLM_BASE_URL=http://localhost:8080/v1\nexport LOCAL_LLM_MODEL_EXTRACTOR=\u003cmodel\u003e\nexport LOCAL_LLM_MODEL_SESSION=\u003cmodel\u003e\n\nswarm compile \"\u003cgoal\u003e\" --extractor local\nswarm run .swarm/contracts/\u003cid\u003e --session local\n```\n\nReference profiles (tested combinations, not recommendations — any\nbackend-compatible model works):\n\n| Profile | Backend             | Hardware                   | Representative model        |\n| ------- | ------------------- | -------------------------- | --------------------------- |\n| Minimal | `openai-compatible` | CPU only                   | small quantized 3-7B        |\n| Modest  | `ollama`            | Consumer GPU               | mid-size code-trained model |\n| Serious | `llama-cpp`         | Workstation / high-end GPU | larger code model           |\n| Remote  | `vllm`              | Separate inference server  | hosted on a GPU box         |\n\nFull env-var and grammar reference: [`docs/providers.md`](docs/providers.md).\n\n### Anthropic provider\n\nHosted Claude integration.\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\n\nswarm compile \"\u003cgoal\u003e\" --extractor anthropic\nswarm run .swarm/contracts/\u003cid\u003e --session anthropic\n```\n\n---\n\n## How it works\n\n```text\ngoal\n  │\n  ▼\ncontract compiler\n  │\n  ▼\ncontract + manifest\n  │\n  ▼\nsession / population manager\n  │\n  ├── generate or ingest patches\n  ├── verify obligations\n  ├── run falsifiers\n  ├── apply rollback if needed\n  └── append ledger evidence\n  │\n  ▼\ncommitted diff\n```\n\n### Compile\n\n`swarm compile` produces:\n\n- `contract.jsonl`\n- `manifest.json`\n\nAll providers emit the same canonical contract format and manifest structure.\n\n### Run\n\n`swarm run` opens a provider session. Depending on provider configuration,\npatches may come from external queues, local inference endpoints, or hosted\nAPIs.\n\nTournament mode evaluates multiple candidates in parallel and selects the top\nverified result.\n\n### Verify\n\nVerification occurs at multiple stages:\n\n- pre-generation\n- streaming\n- post-generation\n- post-merge integration\n\nNothing commits unless verification succeeds.\n\n### Falsify\n\nAfter verification, falsifier adapters attempt to surface:\n\n- regressions\n- counter-examples\n- property violations\n\nConfirmed failures trigger rollback using content-addressed snapshots under\n`.swarm/snapshots/\u003crun-id\u003e/`. Rollback integrity is verified against logged\nSHA-256 hashes before restore.\n\n### Record\n\nEvery action is appended to `.swarm/ledger/\u003crun-id\u003e.jsonl`. Each ledger entry\nincludes the previous entry hash, making tampering detectable. Runs can resume\nfrom prior ledger state.\n\nArchitecture deep-dive: [`ARCHITECTURE.md`](ARCHITECTURE.md).\n\n---\n\n## Adapters\n\n`swarm` includes two separate adapter systems.\n\n### Producer adapters\n\nLocated in `src/adapters/`. These wrap external coding CLIs for the legacy v6\nverified-branch pipeline.\n\nSupported backends:\n\n- Copilot\n- Claude Code\n- Claude Code Teams\n- Codex\n\nOpt-in only:\n\n```bash\nswarm run --v6\n```\n\nSee [`docs/adapters.md`](docs/adapters.md).\n\n### Falsifier adapters\n\nLocated in `src/falsification/adapters/`. These attempt to break already-verified\npatches.\n\n| Falsifier             | Default | Obligation types                                                                  |\n| --------------------- | ------- | --------------------------------------------------------------------------------- |\n| `CodexFalsifier`      | on      | `property-must-hold`                                                              |\n| `CopilotFalsifier`    | on      | `import-graph-must-satisfy`, `function-must-have-signature`                       |\n| `ClaudeCodeFalsifier` | opt-in  | `property-must-hold`, `import-graph-must-satisfy`, `function-must-have-signature` |\n\nGlobal control: `--falsifiers on|off`.\n\nSee [`docs/falsification-adapters.md`](docs/falsification-adapters.md).\n\n---\n\n## CLI reference\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eView commands\u003c/b\u003e\u003c/summary\u003e\n\n```text\nswarm compile \u003cgoal\u003e\nswarm run \u003ccontract\u003e\nswarm resume \u003crun-id\u003e\nswarm stats \u003crun-id\u003e\nswarm doctor\n\nswarm run --goal \"\u003ctext\u003e\"\nswarm gates [path]\nswarm recipes\nswarm attest verify \u003ccommit\u003e\n```\n\n\u003c/details\u003e\n\nRun any command with `--help`. Full reference: [`docs/cli.md`](docs/cli.md).\n\n---\n\n## GitHub Action\n\nThe GitHub Action inherits the deterministic offline default.\n\n```yaml\n- uses: moonrunnerkc/swarm-orchestrator@v8\n  with:\n    goal: 'add a /health endpoint'\n    contract-only: false\n    cost-cap: '5.00'\n  env:\n    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\nAnthropic credentials are only required when explicitly using the Anthropic\nprovider.\n\nSee [`action.yml`](action.yml).\n\n---\n\n## Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eView configuration files\u003c/b\u003e\u003c/summary\u003e\n\n| File                                   | Purpose                              |\n| -------------------------------------- | ------------------------------------ |\n| `.env`, `~/.env`                       | Provider configuration and overrides |\n| `.swarm/contracts/\u003cid\u003e/contract.jsonl` | Compiled obligations                 |\n| `.swarm/contracts/\u003cid\u003e/manifest.json`  | Goal, provenance, contract hash      |\n| `.swarm/ledger/\u003crun-id\u003e.jsonl`         | Append-only execution ledger         |\n| `config/quality-gates.yaml`            | v6 quality gate configuration        |\n| `config/default-agents.yaml`           | v6 agent profiles                    |\n\n\u003c/details\u003e\n\nReference: [`docs/configuration.md`](docs/configuration.md),\n[`CLAUDE.md`](CLAUDE.md).\n\n---\n\n## Project layout\n\n```text\nsrc/\n├── contract/\n├── session/\n├── persona/\n├── population/\n├── ledger/\n├── wasm/\n├── verification/\n├── falsification/adapters/\n├── adapters/\n├── quality-gates/\n└── cli/\n```\n\n---\n\n## Documentation\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eView documentation index\u003c/b\u003e\u003c/summary\u003e\n\n| Document                                                           | Purpose                            |\n| ------------------------------------------------------------------ | ---------------------------------- |\n| [`ARCHITECTURE.md`](ARCHITECTURE.md)                               | System architecture and scheduling |\n| [`docs/providers.md`](docs/providers.md)                           | Provider configuration reference   |\n| [`docs/migration.md`](docs/migration.md)                           | Upgrade and migration notes        |\n| [`docs/configuration.md`](docs/configuration.md)                   | Config file and env precedence     |\n| [`docs/falsification-adapters.md`](docs/falsification-adapters.md) | Falsifier subsystem                |\n| [`docs/adapters.md`](docs/adapters.md)                             | v6 producer adapters               |\n| [`docs/quality-gates.md`](docs/quality-gates.md)                   | Quality gate system                |\n| [`docs/cli.md`](docs/cli.md)                                       | Full CLI reference                 |\n| [`docs/verification.md`](docs/verification.md)                     | Verifier pipeline                  |\n| [`docs/github-action.md`](docs/github-action.md)                   | GitHub Action inputs and outputs   |\n| [`docs/recipes.md`](docs/recipes.md)                               | Built-in recipes                   |\n| [`docs/benchmarks.md`](docs/benchmarks.md)                         | Benchmark harnesses                |\n| [`CHANGELOG.md`](CHANGELOG.md)                                     | Release history                    |\n| [`CONTRIBUTING.md`](CONTRIBUTING.md)                               | Development workflow               |\n| [`SECURITY.md`](SECURITY.md)                                       | Vulnerability reporting            |\n\n\u003c/details\u003e\n\n---\n\n## Contributing\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\nBefore opening a PR:\n\n```bash\nnpm test\nnode dist/src/cli.js gates .\n```\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003csub\u003e\n\n[ISC](LICENSE) © 2026 Bradley R. Kinnard / [moonrunnerkc](https://github.com/moonrunnerkc)\n\n\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoonrunnerkc%2Fswarm-orchestrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoonrunnerkc%2Fswarm-orchestrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoonrunnerkc%2Fswarm-orchestrator/lists"}