throng: a swarm of coding agents verified by real builds and tests

# throng

**A swarm of coding agents, one verification engine underneath.**

Point throng at a repository and give it a goal. Dozens or thousands of agents work on it in parallel, each in its own isolated copy. Every build and test they ask for goes through one shared engine that runs on all your cores. The swarm hands back only a change that the real test suite passed.

It's written in Rust and ships as one Windows executable. It runs local models through Ollama for free, or Anthropic and OpenAI-compatible APIs.

```
❯ Make every test in tests/stats.rs pass by fixing the bugs in src/lib.rs
⏺ swarm s47792557 · 6 agents · fanout · ollama/qwen2.5-coder:7b
  ⎿ w-3    edited src/lib.rs +1 -1
  ⎿ w-3    pass test · 3 ok · hit · 0ms
  ⎿ w-3    ✓ verified 5 steps · 1 file(s) +2 -2
⏺ verified · 2 of 6 agents produced a passing change · 19.2s
    -    xs.iter().fold(0, |a, b| a - b)
    +    xs.iter().fold(0, |a, b| a + b)
❯ /apply
applied src/lib.rs
```

## Three ways in

**1. In a terminal.** `cd` into any repo and run `throng`. Type a goal. You see each agent's edits and test results live, then the verified diff. `/apply` writes it into your files, and `/help` lists everything else (`/agents 50`, `/model`, `/verify`, `/diff`, `/agent w-3`, ...).

**2. The desktop app.** Double-click `throng.exe`, or run `throng app`. Every agent is a point of light on the Swarm Field: colour is its state, glow is its token traffic, and each check visibly flies into the engine at the centre. Core Lanes shows which CPU core is running which agent's build, right now. Click any agent to read its whole transcript: reasoning, tool calls, diffs and test results.

**3. From Claude Code (or any MCP client).** throng is an MCP server, so an agent like Claude can hand work to a swarm and get back a verified patch:

```
claude mcp add throng --scope user -- throng mcp
```

| Tool | What it does |
| --- | --- |
| `throng_swarm` | start a swarm on a repo with a goal |
| `throng_improve` | "make it better": self-improving rounds that learn the project |
| `throng_knowledge` | what swarms have learned about a repo, with each lesson's measured effect |
| `throng_status` | progress, per-agent state, recent events; can block until done |
| `throng_result` | final status, the engine's verification, the full patch |
| `throng_apply` | write the verified change into the working tree (refuses if you edited those files since) |
| `throng_agent` | one agent's transcript |
| `throng_verify` | run a repo's tests through the cached engine, with real exit codes and failing test names |
| `throng_stop`, `throng_env` | stop a swarm; see what this machine has |

`throng_verify` is useful on its own. It gives an assistant a test runner that answers instantly for code it has already seen, and it re-runs only the test binaries a change can affect.

## Make better: a swarm that learns your project

Press **Make better** in the app (or type `/improve` in the terminal, or call `throng_improve`) and throng works on the project in rounds:

1. **Plan.** A planner reads the code, runs the tests, and picks the most valuable improvements it can find: real bugs, missing tests, error handling, performance, confusing code. It has the project's knowledge in hand, including what earlier rounds already did and what failed.
2. **Work.** As many agents as you allow take one improvement each, in parallel, in isolated copies.
3. **Verify.** Only changes that pass the real test suite are merged. The next round builds on top of them.
4. **Reflect.** A reflection agent reads what every agent tried and why the engine failed it, then writes lessons: where things live, conventions, traps.
5. **Repeat,** starting smarter.

### The mirror

AI agents don't improve from experience on their own. Each run starts from zero, and if you just let them keep notes, they confidently teach themselves mistakes. So every project gets a **knowledge base** that is *measured*, not just written:

- **Lessons** come from agents (every agent can leave some when it finishes) and from the reflector.
- **Attempts** record every task tried, whether it was verified, and the engine's actual reason for any failure: failing test names and output. Agents see earlier attempts at similar tasks, so the same mistake isn't repeated.
- **Breakage** records which files broke which tests, and which tests are flaky. This comes straight from the engine, with no model involved.
- **Measured effect.** When a lesson is relevant to a task, it's shown to the agent most of the time and deliberately withheld at random the rest of the time. A lesson's score is the difference in success rate between agents that saw it and agents that didn't. Helpful lessons rise, and lessons that measurably hurt are retired automatically.

Every swarm on a project, not only Make better, reads from and writes to its knowledge. It lives in throng's data folder, never in your repo, with a readable `KNOWLEDGE.md` you can open at any time. `/knowledge` shows it in the terminal; the Knowledge tab shows it in the app.

## Why an engine

Parallel agents usually get one git worktree each, and each worktree builds and tests from cold. Twenty agents means twenty full builds of the same code, twenty `target/` folders, and a machine that runs out of memory. Under that load the tests start failing for reasons that have nothing to do with the code.

throng's engine owns the cores instead:

- **Content-addressed results.** Every test unit's result is keyed by the exact bytes of the files it depends on, which the engine learns from the compiler's dep-info. If agent 7 asks about code agent 2 already tested, the answer is instant and carries the original exit code and output.
- **Coalescing.** Identical checks from different agents share one run.
- **Test impact.** Edit one integration test and only that test binary rebuilds and runs.
- **Warm slots.** A few build slots per project, each with its own warm `target/`. Dependencies are hard-linked from the first build, never rebuilt.
- **Core lanes.** On hybrid CPUs, a check an agent is waiting on gets the fast cores, and speculative pre-checks use the efficient ones. Allocations change live through job objects.
- **Honest failures.** Flaky tests are re-run in isolation before a failure is believed. A crashed compiler or an out-of-memory kill is retried, never recorded as a code error.
- **Nothing escapes.** Every job runs in a Windows job object on a private, invisible desktop, with UI restrictions. A test that runs `start http://localhost:8080` can't open a tab in your browser, and anything it spawns dies with the job.

### Measured

These runs use a real 1,770-test Rust project (Every-Other-Token), with 5 agents making different edits over 4 rounds (`docs/bench`):

| | wall time | CPU time | rounds fully passing |
| --- | --- | --- | --- |
| 5 plain worktrees | 1,037 s | 7,659 s | 2 of 4 (ran out of memory; false test failures) |
| 5 agents on throng | 171 s | 1,730 s | 4 of 4 |

With 20 agents on the same project, all 4 rounds pass for every agent: 1,770/1,770 tests each. See `docs/bench/engine-20.*`.

## Safety

Agents work on snapshots, never your files. By default a built-in guard blocks `git push`, the GitHub CLI, network tools and reads of credential files (`.env`, SSH keys, cloud configs). Commands run offline. Every block is shown in the UI and recorded in the run folder. A verified result lands on a local `throng/<id>` branch and as a patch file. Your working tree changes only when you `/apply`, and only if the files it touches are unchanged since the swarm started.

## Build

```
cd ui && npm install && npm run build && cd ..
cargo build --release -p throng
throng --selftest
```

`node ui/e2e/run.mjs` drives a real swarm through the UI in headless Edge and saves screenshots to `docs/shots`.

Crates: `engine` (verification engine, no AI in it), `harness` (agent loop, providers, swarm patterns, guard), `app` (desktop app, terminal, MCP server, local HTTP bridge).