Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/moonrunnerkc/swarm-orchestrator

Verification and governance layer for AI coding agents. Parallel orchestration with evidence-based quality gates for Copilot, Claude Code, and Codex.
https://github.com/moonrunnerkc/swarm-orchestrator

ai-agents ai-orchestration claude-code cli codex cost-governance github-action github-copilot parallel-execution quality-gates typescript verification

Last synced: 12 days ago
JSON representation

Verification and governance layer for AI coding agents. Parallel orchestration with evidence-based quality gates for Copilot, Claude Code, and Codex.

Awesome Lists containing this project

README 

          



Swarm Orchestrator



### Deterministic-first verification and falsification engine for code changes.





Hand-authored contracts, externally-sourced patches, verifier-gated commits,


append-only evidence ledgers, and optional model providers for local or hosted


generation.






  License

  Node

  CI

  Version






  Quick start

   · 

  Providers

   · 

  How it works

   · 

  Adapters

   · 

  CLI

   · 

  GitHub Action

   · 

  Docs







---



`swarm` separates patch generation from verification.



The default deterministic provider runs entirely offline with no model installs,

API keys, or network access. It validates hand-authored contracts against

externally-supplied patches and runs the same verification pipeline used by

model-backed sessions.



Optional providers let you generate patches through:



- local OpenAI-compatible endpoints

- Ollama

- llama.cpp

- vLLM

- Anthropic Claude



The verifier, falsifiers, ledger, manifests, rollback system, and quality gates

are provider-agnostic. The verifier never knows where patches came from.



After a patch satisfies its obligation, falsifier adapters attempt to break it

before merge. Every action is recorded in an append-only hash-chained ledger for

replay, auditing, and resume support.



The architectural rule is simple:



> Nothing commits unless the obligation verifier and quality gates pass.



---



## Status





Version 8.0.3  ·  Node >= 20  ·  CI matrix 20, 22  ·  License ISC




v8.0.3 changed the default provider from `anthropic` to `deterministic`. If you

upgraded from an earlier release and your workflow assumed a hosted model,

opt back in with `--extractor anthropic --session anthropic` (or the

`EXTRACTOR_PROVIDER` / `SESSION_PROVIDER` env vars). See

[`docs/migration.md`](docs/migration.md).



v8 is the default architecture. These commands dispatch directly to v8 without a

version prefix:



```text

swarm compile

swarm run

swarm resume

swarm stats

swarm doctor

```



The legacy verified-branch pipeline remains available through `swarm run --v6`,

or the older `swarm swarm` / `swarm execute` commands. The `swarm v8 ` form

is still accepted for compatibility.



---



## Quick start



Requires:



- Node `>= 20`

- git `>= 2.40`



The default provider requires no model, no API key, and no network access.



```bash

git clone https://github.com/moonrunnerkc/swarm-orchestrator.git

cd swarm-orchestrator



npm install

npm run build

npm link

```



Author a contract:



```bash

cat > contract.yaml <<'EOF'

obligations:

  - type: test-must-pass

    command: npm test

EOF

```



Compile it:



```bash

swarm compile "verify the test command exits zero" \

  --contract-file contract.yaml \

  --out .swarm/contracts/local

```



Provide externally-generated patches:



```bash

echo -n "" > patches.jsonl

```



Run verification:



```bash

swarm run .swarm/contracts/local \

  --external-patches-queue patches.jsonl

```



Resume a stopped run:



```bash

swarm resume 

```



---



## Providers



All providers implement the same extractor and session interfaces. The verifier,

falsifiers, ledger, manifests, rollback system, tournament logic, and quality

gates are shared across providers.



### Deterministic (default)



Offline verification with no model dependency.



Use when:



- contracts are hand-authored

- patches are generated externally

- reproducibility matters more than generation



Patch sources can include humans, external models, recorded sessions, generated

diff queues, or stdin streams.



```bash

swarm compile "" \

  --contract-file contract.yaml \

  --out 



swarm run  \

  --external-patches-queue patches.jsonl

```



Additional inputs:



- `--external-patches-dir `

- `--external-patches-stdin`



### Local provider



Use any compatible local or self-hosted endpoint.



Supported backends:



- OpenAI-compatible APIs

- Ollama

- llama.cpp

- vLLM



```bash

export LOCAL_LLM_BACKEND=openai-compatible

export LOCAL_LLM_BASE_URL=http://localhost:8080/v1

export LOCAL_LLM_MODEL_EXTRACTOR=

export LOCAL_LLM_MODEL_SESSION=



swarm compile "" --extractor local

swarm run .swarm/contracts/ --session local

```



Reference profiles (tested combinations, not recommendations — any

backend-compatible model works):



| Profile | Backend             | Hardware                   | Representative model        |

| ------- | ------------------- | -------------------------- | --------------------------- |

| Minimal | `openai-compatible` | CPU only                   | small quantized 3-7B        |

| Modest  | `ollama`            | Consumer GPU               | mid-size code-trained model |

| Serious | `llama-cpp`         | Workstation / high-end GPU | larger code model           |

| Remote  | `vllm`              | Separate inference server  | hosted on a GPU box         |



Full env-var and grammar reference: [`docs/providers.md`](docs/providers.md).



### Anthropic provider



Hosted Claude integration.



```bash

export ANTHROPIC_API_KEY=sk-ant-...



swarm compile "" --extractor anthropic

swarm run .swarm/contracts/ --session anthropic

```



---



## How it works



```text

goal

  │

  ▼

contract compiler

  │

  ▼

contract + manifest

  │

  ▼

session / population manager

  │

  ├── generate or ingest patches

  ├── verify obligations

  ├── run falsifiers

  ├── apply rollback if needed

  └── append ledger evidence

  │

  ▼

committed diff

```



