The Swarm
How chemx coordinates several agents in one checkout: leases, claims and gates, one recorded run and the known limits.
From finding to proven done
1 of 6
Audit
The audit ratchet fails a change when any rule's violation count rises in a file.
2 of 6
Task
Work is queued as a task with a tier (light, standard or deep) and a target file.
3 of 6
Claim
One handle claims the task. Tasks can be handed off.
4 of 6
Lease
The handle leases each file before editing. Other handles' chemx edits (patch, write) to it are refused while the lease is live.
5 of 6
Patch
chemx patch and write check that the result parses and report new violations.
6 of 6
Gate
chemx team task done runs the same gate rule and refuses on a CRITICAL or HIGH hazard in the target file, or when any rule's violation count there is higher than at HEAD.
What each guard does, and what it does not
| Mechanism | Does | Does not guarantee |
|---|---|---|
| Leases (chemx team lock) | Hold one file for one handle for 5 minutes from its last chemx call. Other handles' patch, write, autofix and explode on it are refused while it is live. | Tell whether the holder has finished editing, only that it still claims the file. A lease with no chemx activity for 5 minutes lapses. It does not stop an edit made outside chemx (raw shell, scripts, or native tools without an installed hook). |
| Claims (chemx team task claim) | Record one handle as the owner of a task and renew that handle's leases. Only the assignee or creator may hand a task off. | Close themselves. A claim with no later done, blocked or cancelled is reported by audit-run and fails the run. |
| chemx commit | Commit only the listed files, refuse --no-verify and -n, run the pre-commit hook (if none is installed nothing runs and the gate line says so), and refuse a file under another handle's live lease or a commit with no task id unless --no-task=<reason> is given. | See a lease taken after its check, or say what the hook checks: the gate line reports only that a hook ran and exited 0. |
| chemx status | List changed files with each file's live lease (holder, purpose, task, minutes left) and flag a file with no live lease or leased by another handle. | Settle who is right. A flag is a hint: unleased can also mean a finished edit. |
| chemx wait | Poll every 3 seconds for a task, a lock to be free or an idle verify. Exit 0 when met, 2 on timeout. | Take the lease for you. Leasing the file is a separate step before the first edit. |
One recorded run, with the command to re-run it
One run, not a benchmark suite. It does not predict your project. Re-run the commands on a machine that has the run's transcripts.
| Result and how to reproduce it |
|---|
29 agents, 11 tasks, $5.65 Dispatch run validation-1 chemx team audit-run --run=wf_afacbbe8-24c ; chemx report savings --run=wf_afacbbe8-24c Measured 2026-10-09 Feed #7240, #7241 |
0 lease lapses, 0 unleased edits Audit of the validation-1 transcripts chemx team audit-run --run=wf_afacbbe8-24c Measured 2026-10-09 Feed #7240, #7241 |
Three jobs, one session
A family chore game project lives in one checkout that many AI sessions share. When the session started, 17 live sessions had their working directory inside the checkout. The owner typed three jobs from a phone: fix a failing Android build, merge or delete the worktrees, and sync master. chemx named a replacement for each raw command, proved which branches were already in master before anything was removed, and logged every escape from its guard with a reason. The write-up is a draft for the owner's review.
Full write-up (in the project repository): docs/case-studies/2026-10-27-three-jobs-one-session.md
A model and effort per task tier
| Tier | Model | Effort |
|---|---|---|
| light | haiku or sonnet | low |
| standard | sonnet | medium |
| deep | opus | high |
$5.65 actual, $8.51 priced at Opus (1.5x)
Routing price of the validation-1 run
chemx report savings --run=wf_afacbbe8-24c
Measured 2026-10-09
same tokens priced per model
$3.48 against $77.84 priced at Opus (22.4x)
Haiku hazard swarm, two runs
chemx team tokens --run=<id>
Measured 2026-10-09
Feed #6190, #7499
runs 2451 and 2507, same tokens priced per model
What chemx does not do yet
- Forge is not finished. Recall on the labeled ground truth is 17 of 26 (65%) against a 70% target, and it surfaced 0 of 11 in set B and 0 of 7 in set C. Blueprints and heal are still landing, and the 1 s warm-run target is not met.
- A running MCP server keeps the code it loaded. After an upgrade it runs each call in a slower fresh process until you reconnect once with /mcp.
- Short flags are not validated: a mistyped -x is not caught.
- npm lags main. CI publishing is blocked (task #1948), so installed behavior may differ from the docs. chemx --version tells you the build.
- The coordination rows live in the monorepo root db, but a package database keeps its own code index until it is rebuilt, and keeps serving team rows until chemx team migrate merges it.
- Hooks are advice with limits. The guard reads command text and does not sandbox a script that writes files itself.
- Dispatch proves little by itself. chemx renders the script and checks the run afterwards; it cannot show that an agent did its task.