Multi-Agent

Swarmie multi-agent orchestration is implemented in core tooling and surfaced in the TUI.

Primary sources:

• Agent tools and lifecycle: crates/core/src/orchestration_tools/spawn_worker.rs
• Tool registration: crates/core/src/orchestration_tools/mod.rs
• Agent focus + keybindings: crates/tui/src/app/update/keys.rs
• /agent slash behavior: crates/tui/src/input/slash.rs, crates/tui/src/app/update/commands.rs
• Session orchestration loop: crates/core/src/orchestrator.rs

Orchestration workflow

A typical workflow:

1. Ask the main agent to delegate work with orchestration tools (spawn_agent, send_input, wait, close_agent, resume_agent, merge_agents).
2. Let sub-agents run in parallel on scoped tasks.
3. Check status in TUI and switch focus between agents.
4. Wait for completion and merge/close when done.

/agent in the TUI is for listing or switching focused agent context. It does not itself spawn workers.

Switching and focusing agents

Use keyboard focus controls while in multi-agent state:

• Ctrl+N: focus next agent
• Ctrl+P: focus previous agent
• Tab with empty input: cycle agent focus

When focus changes, the output pane is rebuilt from that agent's buffered events and the footer agent label updates.

Mailbox and inter-agent messaging

Swarmie includes a mailbox tool (crates/core/src/orchestration_tools/mailbox.rs) with actions:

• send, reply, broadcast
• inbox, outbox, thread

Use this for structured coordination between specialist agents instead of mixing all updates into one stream.

Worktree isolation

When running in a git repo, sub-agents can get isolated worktrees (crates/core/src/worktree/).

Worktree creation is gated in should_create_worktree() and currently requires:

• repository root available
• more than one active agent
• write-capable tool set (write/edit/patch, or empty allowlist)

On close, Swarmie attempts auto-commit + worktree cleanup.