### Compile



`swarm compile` produces:



- `contract.jsonl`

- `manifest.json`



All providers emit the same canonical contract format and manifest structure.



### Run



`swarm run` opens a provider session. Depending on provider configuration,

patches may come from external queues, local inference endpoints, or hosted

APIs.



Tournament mode evaluates multiple candidates in parallel and selects the top

verified result.



### Verify



Verification occurs at multiple stages:



- pre-generation

- streaming

- post-generation

- post-merge integration



Nothing commits unless verification succeeds.



### Falsify



After verification, falsifier adapters attempt to surface:



- regressions

- counter-examples

- property violations



Confirmed failures trigger rollback using content-addressed snapshots under

`.swarm/snapshots//`. Rollback integrity is verified against logged

SHA-256 hashes before restore.



### Record



Every action is appended to `.swarm/ledger/.jsonl`. Each ledger entry

includes the previous entry hash, making tampering detectable. Runs can resume

from prior ledger state.



Architecture deep-dive: [`ARCHITECTURE.md`](ARCHITECTURE.md).



---



## Adapters



`swarm` includes two separate adapter systems.



### Producer adapters



Located in `src/adapters/`. These wrap external coding CLIs for the legacy v6

verified-branch pipeline.



Supported backends:



- Copilot

- Claude Code

- Claude Code Teams

- Codex



Opt-in only:



```bash

swarm run --v6

```



See [`docs/adapters.md`](docs/adapters.md).



### Falsifier adapters



Located in `src/falsification/adapters/`. These attempt to break already-verified

patches.



| Falsifier             | Default | Obligation types                                                                  |

| --------------------- | ------- | --------------------------------------------------------------------------------- |

| `CodexFalsifier`      | on      | `property-must-hold`                                                              |

| `CopilotFalsifier`    | on      | `import-graph-must-satisfy`, `function-must-have-signature`                       |

| `ClaudeCodeFalsifier` | opt-in  | `property-must-hold`, `import-graph-must-satisfy`, `function-must-have-signature` |



Global control: `--falsifiers on|off`.



See [`docs/falsification-adapters.md`](docs/falsification-adapters.md).



---



## CLI reference



View commands



```text

swarm compile 

swarm run 

swarm resume 

swarm stats 

swarm doctor



swarm run --goal ""

swarm gates [path]

swarm recipes

swarm attest verify 

```



Run any command with `--help`. Full reference: [`docs/cli.md`](docs/cli.md).



---



## GitHub Action



The GitHub Action inherits the deterministic offline default.



```yaml

- uses: moonrunnerkc/swarm-orchestrator@v8

  with:

    goal: 'add a /health endpoint'

    contract-only: false

    cost-cap: '5.00'

  env:

    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

```



Anthropic credentials are only required when explicitly using the Anthropic

provider.



See [`action.yml`](action.yml).



---



## Configuration



View configuration files



| File                                   | Purpose                              |

| -------------------------------------- | ------------------------------------ |

| `.env`, `~/.env`                       | Provider configuration and overrides |

| `.swarm/contracts//contract.jsonl` | Compiled obligations                 |

| `.swarm/contracts//manifest.json`  | Goal, provenance, contract hash      |

| `.swarm/ledger/.jsonl`         | Append-only execution ledger         |

| `config/quality-gates.yaml`            | v6 quality gate configuration        |

| `config/default-agents.yaml`           | v6 agent profiles                    |



Reference: [`docs/configuration.md`](docs/configuration.md),

[`CLAUDE.md`](CLAUDE.md).



---



## Project layout



```text

src/

├── contract/

├── session/

├── persona/

├── population/

├── ledger/

├── wasm/

├── verification/

├── falsification/adapters/

├── adapters/

├── quality-gates/

└── cli/

```



---



## Documentation



View documentation index



| Document                                                           | Purpose                            |

| ------------------------------------------------------------------ | ---------------------------------- |

| [`ARCHITECTURE.md`](ARCHITECTURE.md)                               | System architecture and scheduling |

| [`docs/providers.md`](docs/providers.md)                           | Provider configuration reference   |

| [`docs/migration.md`](docs/migration.md)                           | Upgrade and migration notes        |

| [`docs/configuration.md`](docs/configuration.md)                   | Config file and env precedence     |

| [`docs/falsification-adapters.md`](docs/falsification-adapters.md) | Falsifier subsystem                |

| [`docs/adapters.md`](docs/adapters.md)                             | v6 producer adapters               |

| [`docs/quality-gates.md`](docs/quality-gates.md)                   | Quality gate system                |

| [`docs/cli.md`](docs/cli.md)                                       | Full CLI reference                 |

| [`docs/verification.md`](docs/verification.md)                     | Verifier pipeline                  |

| [`docs/github-action.md`](docs/github-action.md)                   | GitHub Action inputs and outputs   |

| [`docs/recipes.md`](docs/recipes.md)                               | Built-in recipes                   |

| [`docs/benchmarks.md`](docs/benchmarks.md)                         | Benchmark harnesses                |

| [`CHANGELOG.md`](CHANGELOG.md)                                     | Release history                    |

| [`CONTRIBUTING.md`](CONTRIBUTING.md)                               | Development workflow               |

| [`SECURITY.md`](SECURITY.md)                                       | Vulnerability reporting            |



---



## Contributing



```bash

npm install

npm run build

npm test

```



Before opening a PR:



```bash

npm test

node dist/src/cli.js gates .

```



See [`CONTRIBUTING.md`](CONTRIBUTING.md).



---








[ISC](LICENSE) © 2026 Bradley R. Kinnard / [moonrunnerkc](https://github.com/moonrunnerkc)