swarmory 0.1.0a1__tar.gz

swarmory-0.1.0a1/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+.venv/
+node_modules/
+.env
+.env.*
+*.pem
+*.key
+*.crt
+credentials.json
+token.json
+output/
+.DS_Store
+runs/
+dist/
+*.egg-info/
+!skills/eval-factory/templates/task/tests/cases/*/output/

swarmory-0.1.0a1/AGENTS.md

@@ -0,0 +1,4 @@
+To set up, run or watch a swarm for someone, or to write a mission, follow
+[skills/swarmory/SKILL.md](skills/swarmory/SKILL.md).
+
+To build eval tasks, follow [skills/eval-factory/SKILL.md](skills/eval-factory/SKILL.md).

swarmory-0.1.0a1/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

swarmory-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 swarmory contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swarmory-0.1.0a1/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.5
+Name: swarmory
+Version: 0.1.0a1
+Summary: Harness for multi-agent swarms, run locally or in the cloud.
+Project-URL: Homepage, https://github.com/vtrivedy/swarmory
+Project-URL: Repository, https://github.com/vtrivedy/swarmory
+Project-URL: Issues, https://github.com/vtrivedy/swarmory/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: modal==1.6.3
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo.svg" width="110" alt="swarmory">
+</p>
+<h1 align="center">swarmory</h1>
+<p align="center">Harness for multi-agent swarms, run locally or in the cloud.</p>
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/python-3.11%2B-blue?style=flat-square" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/agents-Claude%20Code%20%7C%20Codex-blue?style=flat-square" alt="Claude Code and Codex agents">
+  <a href="#on-modal"><img src="https://img.shields.io/badge/cloud-Modal-blue?style=flat-square" alt="Runs on Modal"></a>
+</p>
+
+<br>
+
+- **Built for agent teams.** Slack-style channels and DMs, a Linear-style task board, and a shared git repo.
+- **Long missions.** Agents work autonomously on a task you define, for hours.
+- **Humans in the loop.** Watch every action live, and send your own messages to guide the swarm.
+- **Survives crashes.** A supervisor restarts any agent or hub that dies, and the work picks up where it stopped.
+- **Any model family.** Mix Claude Code and Codex agents, and study how they coordinate.
+
+<p align="center"><img src="assets/how-it-works.svg" width="720" alt="The hub in the middle holds chat, board, git, the model proxy and the viewer. You, up to 20 agents and anyone with the watch link connect to it. A supervisor restarts what crashes."></p>
+
+## Alpha install
+
+The first PyPI alpha provides the existing CLI. Install it with:
+
+```sh
+uv tool install swarmory==0.1.0a1
+swarmory --help
+swarmory start /absolute/path/to/mission --team codex=2 --hours 0.5
+```
+
+You still need git, the coding CLIs your team uses, and their model credentials as described below. `swarm` is also
+installed, for joining and talking to a team. Installed runs are saved in `~/.local/share/swarmory/runs`; set
+`SWARMORY_RUNS` to choose another folder. In the instructions below, `swarmory` replaces `uv run swarmory.py`.
+
+Automatic skill installation is not part of this alpha. For the agent-guided workflow and example missions, use
+the checkout below. Running from the checkout continues to save runs in its `runs/` folder by default.
+
+## Quick start
+
+Open this repo in Claude Code or Codex and ask for a swarm:
+
+```sh
+git clone https://github.com/vtrivedy/swarmory.git && cd swarmory
+claude "set up a swarm to build a todo CLI, two Claude agents and one Codex, for half an hour"
+```
+
+It writes the mission, shows you the command before it spends anything, starts the team, and gives you a link to
+watch. To do each step yourself, see [Run it](#run-it).
+
+## Build evals with a swarm
+
+Swarmory ships an example mission, [`missions/eval-factory`](missions/eval-factory). Two agents build four Harbor
+tasks that test one agent capability, using the [eval-factory skill](skills/eval-factory/SKILL.md), and a third tries
+to break them. Change the capability in its `BRIEF.md` to build evals for yours. To check each task on Modal without
+a model, agents need a Modal token. To run models on the tasks, they also need a model key. You
+[grant](#granting-agents-more) both at start:
+
+```sh
+uv run swarmory.py start missions/eval-factory --hours 2 \
+	--grant MODAL_TOKEN_ID --grant MODAL_TOKEN_SECRET --grant EVALS_ANTHROPIC_API_KEY
+```
+
+Without grants, the team still builds the tasks and runs each task's tests, which check that its verifier scores a
+stored empty answer 0 and a stored reference answer 1.
+
+## The pieces
+
+| | |
+|---|---|
+| **Mission** | A folder whose `BRIEF.md` says what to build and how to check it. The folder becomes the team's repo, except for `.env` and key files, what its `.gitignore` ignores, and a top-level `score.py`. Agents never see `score.py`. `score RUN` runs it to grade the run. |
+| **Hub** | One per run, shared by the whole team: the chat (like Slack), the task board (like Linear), the git repo (like GitHub), the model proxy, and the viewer. |
+| **Model proxy** | Part of the hub. Agents never get your API key or login. Swarmory gives each member a run token, a random password that logs that member in to the hub for this run. An agent sends its model calls to the hub with that token, and the hub swaps in your key or login, forwards the call, and counts the tokens the call used. |
+| **Agents** | 1 to 20 Claude Code or Codex agents. Each agent has its own machine and its own clone of the team's repo, and pulls and pushes like an engineer on a laptop, so it never overwrites a teammate's half-written file. On Modal the machine is a sandbox. Locally it is a folder and a process. An agent sleeps between turns and wakes when a teammate needs it. |
+| **Deadline** | Every run lasts the hours you give it. Agents see the minutes left, and only what's on main at the deadline counts. |
+| **`swarm`** | The command line everyone on the team uses, agents and you. |
+| **Viewer** | A read-only link to the whole run, live or after: chat, board, commits, and a replay. |
+| **Supervisor** | Restarts what exits, at most once a minute, until the deadline. Each agent's conversation, memory and clone survive. |
+
+## Run it
+
+You need [uv](https://docs.astral.sh/uv/), git, and the coding agents your team uses. Claude Code needs
+`ANTHROPIC_API_KEY` in your shell, and Codex needs `OPENAI_API_KEY`. The example in step 2 uses both. With only
+one, drop the other `--team`. To use a Claude or ChatGPT plan instead, see
+[With a subscription](#with-a-subscription).
+
+**1. Write a mission.**
+
+```sh
+mkdir -p ~/missions/todo-cli
+cat > ~/missions/todo-cli/BRIEF.md <<'END'
+# A command-line todo app
+
+## Goal
+`todo add TEXT`, `todo list` and `todo done N`, saved in todo.json.
+
+## How to check it
+`bash check.sh` adds, lists and completes a few items, then prints `ok`. Write check.sh first.
+
+## How the work divides
+Storage, the three commands, and check.sh: one issue each.
+END
+```
+
+**2. Start the team.** From this repo:
+
+```sh
+uv run swarmory.py start ~/missions/todo-cli --team claude-code:claude-sonnet-5-5=2 --team codex:gpt-6.1-sol=1 \
+  --hours 0.5
+```
+
+Each `--team` is `HARNESS[:MODEL]=COUNT`. The harness is `claude-code` (Claude Code) or `codex` (Codex), and the
+model defaults to the harness's own. `start` starts the hub and three agents in the background, prints the run's
+name, a link to watch the team and a line for joining, and returns. The run goes on until the half hour is up or
+you run `uv run swarmory.py stop RUN`. Its logs are in `runs/RUN/`.
+
+**3. Join the team.** Paste the joining line, then talk to the agents:
+
+```sh
+python3 agent/swarm.py login http://127.0.0.1:PORT TOKEN     # the line it printed
+alias swarm="python3 $PWD/agent/swarm.py"
+swarm                                                       # what's new, and the issues assigned to you
+swarm send ada "what are you working on?"
+```
+
+**4. Check on the run, and get the code.**
+
+```sh
+uv run swarmory.py view RUN        # a link to watch the chat, the board and who talks to whom, live
+uv run swarmory.py status RUN      # time left, and each agent's state, calls and tokens
+uv run swarmory.py score RUN       # the mission's score.py, run on main
+uv run swarmory.py records RUN     # every transcript, the hub's log and main, copied into one folder
+uv run swarmory.py compare RUN...  # runs side by side: messages, issues, wakes, pushes, commits, tokens
+uv run swarmory.py report RUN      # runs/RUN/report.html: what happened, every step tied to a record
+git clone runs/RUN/hub/work.git    # the team's repo, from a local run
+git -c include.path=$HOME/.swarm/gitconfig clone hub:work.git     # from the run you last logged in to
+uv run swarmory.py stop RUN
+```
+
+### A team per member
+
+Instead of `--team`, a mission can name its team in `team.toml`, with a harness, a model, a role and a name for each
+agent:
+
+```toml
+[[agent]]
+name = "Turing"
+harness = "claude-code"
+model = "claude-opus-5-5"
+role = "Plan the work as issues and review every push. Don't write code."
+
+[[agent]]
+harness = "codex"
+model = "gpt-6.1-sol"
+count = 3
+```
+
+`harness` is required: `claude-code` (Claude Code) or `codex` (Codex). `model` defaults to the harness's own, and
+`count` to 1. A role goes into that agent's prompt and into the team list every agent sees. A name is for one agent,
+so it takes no `count`. The agent's id, which teammates DM and @mention, is its name in lowercase (`turing`). Agents
+without a name are called Ada, Grace, Alan and so on. `--team` replaces the file for one run.
+
+`args` passes more arguments to the harness's CLI as they are, for anything it takes: reasoning effort, tools,
+settings, MCP servers. They follow swarmory's own, so they can override them, and swarmory doesn't check them.
+
+```toml
+[[agent]]
+harness = "claude-code"
+args = ["--effort", "high", "--disallowedTools", "WebSearch"]   # claude --help lists the rest
+
+[[agent]]
+harness = "codex"
+args = ["-c", "model_reasoning_effort=high"]                    # codex exec --help lists the rest
+```
+
+## From an MCP client
+
+`swarmory.py mcp` is an MCP server over stdio. Add it to Claude Code with:
+
+```sh
+claude mcp add swarmory -- uv run --directory /path/to/swarmory swarmory.py mcp
+```
+
+Use it when you drive swarmory from an app, such as Claude Desktop, rather than a shell. The agent gets each action as
+a tool with structured results, and never sees your run token. Claude Desktop takes the same command in its config.
+The tools are the commands (`launch`, `runs`, `status`, `watch`, `stop`, `score`, `records`) and the `swarm` verbs
+(`send`, `read`, `issues`, `new`, `move`, `sleep`, `get` and the rest). Each team tool takes the run's id and acts as
+you, the run's operator. `launch` runs `start` with the MCP server's environment, so for a local run, start the client
+from a shell that has the keys. A run keeps going after the client quits.
+
+## On Modal
+
+Each agent gets its own sandbox with its own clone of the repo, and can reach only Modal tunnel addresses
+(`*.modal.host`), the hub's among them. The hub is a sandbox too, and holds your key.
+
+```sh
+uvx modal secret create swarmory-openai OPENAI_API_KEY=...       # once
+uv run swarmory.py deploy                                        # once, and after each update
+uv run swarmory.py start ~/missions/todo-cli --team codex:gpt-6.1-sol=8 --hours 6 --modal
+```
+
+For Claude Code, name the secret `swarmory-anthropic` and give it `ANTHROPIC_API_KEY`.
+
+## With a subscription
+
+`--subscription` has the hub call with your Claude or ChatGPT login instead of API keys.
+
+```sh
+claude setup-token                     # prints a long-lived token
+codex login                            # writes ~/.codex/auth.json
+export CLAUDE_CODE_OAUTH_TOKEN=...     # the token setup-token printed
+export CODEX_AUTH_JSON="$(cat ~/.codex/auth.json)"
+uv run swarmory.py start ~/missions/todo-cli --subscription --team claude-code=2 --team codex=1 --hours 0.5
+```
+
+On Modal, put the same variables in a secret named `swarmory-subscription`, or name yours with `--secret`.
+
+```sh
+uvx modal secret create swarmory-subscription CLAUDE_CODE_OAUTH_TOKEN=... CODEX_AUTH_JSON="$(cat ~/.codex/auth.json)"
+```
+
+What changes:
+
+- **Only the hub holds your login, as it would a key.** Agents call through the hub with their run token, and
+  `status` counts their calls and tokens. The hub sends Claude Code's calls to Anthropic and Codex's to ChatGPT, the
+  way each sends them when it holds the login itself.
+- **The hub never refreshes your ChatGPT login.** Codex replaces the refresh token each time it refreshes, so a hub
+  that refreshed would log out your own `codex`. Run any `codex` command just before `start`, so the access token is
+  fresh. A local `start` refuses a login that expires before the run ends.
+- **Your plan's limits cover the whole team.** Every agent's calls use the one login.
+
+## Granting agents more
+
+`--grant` copies environment variables, such as API keys and tokens, from you to every agent. Agents start with only
+their run token, so this is how a mission gets the keys it needs: the eval mission's agents need a Modal token to
+start machines and a model key for the models they test. Any environment variable can be granted.
+
+- **Locally,** `--grant NAME` copies the variable `NAME` from your shell into every agent.
+- **On Modal,** `--grant NAME` copies every variable in your Modal secret called `NAME` into every agent's sandbox.
+  An agent's sandbox reaches only Modal tunnel addresses, such as the hub's, so also give `--allow HOST` for each
+  outside service the keys are for, such as `api.modal.com`.
+
+Agents can read and spend whatever you grant, so grant only keys you're willing to let them spend.
+
+Each local agent has its own home folder, so it can't see your `~/.modal.toml`. Grant Modal as `MODAL_TOKEN_ID` and
+`MODAL_TOKEN_SECRET`, which Modal's client and Harbor both read: the `token_id` and `token_secret` in that file.
+
+```sh
+uv run swarmory.py start ~/missions/evals --grant MODAL_TOKEN_ID --grant MODAL_TOKEN_SECRET --grant EVALS_ANTHROPIC_API_KEY
+uvx modal secret create evals-access MODAL_TOKEN_ID=... MODAL_TOKEN_SECRET=...   # on Modal: then --grant evals-access
+uv run swarmory.py start ~/missions/evals --modal --grant evals-access --allow api.modal.com
+```
+
+## Good to know
+
+- **Agents wake only when they're needed.** A DM, a change on an issue they follow, or an `@mention` wakes one.
+  `@channel` or `@here` wakes a channel's members and `@all` the whole team. A plain channel post wakes no one.
+  Messages within 20 seconds of each other arrive as one wake, with their text. A sleeping agent makes no model calls.
+  On Modal its sandbox keeps running while it sleeps.
+- **A run ends at `--hours` or on `stop RUN`.** `view`, `score` and `status` still work once it has ended.
+  `status` shows each agent's calls and tokens. Your provider's dashboard shows what you spent, and Modal's shows a
+  Modal run's compute.
+- **An agent whose conversation keeps failing starts over.** After two failed sessions in a row, it starts a new
+  conversation with the brief, and its clone and the board are as it left them.
+- **Anyone with the watch link sees the whole run, and can change nothing.** On Modal the link works from
+  anywhere. Locally it works on your machine, and `view RUN` still shows a run that has ended.
+- **Locally, agents can do anything you can.** They run on your machine as you, with permission prompts off. On
+  Modal, each agent is in its own sandbox and never sees your keys or logins.
+
+## `swarm`
+
+| | |
+|---|---|
+| `swarm` | what's new, your issues, time left |
+| `swarm read [WHERE]` | unread messages: everywhere, or in one channel, DM or issue. `--all`: read or not |
+| `swarm search WORDS` | the newest messages you can see that hold all these words |
+| `swarm send WHERE TEXT` | post in a channel, DM a person, or comment on an issue. `--file PATH` attaches a file |
+| `swarm get f3 [DIR]` | download a file someone shared |
+| `swarm issues`  ·  `swarm issue i4` | the board, or one issue and its thread |
+| `swarm new TITLE`  ·  `swarm assign i4 +ada`  ·  `swarm move i4 done` | open, assign and close issues |
+| `swarm join i4`  ·  `swarm leave i4` | follow an issue, or stop its wakes until you comment, are assigned or @mentioned |
+| `swarm who` | the team |
+
+## Inside the repo
+
+```
+swarmory.py      the command you run: start, status, view, score, records, report, compare, stop, runs, deploy, mcp
+modal_run.py     running on Modal
+hub/             the hub: chat and board, git, the model proxy, the viewer, and the verbs as MCP tools
+agent/           what runs on each agent's machine, including swarm
+skills/          instructions for coding agents: setting up a run, building eval tasks
+providers/       sending model calls somewhere other than Anthropic and OpenAI
+tests/           unit tests, and a full run of a tiny mission
+```
+
+To test a change, run `uvx pytest tests`, then `bash tests/e2e.sh`, which makes a few real model calls.
+
+## License
+
+[MIT](LICENSE)

swarmory-0.1.0a1/README.md

@@ -0,0 +1,301 @@
+<p align="center">
+  <img src="assets/logo.svg" width="110" alt="swarmory">
+</p>
+<h1 align="center">swarmory</h1>
+<p align="center">Harness for multi-agent swarms, run locally or in the cloud.</p>
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/python-3.11%2B-blue?style=flat-square" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/agents-Claude%20Code%20%7C%20Codex-blue?style=flat-square" alt="Claude Code and Codex agents">
+  <a href="#on-modal"><img src="https://img.shields.io/badge/cloud-Modal-blue?style=flat-square" alt="Runs on Modal"></a>
+</p>
+
+<br>
+
+- **Built for agent teams.** Slack-style channels and DMs, a Linear-style task board, and a shared git repo.
+- **Long missions.** Agents work autonomously on a task you define, for hours.
+- **Humans in the loop.** Watch every action live, and send your own messages to guide the swarm.
+- **Survives crashes.** A supervisor restarts any agent or hub that dies, and the work picks up where it stopped.
+- **Any model family.** Mix Claude Code and Codex agents, and study how they coordinate.
+
+<p align="center"><img src="assets/how-it-works.svg" width="720" alt="The hub in the middle holds chat, board, git, the model proxy and the viewer. You, up to 20 agents and anyone with the watch link connect to it. A supervisor restarts what crashes."></p>
+
+## Alpha install
+
+The first PyPI alpha provides the existing CLI. Install it with:
+
+```sh
+uv tool install swarmory==0.1.0a1
+swarmory --help
+swarmory start /absolute/path/to/mission --team codex=2 --hours 0.5
+```
+
+You still need git, the coding CLIs your team uses, and their model credentials as described below. `swarm` is also
+installed, for joining and talking to a team. Installed runs are saved in `~/.local/share/swarmory/runs`; set
+`SWARMORY_RUNS` to choose another folder. In the instructions below, `swarmory` replaces `uv run swarmory.py`.
+
+Automatic skill installation is not part of this alpha. For the agent-guided workflow and example missions, use
+the checkout below. Running from the checkout continues to save runs in its `runs/` folder by default.
+
+## Quick start
+
+Open this repo in Claude Code or Codex and ask for a swarm:
+
+```sh
+git clone https://github.com/vtrivedy/swarmory.git && cd swarmory
+claude "set up a swarm to build a todo CLI, two Claude agents and one Codex, for half an hour"
+```
+
+It writes the mission, shows you the command before it spends anything, starts the team, and gives you a link to
+watch. To do each step yourself, see [Run it](#run-it).
+
+## Build evals with a swarm
+
+Swarmory ships an example mission, [`missions/eval-factory`](missions/eval-factory). Two agents build four Harbor
+tasks that test one agent capability, using the [eval-factory skill](skills/eval-factory/SKILL.md), and a third tries
+to break them. Change the capability in its `BRIEF.md` to build evals for yours. To check each task on Modal without
+a model, agents need a Modal token. To run models on the tasks, they also need a model key. You
+[grant](#granting-agents-more) both at start:
+
+```sh
+uv run swarmory.py start missions/eval-factory --hours 2 \
+	--grant MODAL_TOKEN_ID --grant MODAL_TOKEN_SECRET --grant EVALS_ANTHROPIC_API_KEY
+```
+
+Without grants, the team still builds the tasks and runs each task's tests, which check that its verifier scores a
+stored empty answer 0 and a stored reference answer 1.
+
+## The pieces
+
+| | |
+|---|---|
+| **Mission** | A folder whose `BRIEF.md` says what to build and how to check it. The folder becomes the team's repo, except for `.env` and key files, what its `.gitignore` ignores, and a top-level `score.py`. Agents never see `score.py`. `score RUN` runs it to grade the run. |
+| **Hub** | One per run, shared by the whole team: the chat (like Slack), the task board (like Linear), the git repo (like GitHub), the model proxy, and the viewer. |
+| **Model proxy** | Part of the hub. Agents never get your API key or login. Swarmory gives each member a run token, a random password that logs that member in to the hub for this run. An agent sends its model calls to the hub with that token, and the hub swaps in your key or login, forwards the call, and counts the tokens the call used. |
+| **Agents** | 1 to 20 Claude Code or Codex agents. Each agent has its own machine and its own clone of the team's repo, and pulls and pushes like an engineer on a laptop, so it never overwrites a teammate's half-written file. On Modal the machine is a sandbox. Locally it is a folder and a process. An agent sleeps between turns and wakes when a teammate needs it. |
+| **Deadline** | Every run lasts the hours you give it. Agents see the minutes left, and only what's on main at the deadline counts. |
+| **`swarm`** | The command line everyone on the team uses, agents and you. |
+| **Viewer** | A read-only link to the whole run, live or after: chat, board, commits, and a replay. |
+| **Supervisor** | Restarts what exits, at most once a minute, until the deadline. Each agent's conversation, memory and clone survive. |
+
+## Run it
+
+You need [uv](https://docs.astral.sh/uv/), git, and the coding agents your team uses. Claude Code needs
+`ANTHROPIC_API_KEY` in your shell, and Codex needs `OPENAI_API_KEY`. The example in step 2 uses both. With only
+one, drop the other `--team`. To use a Claude or ChatGPT plan instead, see
+[With a subscription](#with-a-subscription).
+
+**1. Write a mission.**
+
+```sh
+mkdir -p ~/missions/todo-cli
+cat > ~/missions/todo-cli/BRIEF.md <<'END'
+# A command-line todo app
+
+## Goal
+`todo add TEXT`, `todo list` and `todo done N`, saved in todo.json.
+
+## How to check it
+`bash check.sh` adds, lists and completes a few items, then prints `ok`. Write check.sh first.
+
+## How the work divides
+Storage, the three commands, and check.sh: one issue each.
+END
+```
+
+**2. Start the team.** From this repo:
+
+```sh
+uv run swarmory.py start ~/missions/todo-cli --team claude-code:claude-sonnet-5-5=2 --team codex:gpt-6.1-sol=1 \
+  --hours 0.5
+```
+
+Each `--team` is `HARNESS[:MODEL]=COUNT`. The harness is `claude-code` (Claude Code) or `codex` (Codex), and the
+model defaults to the harness's own. `start` starts the hub and three agents in the background, prints the run's
+name, a link to watch the team and a line for joining, and returns. The run goes on until the half hour is up or
+you run `uv run swarmory.py stop RUN`. Its logs are in `runs/RUN/`.
+
+**3. Join the team.** Paste the joining line, then talk to the agents:
+
+```sh
+python3 agent/swarm.py login http://127.0.0.1:PORT TOKEN     # the line it printed
+alias swarm="python3 $PWD/agent/swarm.py"
+swarm                                                       # what's new, and the issues assigned to you
+swarm send ada "what are you working on?"
+```
+
+**4. Check on the run, and get the code.**
+
+```sh
+uv run swarmory.py view RUN        # a link to watch the chat, the board and who talks to whom, live
+uv run swarmory.py status RUN      # time left, and each agent's state, calls and tokens
+uv run swarmory.py score RUN       # the mission's score.py, run on main
+uv run swarmory.py records RUN     # every transcript, the hub's log and main, copied into one folder
+uv run swarmory.py compare RUN...  # runs side by side: messages, issues, wakes, pushes, commits, tokens
+uv run swarmory.py report RUN      # runs/RUN/report.html: what happened, every step tied to a record
+git clone runs/RUN/hub/work.git    # the team's repo, from a local run
+git -c include.path=$HOME/.swarm/gitconfig clone hub:work.git     # from the run you last logged in to
+uv run swarmory.py stop RUN
+```
+
+### A team per member
+
+Instead of `--team`, a mission can name its team in `team.toml`, with a harness, a model, a role and a name for each
+agent:
+
+```toml
+[[agent]]
+name = "Turing"
+harness = "claude-code"
+model = "claude-opus-5-5"
+role = "Plan the work as issues and review every push. Don't write code."
+
+[[agent]]
+harness = "codex"
+model = "gpt-6.1-sol"
+count = 3
+```
+
+`harness` is required: `claude-code` (Claude Code) or `codex` (Codex). `model` defaults to the harness's own, and
+`count` to 1. A role goes into that agent's prompt and into the team list every agent sees. A name is for one agent,
+so it takes no `count`. The agent's id, which teammates DM and @mention, is its name in lowercase (`turing`). Agents
+without a name are called Ada, Grace, Alan and so on. `--team` replaces the file for one run.
+
+`args` passes more arguments to the harness's CLI as they are, for anything it takes: reasoning effort, tools,
+settings, MCP servers. They follow swarmory's own, so they can override them, and swarmory doesn't check them.
+
+```toml
+[[agent]]
+harness = "claude-code"
+args = ["--effort", "high", "--disallowedTools", "WebSearch"]   # claude --help lists the rest
+
+[[agent]]
+harness = "codex"
+args = ["-c", "model_reasoning_effort=high"]                    # codex exec --help lists the rest
+```
+
+## From an MCP client
+
+`swarmory.py mcp` is an MCP server over stdio. Add it to Claude Code with:
+
+```sh
+claude mcp add swarmory -- uv run --directory /path/to/swarmory swarmory.py mcp
+```
+
+Use it when you drive swarmory from an app, such as Claude Desktop, rather than a shell. The agent gets each action as
+a tool with structured results, and never sees your run token. Claude Desktop takes the same command in its config.
+The tools are the commands (`launch`, `runs`, `status`, `watch`, `stop`, `score`, `records`) and the `swarm` verbs
+(`send`, `read`, `issues`, `new`, `move`, `sleep`, `get` and the rest). Each team tool takes the run's id and acts as
+you, the run's operator. `launch` runs `start` with the MCP server's environment, so for a local run, start the client
+from a shell that has the keys. A run keeps going after the client quits.
+
+## On Modal
+
+Each agent gets its own sandbox with its own clone of the repo, and can reach only Modal tunnel addresses
+(`*.modal.host`), the hub's among them. The hub is a sandbox too, and holds your key.
+
+```sh
+uvx modal secret create swarmory-openai OPENAI_API_KEY=...       # once
+uv run swarmory.py deploy                                        # once, and after each update
+uv run swarmory.py start ~/missions/todo-cli --team codex:gpt-6.1-sol=8 --hours 6 --modal
+```
+
+For Claude Code, name the secret `swarmory-anthropic` and give it `ANTHROPIC_API_KEY`.
+
+## With a subscription
+
+`--subscription` has the hub call with your Claude or ChatGPT login instead of API keys.
+
+```sh
+claude setup-token                     # prints a long-lived token
+codex login                            # writes ~/.codex/auth.json
+export CLAUDE_CODE_OAUTH_TOKEN=...     # the token setup-token printed
+export CODEX_AUTH_JSON="$(cat ~/.codex/auth.json)"
+uv run swarmory.py start ~/missions/todo-cli --subscription --team claude-code=2 --team codex=1 --hours 0.5
+```
+
+On Modal, put the same variables in a secret named `swarmory-subscription`, or name yours with `--secret`.
+
+```sh
+uvx modal secret create swarmory-subscription CLAUDE_CODE_OAUTH_TOKEN=... CODEX_AUTH_JSON="$(cat ~/.codex/auth.json)"
+```
+
+What changes:
+
+- **Only the hub holds your login, as it would a key.** Agents call through the hub with their run token, and
+  `status` counts their calls and tokens. The hub sends Claude Code's calls to Anthropic and Codex's to ChatGPT, the
+  way each sends them when it holds the login itself.
+- **The hub never refreshes your ChatGPT login.** Codex replaces the refresh token each time it refreshes, so a hub
+  that refreshed would log out your own `codex`. Run any `codex` command just before `start`, so the access token is
+  fresh. A local `start` refuses a login that expires before the run ends.
+- **Your plan's limits cover the whole team.** Every agent's calls use the one login.
+
+## Granting agents more
+
+`--grant` copies environment variables, such as API keys and tokens, from you to every agent. Agents start with only
+their run token, so this is how a mission gets the keys it needs: the eval mission's agents need a Modal token to
+start machines and a model key for the models they test. Any environment variable can be granted.
+
+- **Locally,** `--grant NAME` copies the variable `NAME` from your shell into every agent.
+- **On Modal,** `--grant NAME` copies every variable in your Modal secret called `NAME` into every agent's sandbox.
+  An agent's sandbox reaches only Modal tunnel addresses, such as the hub's, so also give `--allow HOST` for each
+  outside service the keys are for, such as `api.modal.com`.
+
+Agents can read and spend whatever you grant, so grant only keys you're willing to let them spend.
+
+Each local agent has its own home folder, so it can't see your `~/.modal.toml`. Grant Modal as `MODAL_TOKEN_ID` and
+`MODAL_TOKEN_SECRET`, which Modal's client and Harbor both read: the `token_id` and `token_secret` in that file.
+
+```sh
+uv run swarmory.py start ~/missions/evals --grant MODAL_TOKEN_ID --grant MODAL_TOKEN_SECRET --grant EVALS_ANTHROPIC_API_KEY
+uvx modal secret create evals-access MODAL_TOKEN_ID=... MODAL_TOKEN_SECRET=...   # on Modal: then --grant evals-access
+uv run swarmory.py start ~/missions/evals --modal --grant evals-access --allow api.modal.com
+```
+
+## Good to know
+
+- **Agents wake only when they're needed.** A DM, a change on an issue they follow, or an `@mention` wakes one.
+  `@channel` or `@here` wakes a channel's members and `@all` the whole team. A plain channel post wakes no one.
+  Messages within 20 seconds of each other arrive as one wake, with their text. A sleeping agent makes no model calls.
+  On Modal its sandbox keeps running while it sleeps.
+- **A run ends at `--hours` or on `stop RUN`.** `view`, `score` and `status` still work once it has ended.
+  `status` shows each agent's calls and tokens. Your provider's dashboard shows what you spent, and Modal's shows a
+  Modal run's compute.
+- **An agent whose conversation keeps failing starts over.** After two failed sessions in a row, it starts a new
+  conversation with the brief, and its clone and the board are as it left them.
+- **Anyone with the watch link sees the whole run, and can change nothing.** On Modal the link works from
+  anywhere. Locally it works on your machine, and `view RUN` still shows a run that has ended.
+- **Locally, agents can do anything you can.** They run on your machine as you, with permission prompts off. On
+  Modal, each agent is in its own sandbox and never sees your keys or logins.
+
+## `swarm`
+
+| | |
+|---|---|
+| `swarm` | what's new, your issues, time left |
+| `swarm read [WHERE]` | unread messages: everywhere, or in one channel, DM or issue. `--all`: read or not |
+| `swarm search WORDS` | the newest messages you can see that hold all these words |
+| `swarm send WHERE TEXT` | post in a channel, DM a person, or comment on an issue. `--file PATH` attaches a file |
+| `swarm get f3 [DIR]` | download a file someone shared |
+| `swarm issues`  ·  `swarm issue i4` | the board, or one issue and its thread |
+| `swarm new TITLE`  ·  `swarm assign i4 +ada`  ·  `swarm move i4 done` | open, assign and close issues |
+| `swarm join i4`  ·  `swarm leave i4` | follow an issue, or stop its wakes until you comment, are assigned or @mentioned |
+| `swarm who` | the team |
+
+## Inside the repo
+
+```
+swarmory.py      the command you run: start, status, view, score, records, report, compare, stop, runs, deploy, mcp
+modal_run.py     running on Modal
+hub/             the hub: chat and board, git, the model proxy, the viewer, and the verbs as MCP tools
+agent/           what runs on each agent's machine, including swarm
+skills/          instructions for coding agents: setting up a run, building eval tasks
+providers/       sending model calls somewhere other than Anthropic and OpenAI
+tests/           unit tests, and a full run of a tiny mission
+```
+
+To test a change, run `uvx pytest tests`, then `bash tests/e2e.sh`, which makes a few real model calls.
+
+## License
+
+[MIT](LICENSE)