Agent Swarm

What it is

A Node command-line tool that runs a beads task graph with an ntm agent swarm. A watcher keeps agents working, a fresh read-only review runs after each task, test gates sit between waves and a whole-branch review closes the run. It never pushes, merges or deploys.

What it does

• One-command start that collects every launch problem and prints them all before launching anything.
• Watcher that returns tasks claimed too early and flags blocked panes without restarting them.
• Optional mistake ledger: known pitfalls are added to tasks at init, and review findings are recorded when a fix passes.
• Safety checks at start: refuses to run unless the destructive-command guard is the first Bash hook.

The problem

Several coding agents working from one task graph tend to stall, grab the same task, skip review, or pile up on a failing test. This tool runs a task graph with an agent swarm and adds a watcher, a fresh review after each task, test gates between waves and a status file.

Design decisions

• The watcher decides what to do with a pure function over the state it reads, and it takes no action when it cannot read the world. The tradeoff is that it pauses and shows a WATCHER BLIND banner instead of guessing.
• A fresh read-only reviewer checks every task, and a fix task is created if it finds problems. This costs extra model calls per task.
• A wave's tests run again once if they fail, then the next wave pauses. This avoids stopping on a flaky test under load, but a real failure waits a little longer.
• The knowledge-base link can never stop a build. Without a key nothing is sent, and a failing KB shows a flag and is retried.

How it works

1. swarm initReads a plan's task graph, creates the tasks, and adds matching known pitfalls from the knowledge base to each task.
2. swarm startChecks every requirement, such as the destructive-command guard hook, then launches the agents and answers first-run dialogs.
3. AgentsClaude and Codex agents each claim a task, work only on it, and commit.
4. WatcherEvery tick it reads the task graph, git and the panes, nudges idle agents, returns early claims and writes a status file.
5. Reviewer and gatesA fresh reviewer returns a JSON verdict per task, tests run between waves, and a whole-branch review runs at the end.
6. Mistake ledgerWhen a fix passes review, the findings, fix commit and guarding test are sent to the knowledge base.

Security: enforced, simulated and known gaps

• Enforced in code: start refuses unless the destructive-command guard (dcg) is the first Bash hook and answers DENY to a dangerous test command. Full permissions must be requested explicitly.
• The tool runs git read-only and never modifies the other tools it drives. The knowledge-base key is sent only over https or to the local machine, and code from other people's projects is not recorded without their permission.
• Known gap: agents run unattended with permission prompts off, so it should only be used in a worktree the owner trusts.

What broke and how it was fixed

What broke

In the first dogfood run, two agents both wrote the same task's files, idle agents were kept in an error state after a usage-limit banner, and a flaky test timeout paused wave 2 until someone hand-edited a state file.

How it was found

The owner's first real run on a live task needed three manual interventions, which were then recorded as a fix note.

The fix

The agent prompt now says to work only on a task you claimed. A stale error is cleared when the screen shows a ready prompt, a usage-limit banner is detected and flagged with its reset time, a failed wave test is retried once, and a swarm retest command was added.

What guards it now

test/template.test.js pins the claimed-only wording, and the decision rules are covered by test/decide.test.js; the fix note records 174 passing tests.

Reference

fb00507

Where it runs

A command-line tool run from a git worktree, with the watcher in a tmux window. It is not hosted and the source is not public yet.

Who did what

The owner conceived the product, architecture, specs and acceptance tests and directed the work. Coding agents (Claude, Codex, Gemini) did much of the implementation and review, and the commit trailers name Claude models.

Limits and honest status

• Local project, no public repository yet; first commit 2026-10-12, so it is days old.
• Agents run unattended with permission prompts off; --full-permissions is always required.
• swarm init is not safe to re-run after a partial failure.

Connected to

Knowledge Base Server (Memstalker)Daniel (Agent Orchestrator)Browser AgentSoftware Factory