agentainer 0.1.0

package/llms.txt

@@ -0,0 +1,405 @@
+# AgentSwarm
+
+> AgentSwarm runs several coding-agent CLIs (Claude Code, Codex, Gemini, Hermes) at once.
+> Each agent gets its own directory and its own tmux session. A single YAML file defines
+> the agents, the command that launches each one, its first prompt, and — as a strict
+> whitelist — which other agents it is allowed to message.
+>
+> This file is the reference for LLMs asked to write or repair an AgentSwarm config.
+> If you are configuring a swarm, everything you need is below. Verify your work with
+> `./swarm.sh validate --show-prompts`, which parses the config and launches nothing.
+
+## Mental model
+
+- One YAML file describes the whole swarm. `./swarm.sh up` reads it and, for each agent:
+  creates `<root>/<name>/`, installs a turn-completion hook in that folder, opens a tmux
+  session named `<session_prefix><name>`, runs the agent's `command` inside the folder,
+  waits for its input box to become responsive, then types the assembled first prompt in.
+- Agents message each other with `swarm send --to <agent> "text"`. The `swarm` command is
+  on their `PATH` and `SWARM_AGENT` identifies them, so no `--from` is needed. Delivery is
+  refused unless the recipient appears in the sender's `can_talk_to`.
+- A delivered message is pasted into the recipient's pane as
+  `[swarm] message from <sender>:\n<text>`, archived under `.swarm/inbox/<recipient>/`,
+  and written to `.swarm/logs/`.
+
+## Config file
+
+Top level keys: `swarm`, `defaults`, `agent_types`, `agents`, `templates`.
+Only `agents` is required. Relative paths resolve against the config file's directory.
+
+```yaml
+swarm:
+  name: dev-swarm          # label used in prompts/logs; default = config filename
+  root: ./workspace        # parent of the per-agent folders; default ./workspace
+  create_workdirs: true    # auto-create missing agent folders; default true
+  session_prefix: ""       # prepended to tmux session names; default ""
+  send_delay_ms: 150       # pause before pasting into a pane
+  enter_delay_ms: 250      # pause between pasting and pressing Enter
+  max_forward_hops: 3      # auto-forward loop guard
+  ready_timeout_ms: 60000  # how long to wait for an agent's input box to respond
+  busy_timeout_ms: 900000  # after this, an agent stuck "busy" is treated as idle
+  message_format: tagged   # tagged | plain; tagged is the default
+  max_reply_reminders: 1   # how often to nudge an agent whose reply reached nobody
+  resume: false            # make `up` reattach to recorded conversations by default
+  pane_idle_ms: 2500       # quiet time before a `pane` capture counts as a finished turn
+  pane_poll_ms: 700        # pane sampling interval
+  pane_scrollback: 400     # lines of scrollback the pane watcher diffs
+  tmux_history_limit: 50000 # scrollback per agent pane so you can scroll up when attached; 0 = tmux default
+  tmux_mouse: true         # enable mouse-wheel scrolling in the panes
+
+defaults:                  # any agent key; applied to agents that omit it
+  type: claude
+  append_agents_that_you_can_talk_to_prompt: true
+  workdir: "{root}/{name}" # optional; see "Working directories" below
+
+agent_types:               # override built-ins, or define new types
+  claude:
+    command: "claude --dangerously-skip-permissions"
+    capture: hook
+    boot_delay_ms: 3000
+
+agents:
+  - name: developer        # REQUIRED. Used as the folder name AND the tmux session name.
+                           # Must match ^[A-Za-z0-9_][A-Za-z0-9_-]*$
+    type: codex            # claude | codex | gemini | hermes | any key in agent_types
+    command: "codex --yolo"          # exact CLI invocation; defaults to the type's command
+    can_talk_to: [reviewer]          # whitelist. "*" means every other agent. Default: []
+    first_prompt: |                  # typed in after the CLI boots
+      You are the DEVELOPER...
+    first_prompt_file: ./p.md        # alternative to first_prompt (mutually exclusive)
+    forward_responses_to: [reviewer] # auto-relay finished turns; must ⊆ can_talk_to
+    capture: hook                    # hook | pane | none | auto (default: from type)
+    boot_delay_ms: 3000              # grace period before probing the input box
+    ready_probe: true                # wait for the input box to echo a token first
+    busy_check: true                 # refuse incoming mail while this agent is mid-turn
+    parse_outbound_tags: true        # route <swarm-send> blocks written in its replies
+    reply_reminder: true             # nudge it when it owes a reply but sent nothing
+    resume_args: "--resume {session_id}"          # appended to command by `up --resume`
+    resume_command: "bash -ic 'chy3 --resume {session_id}'"  # or replace it entirely
+    workdir: ./somewhere             # default <root>/<name>; see below
+    create_workdir: true             # false => a missing workdir is an error
+    env: {KEY: value}                # extra env vars for its tmux session
+    append_agents_that_you_can_talk_to_prompt: true
+    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: false
+
+templates:                 # override the text AgentSwarm generates
+  comms: |                 # placeholders: {agent} {swarm} {peers} {prefix} {inbox} {workdir}
+    You are {agent}. You may message: {peers}.
+  task_notice: |
+    Stand by. Your real task arrives in the next message.
+  reply_reminder: |        # placeholders: {agent} {sender} {id} {peers} {problems}
+    You owe {sender} an answer to {id}. Send it inside <swarm-send to="{sender}">.
+  send_failed: |           # placeholders: {agent} {peers} {problems}
+    Your message could not be delivered. {problems}
+```
+
+## Working directories
+
+- Default: each agent gets `<root>/<name>`, created on `up`.
+- `workdir` overrides it. Absolute, relative to the config file, or `~`-prefixed.
+  Placeholders: `{name}` `{root}` `{swarm}` `{type}`.
+- `defaults.workdir` applies to every agent that omits it. Include `{name}` to give
+  each agent its own folder; omit it to put the whole swarm in one directory.
+- `create_workdirs` (swarm-level) and `create_workdir` (per-agent) control creation.
+  Set them to `false` when pointing at real repositories, so a mistyped path is an
+  error rather than a new empty folder.
+- Several agents may share one workdir. That is legitimate (pair programming in one
+  checkout) but they will overwrite each other's files and interleave git commits,
+  so `validate` and `up` print a warning.
+- `root` always holds `.swarm/` (logs, inboxes, the `swarm` shim), even when every
+  agent works elsewhere.
+
+## Tagged messages (the default wire format)
+
+Inbound, an agent sees an envelope it can parse unambiguously:
+
+    <swarm-message from="lead" to="reviewer" id="m-eb4105" reply-to="m-3f9a1c">
+    any number of lines, code blocks, backslashes -- all verbatim
+    </swarm-message>
+
+Outbound, the agent writes a block **in its reply**; the capture hook routes it when
+the turn ends. There is no shell involved, hence no quoting or escaping to get wrong:
+
+    <swarm-send to="reviewer" reply-to="m-eb4105">
+    multi-line body
+    </swarm-send>
+
+    <swarm-broadcast>
+    goes to everyone in the sender's can_talk_to
+    </swarm-broadcast>
+
+- `id` is generated per message; `reply-to` is optional and used for threading.
+- Tagged sends are permission-checked exactly like `swarm send`, and are queued
+  automatically if the recipient is busy.
+- A `<swarm-send to="...">` naming something that is not an agent is discarded with a
+  warning (this catches an agent echoing the `AGENT_NAME` placeholder from its prompt).
+- Blocks are removed from the text before `forward_responses_to` runs, so a message
+  addressed to one peer is not also auto-forwarded to everybody.
+- `message_format: plain` restores the `[swarm] message from <sender>:` header.
+  `parse_outbound_tags: false` stops reading tags out of replies. Both are forced off
+  when `capture: none`, since there is nothing to read.
+- With `capture: pane` the tags are recovered from scraped terminal text, so they are
+  only as reliable as the scrape. Prefer hook-captured agents for tag routing.
+
+## Resuming after a restart
+
+- Every captured turn records the agent's conversation id in `<root>/.swarm/sessions.yaml`
+  (claude hands it to the Stop hook; codex's is read from the newest rollout file under
+  that agent's private `CODEX_HOME/sessions`).
+- `swarm up --resume` rebuilds each agent's command from that id, skips re-sending the
+  first prompt, and preserves the agent's queued mail and any reply it still owes.
+- Resume recipes: claude `--resume {session_id}`, codex `resume {session_id}`. Neither
+  gemini nor hermes exposes a session id, so they always start fresh (with a warning).
+- `resume_args` is appended to `command`. If the command invokes the CLI through an
+  alias or wrapper (`bash -ic chy3`), appending is wrong -- set `resume_command` to the
+  full replacement, using `{session_id}` (and optionally `{command}`).
+- Starting an agent fresh removes its stale entry, so a later `--resume` cannot reattach
+  to a conversation that agent never ran.
+- `swarm sessions` prints what is recorded and the exact command that would resume it.
+
+## Reply reminders
+
+A model asked a question will often write the answer as prose and end its turn. That
+prose reaches nobody -- only a `<swarm-send>` block is delivered. So:
+
+- When agent B receives a message from agent A (and B may message A back), B is
+  recorded as owing a reply.
+- If B's turn ends having sent nothing, it is messaged with the `reply_reminder`
+  template: who is waiting, the message id to quote as `reply-to`, and the exact block
+  to write.
+- If B *tried* to send but the block was malformed -- unclosed, missing `to`, unknown
+  recipient, permission denied -- it gets the `send_failed` template naming each fault.
+- At most `max_reply_reminders` nudges (default 1), then AgentSwarm gives up silently.
+- Anything B delivered counts, including an auto-forward via `forward_responses_to`.
+  Reminders are sent from `swarm`, so they never create a reply obligation themselves.
+- `reply_reminder: false` disables it per agent; it is forced off when the agent's
+  tags are not parsed (`capture: none` or `message_format: plain`).
+
+## The two prompt switches
+
+Both are per-agent booleans, both default as shown, and both append to `first_prompt`:
+
+- `append_agents_that_you_can_talk_to_prompt` (default `true`) — appends a block naming
+  the agents this one may message and showing the `swarm send` / `swarm broadcast` / raw
+  `tmux send-keys` syntax. Set it to `false` for an agent with no peers, or when you want
+  to write the communication instructions yourself.
+- `in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt` (default `false`) —
+  appends a "do not start yet, your task arrives in the next prompt" block. Use it for
+  the agent you will drive manually with `swarm send`, so it acknowledges and waits
+  instead of inventing work.
+
+Final prompt order: `first_prompt`, then the comms block, then the task notice.
+
+## capture: how a finished turn is detected
+
+| value | works with | how |
+|---|---|---|
+| `hook` | `claude`, `codex` **only** | the CLI runs a program on turn completion; exact |
+| `pane` | anything | poll the tmux pane and diff it after `pane_idle_ms`; heuristic |
+| `none` | anything | no capture |
+| `auto` | anything | use the agent type's default (this is the default) |
+
+- `claude` → a `Stop` hook in `<agent-dir>/.claude/settings.json`; reads the transcript.
+- `codex` → a private `CODEX_HOME` at `<agent-dir>/.codex/` with a `notify` program.
+- `gemini`, `hermes` → no such facility, so they fall back to `pane`. Setting
+  `capture: hook` on them (or on a custom type) prints a warning and uses `pane`.
+- `pane` capture is terminal scraping. It filters the echo of incoming messages, but
+  spinners and redraws can leak through. When output quality matters, prefer
+  `capture: none` and tell the agent in its prompt to call `swarm send` itself.
+
+`forward_responses_to` requires `capture` to be `hook` or `pane`; combining it with
+`capture: none` is a config error.
+
+## Rules the validator enforces
+
+- agent names are unique and match `^[A-Za-z0-9_][A-Za-z0-9_-]*$`
+- every name in `can_talk_to` and `forward_responses_to` refers to a real agent
+- an agent may not list itself in `can_talk_to`
+- `forward_responses_to` ⊆ `can_talk_to`
+- `forward_responses_to` is empty unless capture is enabled
+- `type` is a built-in or defined under `agent_types`
+- `first_prompt` and `first_prompt_file` are not both set
+
+## Commands
+
+```
+./swarm.sh up [--only a,b] [--restart] [--no-prompt] [--attach]
+./swarm.sh down [--only a,b]
+./swarm.sh restart
+./swarm.sh status
+./swarm.sh attach <agent>
+./swarm.sh send --to <agent> [--from <name>] [--file F] [--queue] [--wait]
+                             [--wait-timeout S] [--ignore-busy] [--force] "message"
+./swarm.sh broadcast "message"
+./swarm.sh queue <agent> [--clear]
+./swarm.sh idle <agent> [--no-drain]
+./swarm.sh inbox <agent> [-n N]
+./swarm.sh logs [agent] [-n N] [-f]
+./swarm.sh validate [--show-prompts]
+```
+
+Config resolution: `-c PATH`, else `$SWARM_CONFIG`, else `./agents.yaml`, else the
+`agents.yaml` beside `swarm.sh`. `./swarm.sh x.yaml` is shorthand for `up -c x.yaml`.
+
+## What an agent sees at runtime
+
+Environment inside every agent's tmux session:
+
+```
+SWARM_AGENT    this agent's name          SWARM_CONFIG   absolute path to the YAML
+SWARM_PEERS    comma-separated can_talk_to SWARM_ROOT    the swarm root directory
+SWARM_SESSION  its tmux session name       SWARM_NAME     the swarm's name
+PATH           has <root>/.swarm/bin first, providing `swarm`
+```
+
+Sending, from inside an agent:
+
+```bash
+swarm send --to reviewer "src/parse.py is ready for review"
+swarm broadcast "I renamed the config module"
+tmux send-keys -t reviewer -l "raw fallback, skips permissions and logging" \
+  && tmux send-keys -t reviewer Enter
+```
+
+Loop guard: a forwarded message carries a hop count that increments on each relay and
+stops at `max_forward_hops`. A message you send with `swarm send` resets it to zero.
+
+## Worked examples in this repo
+
+- `examples/research-swarm.yaml` — hub and spoke: a lead delegates to a scout
+  (gemini), an analyst (codex) and a writer; the writer uses a custom `workdir`.
+- `examples/software-company.yaml` — six agents across all four CLIs with a
+  restricted comms graph (developers talk to the architect and QA, never to
+  each other).
+- `examples/bug-hunt.yaml` — a hands-free pipeline built on `forward_responses_to`:
+  reproduce → diagnose → fix → verify.
+- `examples/existing-repo.yaml` — two agents pairing inside one existing checkout,
+  using `create_workdirs: false` so a wrong path fails instead of being created.
+
+## Recipes
+
+**Hub and spoke** — one orchestrator drives specialists, which reply only to it:
+
+```yaml
+agents:
+  - {name: orchestrator, type: claude, can_talk_to: "*",
+     in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true}
+  - {name: researcher, type: gemini, can_talk_to: [orchestrator]}
+  - {name: developer,  type: codex,  can_talk_to: [orchestrator]}
+```
+
+**Pipeline** — each stage hands off to the next, automatically:
+
+```yaml
+agents:
+  - {name: spec,   type: claude, can_talk_to: [build], forward_responses_to: [build]}
+  - {name: build,  type: codex,  can_talk_to: [review], forward_responses_to: [review]}
+  - {name: review, type: claude, can_talk_to: []}
+```
+
+**Isolated worker** — runs alone, talks to nobody:
+
+```yaml
+agents:
+  - {name: scribe, type: hermes, can_talk_to: [], capture: none,
+     append_agents_that_you_can_talk_to_prompt: false}
+```
+
+## Busy agents (backpressure)
+
+- An agent is "busy" from the moment a message is submitted to it until its next
+  captured turn end. Sending to a busy agent is refused with a message telling the
+  sender to retry later, `--queue`, or `--wait`.
+- `--queue` appends to `<root>/.swarm/run/<agent>.queue.jsonl`; the capture hook that
+  ends the agent's turn drains one message from it. `--wait` blocks until deliverable.
+  `--queue --wait` queues, then blocks until the agent picks the message up.
+- The busy check and the "now busy" write happen inside the recipient's pane lock, so
+  two parallel senders can never both see an idle agent and both deliver.
+- Turn state is two counters (`delivered`, `completed`), not a boolean: a hook that
+  ends turn N may land after a message delivered during turn N. `completed` is clamped
+  to `delivered` on each turn end, because codex folds a queued message into the turn
+  already running, and an incrementing counter would drift and wedge the agent "busy".
+- Only works when the agent is captured. `capture: none` => `busy_check` is forced off
+  and the agent always accepts mail.
+- `busy_timeout_ms` fails open if a capture never fires; `swarm idle <agent>` clears it.
+- Auto-forwarded responses to a busy peer are queued rather than dropped.
+- Queues self-heal: every turn end sweeps other agents and drains any that have gone
+  idle (or gone stale-busy past `busy_timeout_ms`), so a single missed turn-completion
+  cannot strand queued mail forever. A capture only fires when `type` matches the CLI
+  the `command` actually launches — a `type: codex` agent running `claude` never reports
+  turn ends and looks busy forever.
+
+## Subagents and concurrency
+
+- A subagent inherits `SWARM_AGENT`, so `swarm send` from inside one is attributed to
+  the parent agent and checked against the parent's `can_talk_to`.
+- Every write into a pane takes a per-recipient lock (`<root>/.swarm/run/<session>.lock`).
+  Without it, parallel senders interleave: a paste and its Enter are two tmux calls, so
+  one Enter can submit two concatenated messages and another submit nothing.
+- A message delivered to a busy agent is queued by the CLI and processed after the
+  current tool call. It is not lost.
+- `capture: hook` fires when the *agent's* turn ends. Claude `Task` subagents run inside
+  the turn, so the hook waits for them. Backgrounded work ends the turn early: the
+  interim "I will respond when the subagent finishes" is captured (and forwarded), then
+  the real answer is captured when the agent finishes for real. The hop counter stores
+  the hop at which the agent last *received* a message, so a second response reuses the
+  same hop and the loop guard never suppresses the real answer.
+- Claude records subagent turns in the same transcript with `isSidechain: true`. The
+  Stop hook skips them, so subagent chatter is never relayed as the agent's answer.
+- `capture: pane` cannot tell "waiting on a subagent" from "finished": a quiet pane is
+  its only signal, so it forwards the interim message and then the real one. Raise
+  `pane_idle_ms`, or use `capture: none`.
+
+## Verified CLI behaviours (do not "simplify" these away)
+
+- The claude `Stop` hook entry must have **no `matcher` key**. With one, the interactive
+  TUI never runs the hook (headless `-p` still does, which makes this easy to miss).
+- Claude fires `Stop` *before* flushing the assistant message to the transcript. Read it
+  with a short poll, and only consider text after the last user record -- otherwise the
+  hook captures nothing, or re-relays the previous turn's reply.
+- Claude asks "do you trust this folder?" in any new directory, even under
+  `--dangerously-skip-permissions`. Pre-trust it by setting `hasTrustDialogAccepted`
+  for that path in `~/.claude.json` before launching.
+- Long pastes are collapsed into a chip: `[Pasted text #1 +N lines]` (claude),
+  `[Pasted Content N chars]` (codex). Delivery checks must recognise both.
+
+- Claude Code discards keystrokes for several seconds partway through startup
+  (measured on v2.1.205: t=2s landed, t=6s and t=12s were dropped, t=20s landed).
+  A fixed `boot_delay_ms` cannot fix this, which is why `ready_probe` types a
+  throwaway token until the input box echoes it, and why a paste is verified on
+  screen before Enter is pressed.
+- Codex shows a "do you trust this directory?" modal on first run in a new folder;
+  Enter answers the modal instead of submitting the prompt. The generated
+  `<agent>/.codex/config.toml` pre-trusts the agent's workdir to avoid it.
+- TOML is order-sensitive. In that generated config, `notify` must appear above
+  every `[table]` header, or it becomes `projects.<dir>.notify` and codex never
+  calls it.
+- Claude collapses a long paste into a `[Pasted text #1 +N lines]` chip, so the
+  pasted text never appears verbatim on screen. Delivery checks look for the chip
+  as well as for the tail of the pasted text (the head scrolls out of view).
+
+## Gotchas
+
+- A folder and a tmux session are named after each agent; renaming an agent orphans both.
+- Pointing several agents at one `workdir` is allowed and warned about; they share a
+  filesystem and a git index, so they can clobber each other.
+- Two agents with `forward_responses_to` pointing at each other will relay until the hop
+  limit stops them. Prefer one-directional forwarding, or none.
+- `--dangerously-skip-permissions` / `--yolo` let agents run tools unsupervised. Point
+  `root` at a disposable directory.
+- The first prompt is typed into a live TUI. If AgentSwarm reports "could not confirm
+  the text arrived", the CLI is usually stuck behind a modal (login, trust, onboarding);
+  attach to the session and look. Raise `ready_timeout_ms` if it is merely slow.
+- PyYAML is used when installed; otherwise a bundled subset parser handles the config.
+  It supports block maps/sequences, `|` and `>` scalars, flow `[a, b]` / `{a: 1}`,
+  comments and quoting — but not anchors, aliases, tags or multi-document files.
+
+## Files
+
+- [tests/validate.sh](tests/validate.sh): the full suite. Run it after any change; it
+  uses mock agents, so it needs no API key. 48 checks, all must pass.
+- [agents.example.yaml](agents.example.yaml): every option, documented inline.
+- [README.md](README.md): human-facing guide, architecture and troubleshooting.
+- [lib/config.py](lib/config.py): schema, defaults and validation — the source of truth.
+- [lib/swarm.py](lib/swarm.py): tmux orchestration, message routing, capture.
+- [hooks/](hooks/): the Claude `Stop` hook and the Codex `notify` program.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "agentainer",
+  "version": "0.1.0",
+  "description": "Run a configurable swarm of coding-agent CLIs (Claude Code, Codex, Gemini) in tmux and let them talk to each other.",
+  "keywords": [
+    "agents",
+    "ai",
+    "claude",
+    "codex",
+    "gemini",
+    "tmux",
+    "orchestration",
+    "multi-agent",
+    "swarm"
+  ],
+  "homepage": "https://github.com/mehmetcanfarsak/AgentSwarm#readme",
+  "bugs": {
+    "url": "https://github.com/mehmetcanfarsak/AgentSwarm/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mehmetcanfarsak/AgentSwarm.git"
+  },
+  "license": "MIT",
+  "author": "mehmetcanfarsak",
+  "type": "commonjs",
+  "bin": {
+    "agentainer": "bin/agentainer.js"
+  },
+  "files": [
+    "bin/agentainer.js",
+    "lib/*.py",
+    "hooks/*.sh",
+    "scripts/check-deps.js",
+    "swarm.sh",
+    "examples/*.yaml",
+    "agents.example.yaml",
+    "README.md",
+    "llms.txt"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/check-deps.js",
+    "doctor": "node scripts/check-deps.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ]
+}

package/scripts/check-deps.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Dependency doctor for Agentainer.
+//
+// Runs on `npm install` (postinstall) and on demand via `agentainer doctor`.
+// It only checks the things Agentainer itself needs -- python3 and tmux -- and
+// reports on optional agent CLIs (claude, codex, gemini, ...) without ever
+// treating their absence as an error: a user may only ever run one of them.
+//
+// This script NEVER fails the install. Missing tools are reported with hints;
+// the exit code stays 0 so `npm install -g agentainer` always succeeds.
+"use strict";
+
+const { spawnSync } = require("child_process");
+const os = require("os");
+
+function has(cmd, args) {
+  const probe = spawnSync(cmd, args, { stdio: "ignore" });
+  return !probe.error && probe.status === 0;
+}
+
+const platform = os.platform();
+function installHint(pkg) {
+  if (platform === "darwin") return `brew install ${pkg}`;
+  if (platform === "linux")
+    return `sudo apt install ${pkg}   (or your distro's package manager)`;
+  if (platform === "win32")
+    return `${pkg} is not natively supported on Windows; use WSL2`;
+  return `install ${pkg} with your package manager`;
+}
+
+// --- Required: Agentainer cannot run without these -------------------------
+const required = [
+  { name: "python3", ok: has("python3", ["--version"]) || has("python", ["--version"]), hint: installHint("python3") },
+  { name: "tmux", ok: has("tmux", ["-V"]), hint: installHint("tmux") },
+];
+
+// --- Optional: at least one agent CLI, but which one is up to the user ------
+const optional = [
+  { name: "claude", label: "Claude Code", ok: has("claude", ["--version"]) },
+  { name: "codex", label: "Codex CLI", ok: has("codex", ["--version"]) },
+  { name: "gemini", label: "Gemini CLI", ok: has("gemini", ["--version"]) },
+];
+
+const missingRequired = required.filter((r) => !r.ok);
+
+process.stdout.write("\nAgentainer -- checking dependencies\n");
+process.stdout.write("-----------------------------------\n");
+
+for (const r of required) {
+  process.stdout.write(`  [${r.ok ? "ok" : "--"}] ${r.name}${r.ok ? "" : `   -> ${r.hint}`}\n`);
+}
+
+process.stdout.write("\n  Agent CLIs (install whichever you'll actually use):\n");
+for (const o of optional) {
+  process.stdout.write(`  [${o.ok ? "ok" : "  "}] ${o.name.padEnd(8)} ${o.label}\n`);
+}
+
+if (missingRequired.length) {
+  process.stdout.write(
+    "\n!! Missing required tools: " +
+      missingRequired.map((r) => r.name).join(", ") +
+      "\n   Install them, then re-check with:  agentainer doctor\n"
+  );
+} else {
+  const anyAgent = optional.some((o) => o.ok);
+  process.stdout.write(
+    "\nok Core dependencies satisfied." +
+      (anyAgent ? "" : " (No agent CLI detected yet -- install one to start a swarm.)") +
+      "\n"
+  );
+}
+process.stdout.write("\n");
+
+// Always succeed: never abort an npm install over a missing optional (or even
+// required) tool. The launcher re-checks at runtime and fails clearly there.
+process.exit(0);

package/swarm.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# AgentSwarm -- launch a configurable swarm of coding agents in tmux.
+#
+#   ./swarm.sh up                    start every agent in agents.yaml
+#   ./swarm.sh up -c my-swarm.yaml   ...from a different config
+#   ./swarm.sh agents.yaml           shorthand for `up -c agents.yaml`
+#   ./swarm.sh status                see who is running
+#   ./swarm.sh send --to dev "hi"    message an agent
+#   ./swarm.sh attach dev            jump into an agent's tmux session
+#   ./swarm.sh down                  stop everything
+#
+# See README.md for the full reference, or llms.txt if you are an LLM.
+set -euo pipefail
+
+SWARM_HOME="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+export SWARM_HOME
+
+PYTHON="${SWARM_PYTHON:-}"
+if [[ -z "$PYTHON" ]]; then
+  for candidate in python3 python; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+      PYTHON="$candidate"
+      break
+    fi
+  done
+fi
+
+if [[ -z "$PYTHON" ]]; then
+  echo "xx AgentSwarm needs python3 on PATH (or set SWARM_PYTHON)" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "!! tmux was not found on PATH; every command except 'validate' will fail" >&2
+fi
+
+# The config is resolved in lib/swarm.py: -c, then $SWARM_CONFIG, then
+# ./agents.yaml, then the agents.yaml next to this script. Deliberately NOT
+# exported here -- a stale SWARM_CONFIG would shadow the config that a hook
+# discovers from the agent's working directory.
+
+exec "$PYTHON" "$SWARM_HOME/lib/swarm.py" "$@"