Runtime
Agents
An agent is a saved way to run Swarm for a specific job. It gives Swarm a name, instructions, optional model settings, and a clear boundary for what that agent is allowed to do. The most important difference is how you use it: as a primary, as a delegated subagent, or as a separate-purpose profile.
Kinds of agents
Primary, subagent, and background describe how an agent is used.
primaryThe agent you interact with in a normal Swarm chat. Only one primary is active at a time; /agents use <name> switches which primary answers you.subagentA helper the primary agent can call for delegated work. Subagents do not replace the current chat; they run as child agents and return results to the primary.backgroundA saved profile for work you want kept separate from everyday chat use. Any saved agent can be used for a background run when the launcher targets it; background profiles are useful when you want agents reserved for special-purpose or non-daily workflows.Mode only describes how the profile is selected and used. Each agent also has an execution contract: it can be plan-enabled, read-only, or read/write. Its tool scope can then narrow or explicitly name the tools it may use, including Swarm management tools. Sensitive actions still follow the permission rules for the current workspace.
Tools
Agents can be configured with these Swarm tools.
readRead file contents with line-number pagination.writeWrite, overwrite, or append workspace files when the agent is allowed to edit.editPatch text files by replacing exact strings.listList files and directories in the workspace.searchSearch workspace files and content with the built-in FFF-backed search.bashRun shell commands in the workspace when enabled; agents can be limited to approved command prefixes.git_statusInspect Git status without shell indirection.git_diffInspect Git diffs without shell indirection.git_addStage files for a commit.git_commitCreate a Git commit using the user’s existing Git configuration.websearchSearch the web through Exa. Works with an Exa API key or the public Exa MCP path when enabled.webfetchFetch selected web pages for deeper reading. Requires an Exa API key.webdownloadDownload web content into workspace files when a page is too large to keep in context. Requires an Exa API key.ask-userAsk the user for a decision or structured input.taskDelegate focused work to one or more subagents. Batch multiple launches in one task call when independent work splits cleanly.skill-useLoad a discovered workspace skill into the current run.manage-skillInspect and manage workspace skills.manage-agentInspect and manage saved agents, custom tools, active primary selection, and subagent assignments.manage-themeInspect, create, update, delete, or set themes.manage-worktreeInspect the workspace worktree branch family and combined commits.manage_todosManage workspace todo items and agent checklists.plan_manageInspect or update saved plans without leaving the current session mode.exit_plan_modeSubmit a plan for approval so a plan-mode session can continue into execution.
An agent does not automatically receive every tool in this list. The active execution contract and tool_scope decide what is enabled for that profile. Web search can use Swarm's built-in public Exa MCP bridge when no Exa API key is configured, or the API-key path after /auth key exa <api_key>. Deep fetch and download require the API-key path.
Delegation reports
Subagents run as child sessions and report back to the parent.
task launchesA task call can launch one subagent or a batch of launches. Each launch names a subagent such as explorer, memory, parallel, or clone; the shared parent prompt stays on the task while each launch can carry its own meta prompt.child modeDelegated children inherit the parent workspace context. If the parent is in plan mode, the child run starts in auto so the subagent can complete the assigned work instead of stopping at a plan.progressTask progress reports the launch index, subagent name, child session, current tool, elapsed time, tool counts, and summary. Delegated assistant text is not streamed as live progress.reportEach subagent’s final assistant response is its report. The task result summarizes the report for the parent; long reports can be capped with report_max_chars and persisted under .swarm/subagent-reports when they exceed the cap.The default report cap is 1,800 characters and the maximum accepted cap is 12,000 characters. For full handoff quality, tell each subagent what evidence and filepaths its final report must include.
Built-ins
Swarm ships with five built-in agent profiles.
swarmGroup: Primary. The default primary orchestration agent for normal user work. Runtime shape: Plan → approval → auto flow is enabled by default. Provider, model, and thinking can inherit the current defaults.explorerGroup: Utility subagent. Repository inspection and evidence collection: map files, summarize architecture, and return path/line evidence. Runtime shape: read-only execution setting. Part of the built-in Utility AI baseline.memoryGroup: Utility subagent. Durable writing for commit messages, session titles, compact summaries, and /commit background commit runs. Runtime shape: read-only profile with a background_commit tool contract: git status, diff, add, and commit enabled; broad editing, web, task, ask-user, and exit-plan tools disabled. Part of the built-in Utility AI baseline. Protected from deletion.parallelGroup: Utility subagent. Creative execution worker for component-level outputs and alternatives. Runtime shape: read/write execution setting. Part of the built-in Utility AI baseline.cloneGroup: Clone subagent. Fast implementation subagent that mirrors Swarm behavior for concrete file-change tasks. Runtime shape: read/write execution setting. Available as a subagent assignment, but not part of the default Utility AI baseline.Utility AI
Utility AI is the shared model baseline for built-in helper agents.
swarmThe primary default follows the provider’s primary default model unless you override the agent.explorerUses the Utility AI baseline unless you give this profile a provider/model override.memoryUses the Utility AI baseline and stays protected because Swarm relies on it for session titles and summaries.parallelUses the Utility AI baseline unless overridden.cloneIs a built-in subagent assignment, but it is not part of the default Utility AI baseline.In the agent UI, “Set Utility AI” fills blank built-in utility agents. Existing per-agent overrides stay custom unless you explicitly clear overrides.
TUI and Desktop
The surfaces are different, but they manage the same saved profiles.
TUI/agents opens the terminal manager. It supports profile search/filtering, new/edit flows, primary activation, enable/disable, delete, restore, reset, and Utility AI updates. Command shortcuts cover common operations without requiring the modal.DesktopDesktop Settings → Agents groups profiles into Primary Agents, Subagents, and Background Agents. Background Agents are available for profiles you do not want in everyday primary or delegated use. The surface exposes New agent, Set Utility AI, Delete all & reset, Make active primary, profile fields, plan-mode enablement, execution setting, and advanced tool-scope fields.Do not treat the UI differences as different runtime systems. Both surfaces read and write the same agent profile state.
Commands
Use these commands for the common agent operations.
/agentsOpen the agents manager surface./agents restoreRestore built-in agent profiles without deleting custom agents./agents resetDelete custom agents and custom tools, then restore the built-in defaults./agents use <primary-agent>Set the active primary agent for normal chat sessions./agents prompt <name> <prompt text>Replace a saved agent prompt from the TUI command line./agents delete <name>Delete an agent profile when it is not protected and deletion would not remove the last primary./commit [instructions]Launch a background commit run from an active chat. Current Swarm uses the built-in memory profile for this flow.Custom agents
You can ask Swarm to make an agent for a job.
The plain-language path is intentional: ask for the role you want, and Swarm can inspect the current agent state, propose a saved profile, and apply it after approval. Custom agent creation uses the same profile fields as the UI: mode, prompt, provider/model overrides, execution setting or plan-mode contract, and optional tool limits.
ExampleMake me an agent for reviewing API diffs. It should be a read-only subagent.ExampleFix the prompt for the memory agent to compact in a certain manner.ExampleMake me an agent with a custom tool that runs our local Go-version check script.Custom tools are part of the agent system too. Today they are fixed-bash wrappers for predefined scripts or one-off shell commands, which makes them easier to manage than broad bash allowlisting. The runtime management tool supports creating those tools and assigning or unassigning them from agents. For now, ask Swarm to create the agent/tool rather than manually editing storage files.
Defaults
Restore and reset do different things.
/agents restoreRewrites the built-in profiles and restores default subagent assignments. Custom agents remain./agents resetDeletes custom agents and custom tools, then restores built-in profiles and default assignments.swarmProtected from deletion because it is the default primary profile.memoryProtected from deletion because Swarm uses it for titles, summaries, and compact messages.Runtime contracts
Runtime contracts decide whether an agent plans first or acts directly.
Plan → AutoPlan mode is enabled for the profile. Tool availability follows plan mode until the agent calls exit_plan_mode for approval. After approval, the same chat continues in auto. This is the built-in swarm default.Read-onlyPlan mode is off and execution_setting is read. The direct baseline enables inspection tools such as read, search, list, and configured non-mutating web/plan helpers; it disables write, edit, bash, and task delegation.Read/writePlan mode is off and execution_setting is readwrite. The direct baseline enables read, search, list, write, and edit when workspace permissions allow it; bash and task still require an explicit tool contract or scope.Tool scopeNot a runtime contract by itself. It overlays the selected contract with allowed tools, denied tools, bash prefixes, presets, and inherited permission policy. The resolved tool list shown to the run is final.
In storage, Plan → Auto is the short name for exit_plan_mode_enabled. If that is off, the profile must choose read or readwrite; otherwise Swarm has no effective runtime contract to run.