{"id":50791527,"url":"https://github.com/swoofer/essaim","last_synced_at":"2026-06-12T11:30:46.166Z","repository":{"id":355954920,"uuid":"1230274422","full_name":"swoofer/essaim","owner":"swoofer","description":"Spawn N coordinated Claude Code agents — orchestrator + behavior catalog. Pairs with @swoofer/promptweave + mcp-coordinator.","archived":false,"fork":false,"pushed_at":"2026-05-24T17:13:23.000Z","size":501,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T17:26:49.540Z","etag":null,"topics":["agents","ai-agents","anthropic","automation","behavior-catalog","claude","claude-code","cli-tool","mcp","model-context-protocol","multi-agent","orchestrator","parallel","typescript","workflow"],"latest_commit_sha":null,"homepage":null,"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/swoofer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"github":["swoofer"],"buy_me_a_coffee":"swoofer"}},"created_at":"2026-05-05T20:59:24.000Z","updated_at":"2026-05-24T17:13:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/swoofer/essaim","commit_stats":null,"previous_names":["swoofer/essaim"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/swoofer/essaim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swoofer%2Fessaim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swoofer%2Fessaim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swoofer%2Fessaim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swoofer%2Fessaim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swoofer","download_url":"https://codeload.github.com/swoofer/essaim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swoofer%2Fessaim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34243051,"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-06-12T02:00:06.859Z","response_time":109,"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":["agents","ai-agents","anthropic","automation","behavior-catalog","claude","claude-code","cli-tool","mcp","model-context-protocol","multi-agent","orchestrator","parallel","typescript","workflow"],"created_at":"2026-06-12T11:30:46.082Z","updated_at":"2026-06-12T11:30:46.161Z","avatar_url":"https://github.com/swoofer.png","language":"TypeScript","funding_links":["https://github.com/sponsors/swoofer","https://buymeacoffee.com/swoofer"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# essaim\n\n**Spawn N coordinated Claude Code agents on your repo. Pick a preset, the orchestrator does the rest.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![npm](https://img.shields.io/npm/v/essaim.svg)](https://www.npmjs.com/package/essaim)\n[![Tests](https://github.com/swoofer/essaim/actions/workflows/test.yml/badge.svg)](https://github.com/swoofer/essaim/actions)\n\n\u003c/div\u003e\n\n[Problem](#the-problem) · [How it works](#how-it-works) · [Quickstart](#quickstart) · [Architecture](#architecture) · [BCE](#bce--behavior-composition-engine) · [Phases](#work-stealing-phases) · [Effort](#effort-profiles) · [CLI](#cli) · [Templates](#portable-templates) · [Quota](#anthropic-quota-pre-flight) · [Config](#configuration) · [Related](#related-projects)\n\n---\n\n## The Problem\n\nWhen multiple developers each use an AI coding agent in parallel on the same repo, things break:\n\n- **Regressions** — Agent A rewrites a module that Agent B was depending on\n- **Duplicated work** — Two agents implement the same feature from different directions\n- **Architectural drift** — Agents make local decisions that conflict with each other's designs\n- **Wasted reconciliation time** — Developers spend hours untangling what the agents did\n\nEach agent works in isolation. None of them know what the others are doing.\n\nessaim fixes this by giving agents a **shared nervous system** — they announce intentions before coding, conflicts are detected before a single line is written, and agents see each other's actions in real-time to agree on an approach.\n\n---\n\n## How It Works\n\n```\nDeveloper A                    Developer B\n    |                               |\n    |  announce_work                |  announce_work\n    v                               v\n+--------------+              +--------------+\n|  Agent α     |  \u003c-- MQTT --\u003e|  Agent β     |\n|  (essaim)    |   push-based |  (essaim)    |\n+--------------+              +--------------+\n        |         MCP HTTP / SSE        |\n        +---------------+---------------+\n                        |\n             +----------v----------+\n             |     mcp-coordinator |\n             |  MCP tools + SQLite |\n             |  MQTT broker        |\n             +---------------------+\n```\n\nThe consultation cycle — **announce → detect → consult → resolve** — runs in the agent-loop without a sidecar. Agents call `announce_work` before coding; the coordinator scores impact and opens a thread on score ≥ 90; MQTT pushes the thread to affected peers between turns; the thread closes on consensus, timeout, or gray-zone auto-resolve.\n\nessaim ships the orchestrator (agent-loop, preset runner, phase scheduler) and the behavior catalog (32 behaviors, 21 presets, 3 composition rules). The coordination server lives in [`mcp-coordinator`](https://github.com/swoofer/mcp-coordinator#readme); the prompt assembly engine in [`@swoofer/promptweave`](https://github.com/swoofer/promptweave#readme). essaim wires them together and ships the CLI.\n\n---\n\n## Quickstart\n\n### Prerequisites\n\n- Node.js \u003e= 20\n- `claude` CLI on PATH (install from [claude.ai/code](https://claude.ai/code))\n- `ANTHROPIC_API_KEY` environment variable set\n\n### Install\n\n```bash\nnpm install -g essaim\n```\n\n### Start the coordinator\n\nessaim delegates all coordination state to `mcp-coordinator`. Start it once:\n\n```bash\nmcp-coordinator server start --daemon\n```\n\n### Run your first swarm\n\n```bash\n# Initialize your project (installs hooks + MCP config)\nessaim init ~/my-project\n\n# Launch 3 coordinated agents on a bug hunt\nessaim run swarm -p ~/my-project --agents 3\n\n# Or run a single agent without orchestration\nessaim solo gardien -p ~/my-project\n```\n\n\u003e The `swarm` preset runs discover → execute phases. Agents discover issues in read-only mode, share findings via the coordinator, then work-steal tasks from the shared pool until the pool is drained.\n\n---\n\n## Architecture\n\n```\nessaim (this package)\n  |\n  +-- @swoofer/promptweave   (BCE engine: assembles prompts from YAML behaviors)\n  |\n  +-- mcp-coordinator        (coordination server: MCP tools, SQLite, MQTT broker, dashboard)\n```\n\nessaim owns the **catalog** (32 behaviors, 21 presets, 3 composition rules, 6 hook scripts), the **orchestrator** (phase scheduler, effort router, work-stealing loop), and the **CLI**. `@swoofer/promptweave` owns the BCE engine (resolver, validator, assembler). `mcp-coordinator` owns everything coordination-side: 26 MCP tools, impact scoring, MQTT broker + topic protocol, SQLite, and the dashboard at `http://localhost:3100/dashboard`.\n\n**For the tool reference, scoring layers, MQTT topics, dashboard panels, and server-side config, read [mcp-coordinator's README](https://github.com/swoofer/mcp-coordinator#readme).** This file documents only essaim's own surface.\n\n---\n\n## BCE — Behavior Composition Engine\n\nEvery agent prompt, hook, and MCP config is **assembled, not written**. essaim ships a catalog of reusable YAML modules; `@swoofer/promptweave` resolves the preset, validates, composes, and emits `prompt.md` + `hooks/*.sh` + `.mcp.json` for each agent.\n\n```\n32 behaviors    21 presets    3 composition rules    6 hook scripts    3 workflow phases\n```\n\n### Three behavioral layers\n\nBehaviors contribute numbered sections that sort deterministically into a final prompt.\n\n| Layer | Sections | Responsibility | Sample behaviors |\n|-------|----------|----------------|------------------|\n| Foundation | 000-009 | Who I am, which project | `project-context`, `user-brief`, `coordinator-rules` |\n| Patterns | 010-029 | How I coordinate | `announce-before-write`, `conflict-resolution`, `worktree-isolation`, `sequential-wait` |\n| Mission | 030-050 | What I actually do | bug-hunting, test-writing, refactoring, code-review, debate, quiz, translation, sequential pipelines — 21 in total |\n| Transversal | 050-099 | Constraints and style | `activity-tracking`, `read-only-mode`, `audit-output` |\n\n### Composition rules\n\nThree rules adapt behaviors automatically based on what's assembled.\n\n| Rule | Trigger | Action |\n|------|---------|--------|\n| `announce-readonly-adaptation` | `announce-before-write` + `read-only-mode` | Section 020 becomes \"before your analysis\" instead of \"before modifying\" |\n| `sequential-then-announce` | `sequential-wait` + `announce-before-write` | Injects section 012: \"wait -\u003e announce -\u003e code\" |\n| `solo-mode-strip` | `coordinator-rules.solo_mode = true` | Strips announce / conflict-resolution entirely; agent works alone |\n\nList the templates the CLI ships with via `essaim list`. To preview what a template assembles (prompt + agent plan) without burning tokens, use `essaim run \u003ctemplate\u003e --dry-run`. Behaviors, presets, and composition rules live under [`behaviors/`](./behaviors/), [`presets/`](./presets/), and [`compositions/`](./compositions/) in this repo — browse them directly to author or edit.\n\n### Read-only audits with a fixed write surface\n\n`read-only-mode` is strict: agents read, analyze, and communicate via MCP threads, but write nothing — no `Write`, no `Edit`, no created files. To carve out an exception for a specific audit report (without lifting the rest of the no-write fence), pair it with `audit-output`:\n\n```bash\nessaim solo gardien -p . \\\n  --set 'audit-output.paths=[\"MIGRATION_AUDIT.md\",\"docs/risks.md\"]'\n```\n\n`gardien` ships with `audit-output.paths = [\"AUDIT.md\"]` by default; override with `--set` for any other artifact path. The pair (`read-only-mode` + `audit-output`) renders as \"no writes — except these exact paths\". Presets that need pure read-only communication (`debat`, `revue-reviewer`, `chaine-review`, `arene-*`) include only `read-only-mode` and write nothing at all.\n\n### Briefing a run with free-form context\n\nEvery preset includes the `user-brief` behavior in slot `001-user-brief` (right after project identity, before any coordination rules). It's a free-form \"system-prompt prefix\" the operator can fill at launch time, no preset edit required. Both fields are optional — when neither is set, nothing renders.\n\n```bash\nessaim run raid -p . --agents 3 \\\n  --set user-brief.brief='We are migrating the checkout from Stripe v3 to v4. Payment-touching code under src/payments/ must NOT be modified without a feature flag.' \\\n  --set user-brief.constraints='[\"No breaking changes to /api/v1/*\",\"Keep Node 18 compat\",\"Each agent commits in its own worktree, no cross-merge\"]'\n```\n\nThe brief lands once per agent prompt and is visible across every phase (discover / review / execute) because `user-brief` is not phase-tagged. Confirm with `essaim run \u003ctemplate\u003e --dry-run` (the assembled prompt size will jump by the brief's length).\n\n**Dispatch caveat (`maitre`, `revue`)**: in lead/worker presets, the lead's brief does NOT auto-propagate to dispatched workers — the dispatch travels through `announce_work(plan: ...)`, not through the worker's prompt. Set the brief on the worker preset too (`maitre-worker`, `revue-reviewer`) — every agent reads its own copy.\n\n---\n\n## Work-stealing Phases\n\nBCE behaviors can declare an optional `phase`. When a preset contains phased behaviors, the orchestrator executes each phase sequentially with different tool permissions.\n\n```\n PHASE      TOOLS       LOOP   PURPOSE\n -----------------------------------------------------------------\n discover   read_only   no     Scan code, list findings\n review     none        no     Dedup against existing threads\n execute    full        yes    Work-stealing — one task at a time\n (no phase) full        no     One-shot (backward-compat)\n```\n\nTasks stay `open` (`keep_open: true`) until atomically claimed via the coordinator's `/api/claim-task`. MQTT pushes `claimed` / `completed` between turns; agents back off (3×10s grace) before declaring the pool drained. Crashed agents have claims auto-released on heartbeat timeout. `phase-review` dedups discoveries into `NEW | DUPLICATE | ENRICHES` before they hit the pool.\n\n---\n\n## Effort Profiles\n\nModel selection is phase-aware: each phase requests an effort level, the orchestrator maps it to a model + thinking keyword + turn budget. `critical:` discoveries auto-promote `low` to `mid`. Lead-worker presets propagate the level into dispatched prompts. Per-phase overrides supported (`phase-discover.effort=mid`).\n\n| Level | Model | Thinking | maxTurns | Cost | Use case |\n|-------|-------|----------|---------:|------|----------|\n| `low` | `claude-haiku-4-5` | none | 15 | $ | Coordination chatter, trivial review |\n| `mid` | `claude-sonnet-4-6` | `think` | 8 | $$ | Discover, standard execute, dispatched work |\n| `high` | `claude-opus-4-6` | `think-hard` | 20 | $$$ | Complex execute with thinking headroom |\n| `max` | `claude-opus-4-6` | `ultrathink` | 60 | $$$$ | Architecture debates, deep reasoning |\n| `auto` | resolved by context | — | — | — | `read_only`/no-tools -\u003e low; loop -\u003e high; else mid |\n\n---\n\n## CLI\n\nessaim ships a CLI binary. All commands:\n\n| Command | Description |\n|---------|-------------|\n| `essaim run \u003ctemplate\u003e [-p path] [--agents N] [--timeout min] [--set k=v] [--dry-run] [--base-ref ref] [--coordinator-url url] [--max-quota-pct pct] [--cleanup]` | Launch coordinated agents using a template. `--dry-run` previews the assembled prompts + agent plan without launching. |\n| `essaim solo \u003ctemplate\u003e [-p path] [--timeout min] [--set k=v]` | Launch a single agent without orchestration |\n| `essaim scan \u003cpath\u003e` | Auto-detect project language, structure, test framework |\n| `essaim init [path] [--url url] [--name name] [--modules list]` | Install hooks + MCP config on a project |\n| `essaim list` | List the templates the CLI ships with |\n| `essaim self-update` | Update to the latest release |\n\n### Examples\n\n```bash\nessaim scan ~/my-project                            # detect language, tests, modules\nessaim run raid -p ~/my-project --dry-run           # preview assembled prompts, no launch\nessaim run raid -p ~/my-project --agents 3          # bug hunt\nessaim run swarm -p ~/my-project --agents 4         # refactoring\nessaim solo gardien -p ~/my-project                 # read-only audit\nessaim run raid -p ~/my-project --set bug-hunting.modules='[\"src/auth\"]'\n```\n\n---\n\n## Portable Templates\n\nLanguage-agnostic templates. `essaim scan` auto-detects the stack; the template generates prompts tuned to the result.\n\n| Template | Pattern | Agents | Phases |\n|----------|---------|--------|--------|\n| `raid` | Bug hunt | 2-3 | discover -\u003e execute |\n| `melee` | Parallel test writing | 2-6 | discover -\u003e execute |\n| `swarm` | Volume refactoring | 3-6 | discover -\u003e execute |\n| `chaine` | Sequential pipeline | 3 | one-shot, staggered |\n| `relais` | Relay improvements | 3 | one-shot, staggered |\n| `revue` | Authors + cross reviewers | 4-8 | one-shot |\n| `maitre` | Lead + workers | 3-5 | one-shot (lead dispatches) |\n| `gardien` | Read-only audit | 1 | one-shot |\n| `debat` | Architecture debate | 3 | one-shot, keep_open |\n| `arene` | Code quiz / trivia | 3 | one-shot, keep_open |\n| `carrefour` | Intentional conflict test | 2-3 | one-shot |\n| `babel` | Documentation translation | 2 | sequential |\n\nFor per-template descriptions and the preset roles each one wires together, run `essaim list presets` or read [`compositions/`](./compositions/) in this repo.\n\n---\n\n## Anthropic Quota Pre-flight\n\n`run` and `solo` check your Anthropic workspace quota before launching N agents, to avoid 429 storms mid-session.\n\n```bash\nessaim run raid -p ~/my-app --agents 4 --max-quota-pct 90\n# Aborts if workspace utilization \u003e= 90%\n```\n\n- Reads usage from the Anthropic API using the key in the environment.\n- Threshold via `--max-quota-pct` flag or `MAX_QUOTA_PCT` env var (default `95`).\n- Back-off when the usage endpoint itself returns 429.\n\nessaim emits the resulting `token_usage` and `quota_update` events to the coordinator; the dashboard widget is rendered by mcp-coordinator.\n\n---\n\n## Token Observability\n\nEvery agent turn is logged via the `tokens` component logger (`input_tokens`, `output_tokens`, `cache_read`, `cache_creation`, `thinking`, model, turn index). A per-run `reports/YYYY-MM-DD-\u003crun-id\u003e.md` aggregates totals by agent / phase / effort, and surfaces `deduped: N` from `phase-review`. Live gauges live in the mcp-coordinator dashboard.\n\n---\n\n## Configuration\n\n`essaim init` writes a per-project `.claude/` (`.coordinator-env`, `settings.json` for MCP registration, BCE-assembled `hooks/`). The variables essaim itself reads are below; server-side `COORDINATOR_*` env vars belong to mcp-coordinator (see its README).\n\n| Variable | Example |\n|----------|---------|\n| `COORDINATOR_URL` | `http://localhost:3100` |\n| `COORDINATOR_AGENT_ID` / `_NAME` / `_MODULES` | `alice-12345` · `Alice` · `src/auth,src/users` |\n| `MAX_QUOTA_PCT` | `95` (overrides the pre-flight default) |\n| `LOG_LEVEL` | `debug` / `info` / `warn` / `error` |\n\nResolution priority: CLI flag → env var → `config.json` → default. If the coordinator has JWT auth on, `essaim init` provisions a token into `.coordinator-env` and essaim attaches it to every MCP HTTP and MQTT request automatically.\n\n---\n\n## Structured Logging\n\nJSON to stdout via [Pino](https://getpino.io/). Component loggers: `orchestrator`, `agent-loop`, `phase-scheduler`, `work-stealing`, `effort`, `quota`, `tokens`. Control verbosity with `LOG_LEVEL=debug|info|warn|error`; pretty-print with `NODE_ENV=development`.\n\n---\n\n## Development\n\n```bash\n# Tests\nnpm test              # 302/303 unit tests pass on macOS/Linux; one Windows-only chmod test is skipped there\nnpm run test:watch\n\n# CLI in dev\nnpm run dev -- list\nnpm run dev -- run raid -p ~/my-project --dry-run\n\n# Build\nnpm run build\n```\n\nessaim is exercised by its own catalog — the `swarm` template was used to refactor essaim's own source during development, producing a working dogfood loop.\n\n---\n\n## Related Projects\n\n| Package | Role |\n|---------|------|\n| [`mcp-coordinator`](https://github.com/swoofer/mcp-coordinator) | Coordination server: 26 MCP tools, SQLite, embedded MQTT broker, live dashboard. essaim agents talk to it over MCP HTTP; push events arrive over MQTT. |\n| [`@swoofer/promptweave`](https://github.com/swoofer/promptweave) | BCE engine: resolves presets, validates behavior YAML, composes outputs. essaim feeds it the catalog; promptweave returns prompt.md, hooks, and MCP config. |\n\n---\n\n## Support\n\nSolo maintainer. If this project saves you time, consider supporting development:\n\n- [GitHub Sponsors](https://github.com/sponsors/swoofer)\n- [Buy Me A Coffee](https://buymeacoffee.com/swoofer)\n\nA star on the repo also helps surface the project to other developers.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswoofer%2Fessaim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswoofer%2Fessaim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswoofer%2Fessaim/lists"}