{"id":51419662,"url":"https://github.com/calvinnwq/agent-swarm","last_synced_at":"2026-07-04T23:01:17.933Z","repository":{"id":351431839,"uuid":"1210010064","full_name":"calvinnwq/agent-swarm","owner":"calvinnwq","description":"Run focused swarms of AI agents and get one deterministic synthesis back.","archived":false,"fork":false,"pushed_at":"2026-06-24T05:39:03.000Z","size":8131,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T06:23:47.060Z","etag":null,"topics":["agent-swarm","ai-agents","cli","code-review","developer-tools","multi-agent","product-decision","typescript"],"latest_commit_sha":null,"homepage":"https://calvinnwq.github.io/agent-swarm/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/calvinnwq.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-14T02:10:46.000Z","updated_at":"2026-06-24T05:39:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/calvinnwq/agent-swarm","commit_stats":null,"previous_names":["calvinnwq/swarm","calvinnwq/agent-swarm"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/calvinnwq/agent-swarm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calvinnwq%2Fagent-swarm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calvinnwq%2Fagent-swarm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calvinnwq%2Fagent-swarm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calvinnwq%2Fagent-swarm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/calvinnwq","download_url":"https://codeload.github.com/calvinnwq/agent-swarm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calvinnwq%2Fagent-swarm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35138078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"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":["agent-swarm","ai-agents","cli","code-review","developer-tools","multi-agent","product-decision","typescript"],"created_at":"2026-07-04T23:01:17.163Z","updated_at":"2026-07-04T23:01:17.913Z","avatar_url":"https://github.com/calvinnwq.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Agent Swarm\n\n**Many AI agents on the problem. One answer back.**\n\n[![npm version](https://img.shields.io/npm/v/@calvinnwq/agent-swarm.svg)](https://www.npmjs.com/package/@calvinnwq/agent-swarm) [![npm downloads](https://img.shields.io/npm/dm/@calvinnwq/agent-swarm.svg)](https://www.npmjs.com/package/@calvinnwq/agent-swarm) [![CI](https://github.com/calvinnwq/agent-swarm/actions/workflows/ci.yml/badge.svg)](https://github.com/calvinnwq/agent-swarm/actions/workflows/ci.yml) [![docs](https://img.shields.io/badge/docs-site-blue.svg)](https://calvinnwq.github.io/agent-swarm/) [![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![X @calvinnwq](https://img.shields.io/badge/X-%40calvinnwq-black?logo=x)](https://x.com/calvinnwq)\n\n[**Docs**](https://calvinnwq.github.io/agent-swarm/) · [Quickstart](#quickstart) · [Spec](SPEC.md) · [Agent setup](INSTALL.md)\n\n\u003cbr /\u003e\n\n\u003cimg src=\"media/agent-swarm-social-h3-split-hero.png\" alt=\"Agent Swarm turns one AI agent request into a panel of specialist agents and synthesizes one answer back.\" width=\"900\" /\u003e\n\n\u003c/div\u003e\n\nAsk one model a question and you get one answer, shaped by a single point of\nview. Agent Swarm puts several agents on the same question instead - 2 to 5 of\nthem, each in a different role, all running at once - and merges what they send\nback into one report: the recommendation, where they agreed, the risks more than\none of them flagged, and the questions still open. That report is put together by\ncode rather than another model, so the same answers always produce the same\nresult.\n\nThe bundled presets cover a few common cases, like reviewing a diff or getting\ncustomer-style feedback on a launch, but each one is really just a list of agents\nand a set of decision words. Run a preset as it ships, or define your own agents\nand wire them into a new one.\n\n## Quickstart\n\nInstall the CLI globally - every method ends with the same `agent-swarm` command.\nYou'll need **Node ≥ 20** (Node 24 LTS recommended) and at least one harness CLI\non your `PATH`, authenticated - the default `product-decision` preset uses Claude\n(`claude auth login`).\n\n```bash\n# npm\nnpm install -g @calvinnwq/agent-swarm\n\n# pnpm\npnpm add -g @calvinnwq/agent-swarm\n\n# verify your setup\nagent-swarm --version\nagent-swarm doctor\n```\n\nThen run a one-round swarm - no config required:\n\n```bash\nagent-swarm run 1 \"Should we adopt server components?\" \\\n  --preset product-decision \\\n  --goal \"Decide on migration strategy\" \\\n  --decision \"Adopt / Defer / Reject\" \\\n  --timeout-ms 300000\n```\n\nWhen it finishes you'll find a self-contained run directory under\n`.agent-swarm/runs/\u003ctimestamp\u003e-\u003cslug\u003e/` with a deterministic `synthesis.md`.\nReal harnesses can take longer than the default 120s timeout - bump\n`--timeout-ms` for deeper runs. Use `--quiet` for one-line-per-event output in CI.\n\n\u003cdetails\u003e\n\u003csummary\u003eRun without installing (npx)\u003c/summary\u003e\n\nPrefer not to install a global CLI? Run any command through `npx` - swap\n`agent-swarm` for `npx -y @calvinnwq/agent-swarm`:\n\n```bash\nnpx -y @calvinnwq/agent-swarm doctor\nnpx -y @calvinnwq/agent-swarm run 1 \"Should we adopt server components?\" \\\n  --preset product-decision \\\n  --timeout-ms 300000\n```\n\nIf `npx` can't resolve the scoped-package bin, install globally instead (above).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall from source\u003c/summary\u003e\n\n```bash\npnpm install\npnpm build\npnpm link --global\nagent-swarm --version\n```\n\n**First-time `pnpm link --global` setup.** You'll need pnpm's global bin\ndirectory configured once. Run `pnpm setup`, then open a new shell (or\n`source ~/.zshrc` / `source ~/.bashrc`) before re-running `pnpm link --global`.\nThis is a one-time pnpm setup, not an `agent-swarm`-specific step - see the\n[pnpm docs](https://pnpm.io/cli/setup). If you'd rather skip global pnpm config,\n`npm link` works fine - it uses npm's prefix (typically already on PATH via\nnvm/Homebrew) against the pnpm-installed dep tree.\n\n\u003c/details\u003e\n\n### Recommended agent setup\n\nAgent Swarm is agent-operated, so let your coding agent finish the job. Install\nthe public skill and the CLI runs on demand via `npx`:\n\n```bash\nnpx skills add calvinnwq/agent-swarm --skill agent-swarm\n```\n\nThat installs the public `skills/agent-swarm` mirror into agents that support\nlocal skills; the\nskill invokes the CLI on demand with `npx -y @calvinnwq/agent-swarm`, so the\nagent path needs no separate install. The skill knows how to pick a preset, handle a decision matrix,\ninspect run artifacts, and report the synthesis - see [INSTALL.md](INSTALL.md)\nfor the full agent-operated setup and first run, and the\n[Agent usage guide](https://calvinnwq.github.io/agent-swarm/agent-usage.html) for\nthe operator workflow.\n\n## How it works\n\nEach `agent-swarm run` follows the same lifecycle:\n\n| Step | What happens |\n| --- | --- |\n| **1. Plan** | CLI flags, project config, and the chosen preset merge into a run. Each selected agent resolves to a harness (Claude, Codex, OpenCode, or Rovo). |\n| **2. Round** | Agents run in parallel (concurrency 3 by default) and each returns JSON validated against the agent output schema. One repair retry on a parse miss. |\n| **3. Resolve** | Between rounds, `--resolve` decides the next directive: a deterministic template (`off`) or a real LLM orchestrator pass (`orchestrator`). |\n| **4. Synthesize** | After the final round, a deterministic synthesis (no LLM call) computes consensus, the top recommendation, shared risks, and deferred questions. |\n\nEverything is durable: events, messages, and a checkpoint are written\nincrementally, so a failed run can be inspected (and, with future tooling,\nresumed).\n\n## Presets\n\nAgent Swarm ships seven bundled presets, each with its own set of agents and\ndecision words. Run one by name (no `--agents` required), or copy it as the\nstarting point for your own:\n\n| Preset                      | Agents                                                          | Resolve        | Best for                                                                         |\n| --------------------------- | --------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------- |\n| `product-decision`          | `product-manager`, `principal-engineer`                         | `orchestrator` | Framing a product decision through user-value and engineering-feasibility lenses |\n| `product-decision-codex`    | `product-manager-codex`, `principal-engineer-codex`             | `orchestrator` | The same flow, dispatched through Codex                                          |\n| `product-decision-opencode` | `product-manager-opencode`, `principal-engineer-opencode`       | `orchestrator` | The same flow, dispatched through OpenCode                                       |\n| `triad`                     | `product-manager`, `principal-engineer`, `product-designer`     | `orchestrator` | Full product triad: value, feasibility, and UX together                          |\n| `product-triad`             | `product-manager`, `product-engineer`, `product-designer`       | `orchestrator` | First-time default for product, design, and build tradeoffs                      |\n| `adversarial-code-review`   | `code-reviewer`, `implementation-skeptic`, `test-risk-reviewer` | `orchestrator` | Proposed code changes, PR plans, and architecture diffs                          |\n| `customer-panel`            | `first-time-user`, `busy-operator`, `skeptical-buyer`           | `orchestrator` | First-run value, adoption blockers, and outside-in product feedback              |\n\n```bash\nagent-swarm run 1 \"Should we adopt server components?\" \\\n  --preset product-decision \\\n  --timeout-ms 300000\n```\n\nCLI flags still win over preset defaults, so you can override `--resolve`,\n`--goal`, or `--decision` per run. Codex/OpenCode presets and custom presets are\ncovered in the [Reference](#reference).\n\n## Reference\n\n\u003cdetails\u003e\n\u003csummary\u003eCommands \u0026amp; flags\u003c/summary\u003e\n\n```\nUsage: agent-swarm [options] [command]\n\nCommands:\n  run [options] \u003crounds\u003e \u003ctopic...\u003e  Run a swarm\n  doctor                             Diagnose swarm setup\n  init [options]                     Create .agent-swarm/config.yml defaults\n  help [command]                     Display help for a command\n```\n\nRunning `agent-swarm` with no arguments prints this top-level help and exits 0,\nthe same as `agent-swarm --help`.\n\n#### `agent-swarm run`\n\n```\nUsage: agent-swarm run [options] \u003crounds\u003e \u003ctopic...\u003e\n\nArguments:\n  rounds             number of rounds (1-3)\n  topic              topic for the swarm\n\nOptions:\n  --agents \u003clist\u003e    comma-separated agent names\n  --backend \u003cname\u003e   runtime backend adapter (claude, codex)\n  --resolve \u003cmode\u003e   between-round resolution mode (off | orchestrator | agents)\n  --goal \u003ctext\u003e      primary goal for the swarm\n  --decision \u003ctext\u003e  decision target for the swarm\n  --doc \u003cpath\u003e       carry-forward document (repeatable)\n  --preset \u003cname\u003e    named preset (used when --agents is not provided)\n  --timeout-ms \u003cms\u003e  per-agent and orchestrator dispatch timeout (default: 120000)\n  --quiet            force quiet output; default auto by TTY\n```\n\nCarry-forward docs from `--doc` are deduplicated by path and must be readable\nfiles. The first 4,000 characters of each doc are packed into the seed brief\nwith provenance, so agents see source content rather than just paths.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eResolution modes (between rounds)\u003c/summary\u003e\n\n`--resolve` controls what happens **between rounds** while the run is in flight:\n\n| Mode           | Between-round behavior                                                                                                                                                                                                                                                                      |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `off`          | Deterministic only - the next-round brief gets a templated summary built from the prior packet. No extra LLM call. Question resolutions stay empty.                                                                                                                                         |\n| `orchestrator` | Real LLM pass - the bundled `orchestrator` agent reads the prior packet and returns a structured `OrchestratorOutput` (directive, question resolutions, deferred questions, confidence). The directive feeds the next round, and each pass is captured in `checkpoint.json` for resume use. |\n| `agents`       | Reserved - accepted and persisted in `manifest.json`/`synthesis.json` but currently behaves like `off`. Kept on the CLI surface so future agent-driven resolution can land without a flag rename.                                                                                           |\n\nIn `orchestrator` mode you also get:\n\n- An `orchestrator:pass` event per pass in `events.jsonl`, with `agentName`, `directive`, `confidence`, `questionResolutionsCount`, `questionResolutionLimit`, and `deferredQuestionsCount`.\n- An `orchestratorPasses` array in `checkpoint.json`, one entry per pass with the full `OrchestratorOutput` snapshot for resume.\n- The next round's `brief.md` embeds the LLM-derived directive instead of the deterministic template.\n\nIf an orchestrator dispatch fails (timeout, malformed JSON after the single\nrepair attempt, non-zero exit), the run finalizes as `failed`, emits a\n`run:failed` event, and exits `1`. Earlier successful passes stay in the\ncheckpoint so a resume is clean.\n\n```bash\n# Two-round run with orchestrator-driven resolution\nagent-swarm run 2 \"Should we adopt server components?\" \\\n  --preset product-decision \\\n  --resolve orchestrator \\\n  --timeout-ms 300000\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eagent-swarm doctor\u003c/code\u003e\u003c/summary\u003e\n\n`agent-swarm doctor` validates your setup before a run. Output is grouped into\nthree sections:\n\n- **Configuration** - `.agent-swarm/config.yml` parses cleanly; configured carry-forward docs exist and are readable (truncated docs are flagged); the agent and preset registries load; any agents or preset referenced in the project config resolve; the configured backend is supported.\n- **Harness inventory** - all four harnesses (Claude, Codex, OpenCode, Rovo) are probed for availability and auth, even when there is no project config. A harness that is missing or unauthenticated but not required by your configured agents is reported as **WARN** (non-fatal). If a failing harness is required by one or more configured agents it is reported as **FAIL** with `required by: \u003cagent...\u003e` attribution and install/auth guidance. agent-swarm does not globally require any harness - a single-harness setup passes doctor when its required harness works.\n- **Agent summary** - each configured agent is mapped to its resolved harness. When there is no project config, the default `product-triad` preset's agents are shown.\n\nWhen config is read from the legacy `.swarm/config.yml` path, doctor reports it\nexplicitly and points you to `.agent-swarm/config.yml`. Exit codes:\n\n- `0` - everything is ready.\n- `1` - at least one check failed (with actionable per-check messages).\n- `2` - internal command error.\n\n```bash\nagent-swarm doctor\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePresets - Codex/OpenCode \u0026amp; custom\u003c/summary\u003e\n\n#### Codex and OpenCode presets\n\nThe Codex and OpenCode presets pin agents to their respective harnesses. When\n`--resolve orchestrator` is active and every selected agent resolves to the same\nharness, the orchestrator follows along.\n\n- **Claude** (default) - requires `claude` on `PATH` with an existing `claude auth login` session.\n- **Codex** - requires `codex` on `PATH`, authenticated with `codex login`, and new enough to support `codex exec`. Use `--backend codex` only when you want to override unpinned agents at the run level.\n- **OpenCode** - requires `opencode` on `PATH`, authenticated with `opencode auth login`.\n\n```bash\n# Codex\nagent-swarm run 1 \"Should we adopt server components?\" \\\n  --preset product-decision-codex \\\n  --timeout-ms 300000\n\n# OpenCode\nagent-swarm run 1 \"Should we adopt server components?\" \\\n  --preset product-decision-opencode \\\n  --timeout-ms 300000\n```\n\n#### Custom presets\n\nPresets resolve from three roots, first match wins:\n\n| Source        | Path                                            | Scope          |\n| ------------- | ----------------------------------------------- | -------------- |\n| Project-local | `.agent-swarm/presets/**/*.yml` / `**/*.yaml`   | This repo      |\n| User-global   | `~/.agent-swarm/presets/**/*.yml` / `**/*.yaml` | Your machine   |\n| Bundled       | _(ships with agent-swarm)_                      | Always present |\n\nPreset files may be grouped in subdirectories for readability; folder names are\norganization only, not namespaces. A project-local preset with the same `name`\nas a bundled preset fully replaces it for that project. A user-global preset\noverrides bundled machine-wide but yields to project-local. Duplicate `name`\nvalues within a single root are an error.\n\n\u003e **Legacy paths.** The previous `.swarm/presets/` (and `~/.swarm/presets/`) locations are still read as a fallback for one release. When both exist, the `.agent-swarm/` path wins. Move your presets to `.agent-swarm/presets/` when convenient.\n\nA preset is a YAML object with required `name` and `agents`, plus optional\n`description`, `resolve`, `goal`, and `decision`:\n\n```yaml\nname: product-decision\ndescription: Product and engineering framing for major product bets\nagents:\n  - product-manager\n  - principal-engineer\nresolve: orchestrator\ngoal: Decide on migration strategy\ndecision: Adopt / Defer / Reject\n```\n\nPreset names use lowercase letters, numbers, `-`, or `_`; `agents` lists 2-5\nagent names.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eProject config (\u003ccode\u003e.agent-swarm/config.yml\u003c/code\u003e)\u003c/summary\u003e\n\nOptional. Set defaults so teammates don't have to remember the flags.\n\n```yaml\npreset: product-decision\n# or, instead of preset:\n# agents: [product-manager, principal-engineer]\nbackend: claude\ngoal: Decide on migration strategy\ndecision: Adopt / Defer / Reject\nresolve: off # off | orchestrator | agents\ntimeoutMs: 300000 # default 120000\ndocs:\n  - docs/architecture.md\n```\n\n**Precedence: CLI flags \u003e config values \u003e preset defaults.** Everything is\noptional - when there's no config file, CLI flags fully describe the run.\nValidation errors (unknown keys, wrong types) are reported by `agent-swarm\ndoctor` and at run start.\n\nRun `agent-swarm init` to create this file with safe defaults (`preset:\nproduct-triad`, `resolve: off`, `timeoutMs: 300000`). It only ever touches\n`.agent-swarm/config.yml`, never overwrites an existing config without `--force`,\nand the values it writes are still overridden by CLI flags.\n\nA legacy `.swarm/config.yml` is still read when `.agent-swarm/config.yml` is\nabsent (the `.agent-swarm/` path wins if both exist); `agent-swarm doctor` flags\nthe legacy path so you can migrate.\n\nConfigured `docs` use the same carry-forward behavior as repeated `--doc` flags:\npaths are normalized, readable files are required, and each doc contributes at\nmost 4,000 characters. `timeoutMs` accepts a positive integer and matches\n`--timeout-ms`.\n\nSupported keys: `preset`, `agents` (2-5 names), `backend`, `resolve`,\n`timeoutMs`, `goal`, `decision`, `docs`. The `rounds` key is reserved but not yet\napplied - pass `\u003crounds\u003e` on the CLI.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAgents - bundled, formats, pinning \u0026amp; output schema\u003c/summary\u003e\n\nAgent definitions are YAML or Markdown files resolved from three roots (first\nwins):\n\n| Path                                                       | Scope                                   |\n| ---------------------------------------------------------- | --------------------------------------- |\n| `.agent-swarm/agents/**/*.yml` / `**/*.yaml` / `**/*.md`   | Project-local                           |\n| `~/.agent-swarm/agents/**/*.yml` / `**/*.yaml` / `**/*.md` | User-global                             |\n| _(bundled)_                                                | Ships with agent-swarm; see table below |\n\nAgent files may be grouped in subdirectories for readability; folder names are\norganization only, not namespaces. A project-local agent with the same `name` as\na bundled agent fully replaces it. A user-global agent overrides bundled\nmachine-wide but yields to project-local. Duplicate `name` values within the\nsame root are an error.\n\n\u003e **Legacy paths.** The previous `.swarm/agents/` (and `~/.swarm/agents/`) locations are still read as a fallback for one release, after their `.agent-swarm/` equivalents. When the same agent name exists in both, the `.agent-swarm/` definition wins.\n\n#### Bundled agents\n\n| Agent                         | Role                                                               |\n| ----------------------------- | ------------------------------------------------------------------ |\n| `product-manager`             | User value, scope, and decision framing                            |\n| `principal-engineer`          | System design, feasibility, and operational risk                   |\n| `product-engineer`            | Product engineering scope, implementation shape, and delivery risk |\n| `product-designer`            | UX, usability, and user-journey perspective                        |\n| `code-reviewer`               | Correctness, maintainability, and regression risk                  |\n| `implementation-skeptic`      | Scope creep, hidden coupling, and brittle assumptions              |\n| `test-risk-reviewer`          | Test coverage, release risk, rollback, and proof quality           |\n| `first-time-user`             | Onboarding clarity, setup friction, and early comprehension        |\n| `busy-operator`               | Workflow fit, repeated use, and time-to-result pressure            |\n| `skeptical-buyer`             | Adoption barriers, value proof, and willingness to keep using it   |\n| `product-manager-codex`       | Codex-backed product decision framing                              |\n| `principal-engineer-codex`    | Codex-backed engineering feasibility                               |\n| `product-manager-opencode`    | OpenCode-backed product decision framing                           |\n| `principal-engineer-opencode` | OpenCode-backed engineering feasibility                            |\n| `orchestrator`                | Coordinator persona for between-round context and resolve modes    |\n\n#### YAML format\n\n```yaml\nname: product-manager\ndescription: Strategic product perspective\npersona: \u003e\n  You are a senior product manager focused on user outcomes,\n  market timing, and business viability.\nprompt: \u003e\n  Evaluate the topic from a product strategy lens. Consider\n  user impact, competitive landscape, and delivery risk.\nbackend: claude # or codex\n```\n\n#### Markdown format\n\nMarkdown agents use YAML frontmatter (validated against the same schema) with the\nbody as the prompt:\n\n```markdown\n---\nname: principal-engineer\ndescription: Deep technical architecture perspective\npersona: \u003e\n  You are a principal engineer focused on system design,\n  scalability, and long-term maintainability.\nbackend: claude # or codex\n---\n\nEvaluate the topic from a technical architecture lens. Consider\nsystem complexity, operational burden, and migration risk.\n```\n\n#### Pinning harness and model\n\nEach agent can pin its runtime harness and model independent of the run-level\n`--backend`:\n\n| Field     | Values                                | Default                                                         |\n| --------- | ------------------------------------- | --------------------------------------------------------------- |\n| `harness` | `claude`, `codex`, `opencode`, `rovo` | Falls back to the run-level backend, then the agent's `backend` |\n| `model`   | Any non-empty string                  | Harness default (the harness chooses)                           |\n\n**Resolution order per agent (first wins):** `agent.harness` → run-level\n`--backend` or project `backend` → `agent.backend`. When `--resolve orchestrator`\nis active without a run-level backend override, the bundled orchestrator inherits\nthe selected agents' harness if all agents resolve to the same harness; mixed\nswarms keep the orchestrator on its default. The resolved `(harness, model)` pair\nis captured in `manifest.json` under `agentRuntimes` and surfaced in each agent's\nper-round markdown header (`Harness:` / `Model:`).\n\nThis unlocks **mixed-harness swarms**: route one agent through Claude and another\nthrough Codex, OpenCode, or Rovo Dev in the same run, as long as each harness's\nCLI is installed and probes successfully. Claude, Codex, and OpenCode must be\nauthenticated; Rovo requires `acli` with the `rovodev` plugin to be runnable.\n\n```yaml\n# .agent-swarm/agents/pm-mixed.yml - Claude with a pinned model\nname: pm-mixed\ndescription: Product manager dispatched via Claude\npersona: You are a rigorous product manager.\nprompt: Evaluate the topic and return the swarm JSON contract.\nharness: claude\nmodel: claude-sonnet-4-5\n```\n\n```yaml\n# .agent-swarm/agents/pe-mixed.yml - Codex, harness-default model\nname: pe-mixed\ndescription: Principal engineer dispatched via Codex\npersona: You are a principal engineer.\nprompt: Evaluate the topic and return the swarm JSON contract.\nharness: codex\n```\n\n```bash\nagent-swarm run 1 \"Should we adopt mixed-harness swarms\" \\\n  --agents pm-mixed,pe-mixed \\\n  --resolve off\n```\n\nWhen `agent.model` is set, every harness adapter forwards it to its CLI: `claude\n--model`, `codex -m`, `opencode --model`, `acli rovodev run --model`. Omit\n`agent.model` to let the harness pick a default. At run start, the CLI fails fast\nif any agent requests an unimplemented harness.\n\n#### Agent output schema\n\nEach agent must return JSON of the following shape:\n\n```json\n{\n  \"agent\": \"product-manager\",\n  \"round\": 1,\n  \"stance\": \"Adopt with caveats\",\n  \"recommendation\": \"Proceed with a phased migration...\",\n  \"reasoning\": [\"...\"],\n  \"objections\": [\"...\"],\n  \"risks\": [\"...\"],\n  \"changesFromPriorRound\": [],\n  \"confidence\": \"high\",\n  \"openQuestions\": [\"...\"]\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRun artifacts \u0026amp; synthesis\u003c/summary\u003e\n\nEvery run produces a self-contained directory under `.agent-swarm/runs/`:\n\n```\n.agent-swarm/runs/20260419-121439-should-we-adopt-server-components/\n├── manifest.json          # Run metadata (id, status, topic, goal, decision, rounds, backend, agents, agentRuntimes, timestamps)\n├── checkpoint.json        # Durable recovery checkpoint after completed rounds\n├── events.jsonl           # Append-only orchestration event ledger\n├── messages.jsonl         # Append-only staged/committed message ledger\n├── seed-brief.md          # Initial brief sent to all agents in round 1\n├── carry-forward-docs/    # Optional doc excerpts with provenance snapshots\n│   ├── manifest.json\n│   └── doc-01.md\n├── round-01/\n│   ├── brief.md\n│   └── agents/\n│       ├── product-manager.md\n│       └── principal-engineer.md\n├── round-02/\n│   ├── brief.md           # Includes prior-round packet and orchestrator pass context\n│   └── agents/...\n├── synthesis.json         # Deterministic synthesis output\n└── synthesis.md           # Human-readable synthesis report\n```\n\nWhen agent runtimes are resolved, `manifest.json` includes `agentRuntimes` and\nper-agent markdown files include `Harness:` and `Model:` header fields.\n\n**Synthesis** is deterministic - no LLM call. It aggregates every agent output to\nproduce:\n\n- **Consensus** - unanimous stance across the final round\n- **Stance tally** - count of each unique stance\n- **Top recommendation** - picked by highest confidence with alphabetical tie-break\n- **Shared risks** - risks flagged by 2+ agents, deduplicated across rounds\n- **Deferred questions** - deduplicated across all rounds, rendered in `synthesis.md`\n- **Overall confidence** - rounded average of all agent confidence levels\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eTerminal UX\u003c/summary\u003e\n\nTwo rendering modes:\n\n- **Live** (default, TTY) - phase banner, per-agent status rows with elapsed timers, flicker-free cell-based diff rendering.\n- **Quiet** (`--quiet` or non-TTY) - structured one-line-per-event log output for CI.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMigration from \u003ccode\u003e.swarm\u003c/code\u003e\u003c/summary\u003e\n\nThis CLI was previously published as `swarm` and stored data under `.swarm/`. It\nis now `agent-swarm`, storing project/user data under `.agent-swarm/`. For at\nleast one release, the legacy `.swarm/` locations - project config, agents,\npresets - are still read as a fallback, with the new `.agent-swarm/` path winning\nwhen both exist; new run artifacts are written under `.agent-swarm/runs/`.\nMigrate by moving `.swarm/` to `.agent-swarm/` when convenient.\n\nIt also remains contract-compatible with the Python swarm prototype: agent\ndefinitions, output schemas, and artifact layout follow the same contracts, so\nautomation that consumes run artifacts keeps working.\n\n\u003c/details\u003e\n\n## Contributing\n\nWorking on `agent-swarm` itself? See [CONTRIBUTING.md](CONTRIBUTING.md) for the\ndev loop, the real-harness smoke gate, the release process, and an architecture\nmap. [ARCHITECTURE.md](ARCHITECTURE.md) goes deeper on runtime internals and\n[SPEC.md](SPEC.md) is the durable runtime contract. The browsable docs site lives\nin [docs/](docs/) and is published at\n\u003chttps://calvinnwq.github.io/agent-swarm/\u003e. Release history lives in\n[CHANGELOG.md](CHANGELOG.md).\n\n## Support and security\n\nUse [GitHub issues](https://github.com/calvinnwq/agent-swarm/issues) for bugs and\nfeature ideas. See [SUPPORT.md](SUPPORT.md), [SECURITY.md](SECURITY.md), and the\n[code of conduct](CODE_OF_CONDUCT.md).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalvinnwq%2Fagent-swarm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcalvinnwq%2Fagent-swarm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalvinnwq%2Fagent-swarm/lists"}