> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prbe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent swarms

> Run many research agents at once and still see which branch is winning, what each one cost, and reach any of them.

When a dozen coding agents run experiments in parallel, three things get hard: telling which line of work is ahead, knowing where the agent time and money went, and keeping one agent from redoing what another already ruled out. Every agent with Probe on writes its work to the same Probe record, so all three are answered there, for you and for the agents.

## Every agent starts from what the others tried

With Probe on, each session records its projects, experiments and runs, whether [the daemon](https://docs.prbe.ai/agents/daemon.md) records or the agent does. Before an agent starts something, it reads what the team already did, the other agents included: with `probe ask` when the daemon runs, through the [MCP server](https://docs.prbe.ai/agents/mcp.md) otherwise.

An experiment that went nowhere is marked so, with the reason, and the next agent reads it:

```bash theme={null}
probe experiment set lr-warmup-sweep --dead-end "loss diverges past lr 3e-4 at every warmup length"
probe experiment set lr-warmup-sweep --clear-dead-end     # it was not a dead end after all
```

Its branch reads `dead_end` until a run of it is live again. It still ranks.

## Which branch is winning

A project declares one **headline metric**: the number that ranks its work, and which way is better. An experiment can override it for itself.

```bash theme={null}
probe project set folding --metric eval/dockq --goal max                  # --reduce final (default) or best
probe experiment set dockq-long-context --metric eval/dockq_long --goal max
```

Probe ranks the branches on that metric, each by its best run, and names the **leader**. When another line of work has a value too, it also names the runner-up (that line's best branch) and the gap; otherwise the read says `no_other_line`. An experiment that overrides the metric is ranked with the others using the same override, not against the project's metric. The **pick** is the experiment someone decided is best, with the reason:

```bash theme={null}
probe project set folding --best dockq-long-context --reason "best DockQ, and stable across 3 seeds"
probe workspace set structure-lab --best dockq-long-context --reason "the one to build on"
```

The agents doing the work set the metric and the pick as they go and tell you in one line; the dashboard shows both. An agent never writes over a person's metric or pick: the CLI refuses and names whose it is. `--metric ""` and `--best ""` clear them.

## Lines of work and branches

A **branch** is a chain of experiments that continue one another; it splits where two experiments fork from the same parent. Where the first experiment of a tree forks, each fork starts its own **line of work**; forks further down stay inside their line. Each branch has a state, first match wins:

| State | Means |
| - | - |
| `live` | A run of it is running and still reporting |
| `dead_end` | Its newest experiment is marked a dead end |
| `concluded` | Its newest experiment has a conclusion, and no activity came more than five minutes after the experiment's last change |
| `stopped` | Its newest run failed, crashed or was cancelled, with no activity more than five minutes after |
| `active` | Worked on in the last 24 hours |
| `idle` | Nothing for 24 hours or more |

```bash theme={null}
probe project branches folding      # each line of work: best value, rank, effort, state
```

An agent reads the same thing through the MCP server: `entity` with `view="branches"` on a project or an experiment gives the ranking and one summary per branch, and `view_options.branch` gives one branch in full, its experiments as rows. A workspace's history is `browse` with `mode="branches"`.

On the workspace canvas, the pick carries a star and the path to it is drawn through the experiments that led there.

## Where the time and money went

Every branch carries its effort, read from the sessions that worked on it:

| Field | Means |
| - | - |
| `agent_h` | Agent hours: the sessions' active time on this branch, in five-minute buckets, so parallel agents add up |
| `agent_wall_h` | The same time with parallel agents counted once |
| `sessions_top` | The two sessions with the most time on it, e.g. `codex 2.9h · pi 2.1h` |
| `cost_usd` | The daemon's recorded model spend plus the agents' own tokens at list price, split by time. `cost_estimated` says list prices were used: an estimate, not your bill. `null` means unknown, never 0 |

A session's cost is unknown when it used a model with no known price; a partial sum is never shown.

On the canvas, **Canvas settings → Show effort** colours each experiment by its agent hours in the window you picked (**24h**, **7d**, **30d** or **All**), from green for the least to red for the most. Under **Live** it shows only experiments with a live run, coloured by their last hour.

## Reach a running agent

Send one of your own running sessions a message. The branches read names each branch's sessions.

```bash theme={null}
probe session send <session_id> "stop the warmup sweep; branch from dockq-long-context instead"
```

Its daemon puts the message in the agent's mailbox within about 30 seconds, and the agent reads it at its next prompt or tool call; an idle Claude Code or pi is woken. A message sent from the CLI reads as from one of your agent sessions, never as from you: only the dashboard speaks as you. A session with no daemon (Probe off, inline, or headless `-p`) can't be reached: a message not yet received reads `unreachable` while no daemon has checked that session's mailbox in the last two minutes, and `expired` after 12 hours. Messages are up to 2,000 characters.

When a run that a session launched or wrote to crashes or is flagged, the daemon tells that agent the same way, with the same alerts the email sends, so the agent that owns the run hears about it without you relaying it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.