# Swarm

Background subagents running alongside your main session.

Type `/swarm` to open the dashboard, then `n` to spawn one. Each agent is a separate `zot` subprocess with its own model loop, its own persistent session file, and its own chat in the dashboard — but they all run in the same working directory as the host, so they see and edit the same files you do.

There is no per-agent worktree or branch. If you need parallel edits on isolated checkouts, set that up yourself with `git worktree` outside zot.

## Command line

```tui
/swarm                            # open the dashboard
/swarm new <task>                 # spawn an agent
/swarm new --model gpt-5 <task>    # pin the new agent to a model
/swarm logs <id>                  # jump into one transcript
/swarm send <id> <text>           # send a follow-up
/swarm resume                     # bring back a stopped agent
/swarm kill <id>                  # stop a running agent
/swarm remove <id>                # delete the agent's state
```

## Persistence across restarts

Each agent keeps its event log and session under `$ZOT_HOME/swarm/agents/<id>/`. After restarting zot, previously spawned agents appear as detached. Open `/swarm` to inspect them or use `/swarm resume <id>` to continue one.

Startup reads only the last 4 MiB of each large event log. Opening the dashboard or resuming an agent loads its full log on demand, which can briefly delay that action for very large logs. The displayed transcript retains at most the most recent 2000 lines. The full event log remains on disk.

## Auto-swarm

With `/settings` -> auto-swarm on, the main agent can fork sub-agents on its own via a built-in `swarm_spawn` tool when a request splits into independent parallel work. When the last sub-agent finishes, zot injects a single `auto-swarm update` message back into the main chat with each agent's status, task, and complete final response. If an agent produced no assistant response, the update includes a truncated transcript tail for diagnostics instead.