Skip to main content
Modes define how an agent behaves during a session. A mode controls which actions the agent can use, what system prompt it receives, where it works on disk, and what mode it should switch to next. Every agent session runs in exactly one mode at a time. You can use the built-in modes as-is, customize them, or create entirely new ones.

​
Built-in Modes

OpenSwarm ships with five built-in modes:
ModeActionsPurpose
AgentAllFull autonomous agent with read and write access to everything. The default.
AskRead, Glob, Grep, AskUserQuestionAnswer questions about the codebase. Read-only — no edits or commands.
PlanRead, Glob, Grep, AskUserQuestionAnalyze a request and produce a step-by-step plan without executing it. Auto-switches to Agent when done.
App BuilderAllCreate and iterate on interactive App artifacts. Operates in a dedicated workspace folder.
Skill BuilderAllCreate and iterate on reusable Skills. Operates in a dedicated workspace folder.
Built-in modes can be edited but not deleted. If you modify a built-in mode and want to undo your changes, use the Reset to Default button in the edit dialog.

​
Mode Properties

Every mode — built-in or custom — has the following configurable properties:

​
Name & Description

The name is what appears in the mode selector in the chat input. The description is shown below the name in the mode card and helps you (and the agent) understand the mode’s purpose.
The description is for your reference only — it is not injected into the agent’s system prompt. Use the System Prompt field for instructions you want the agent to follow.

​
System Prompt

The system prompt is injected into every message the agent processes while in this mode. Use it to define the agent’s role, constraints, output format, or any behavioral rules. 
You are a code reviewer. Analyze the code for bugs, security issues,
and style problems. Do not make any edits — only report findings.
The system prompt editor supports two special syntaxes:
  • @ mentions — Reference files, folders, or other context that should be attached to the prompt. Type @ to browse.
  • / commands — Insert slash commands. Type / to browse available commands.
When a session starts, OpenSwarm composes the final system prompt by combining three layers (in order):
  1. The global default system prompt from Settings
  2. The mode system prompt (this field)
  3. The session-level system prompt (if one was provided when launching the agent)

​
Actions

By default, a mode allows all actions — every built-in tool and every connected MCP integration. You can restrict this to a specific subset by enabling the Restrict actions toggle and selecting which actions are allowed. Actions are organized into two groups in the selector:
The core tools from the Claude Agent SDK:
  • Read — Read file contents
  • Edit — Make targeted edits to files
  • Write — Write entire files
  • Bash — Run shell commands
  • Glob — Search for files by pattern
  • Grep — Search file contents
  • AskUserQuestion — Ask the user a clarifying question
Any MCP server you’ve connected in the Action Library appears here as mcp:<name> (e.g., mcp:google-workspace, mcp:reddit). Selecting an MCP action makes the entire server’s tools available to the agent in this mode.
Action restrictions are enforced at session launch. If a mode only allows Read and Grep, the agent physically cannot call Bash or Write — they are not loaded into the session. This is a hard constraint, not a prompt-based suggestion.

​
Default Next Mode

When set, the agent will automatically switch to the specified mode after completing its task. This enables mode chaining — for example, the built-in Plan mode sets its default next mode to Agent, so after planning, the agent transitions into execution mode. If no default next mode is set, the agent stays in the current mode.

​
Default Folder

The working directory the agent starts in when using this mode. This overrides the global default folder from Settings. The resolution order for an agent’s working directory is:
  1. Session-level target directory (if explicitly set when launching the agent)
  2. Mode default folder (this field)
  3. Global default folder (from Settings)
  4. Home directory (~)
You can type a path directly or use the Browse button to pick a folder visually.
The App Builder and Skill Builder modes use their default folder as a workspace root — each new session creates a subdirectory within it. This keeps each app/skill isolated in its own folder.

​
Icon & Color

Visual customization for the mode card and mode selector. Pick from the available icon set and color palette to make modes easily distinguishable at a glance.

​
Creating a Custom Mode

  1. Navigate to Customization → Modes in the sidebar
  2. Click New Mode in the top right
  3. Fill in the mode properties described above
  4. Click Create Mode
Your custom mode will immediately appear in the mode selector when starting or switching agent modes.

​
Example: Research Mode

A mode that restricts the agent to reading and searching — no file edits or shell commands. Great for when you want answers without side effects:
FieldValue
NameResearch
DescriptionSearches the web, reads files, and answers questions. No edits or commands.
System PromptYou are a research assistant. Find accurate, well-sourced answers to questions. Summarize findings clearly with key takeaways. Do not make any file edits or run commands.
ActionsRead, Glob, Grep, AskUserQuestion
Default Next ModeNone
Default FolderNot set

​
Example: Email Drafter Mode

A mode that gives the agent access to Gmail for composing drafts, scoped to a specific folder for context:
FieldValue
NameEmail Drafter
DescriptionDrafts emails based on notes and context files.
System PromptYou are a professional writing assistant. Read the user's notes and context, then draft clear, concise emails. Always save as a Gmail draft — never send directly. Match the user's tone and keep emails under 200 words unless asked otherwise.
ActionsRead, Glob, Grep, AskUserQuestion, mcp:google-workspace
Default Next ModeNone
Default Folder/Users/me/Documents/email-drafts

​
Editing & Resetting Modes

​
Editing

Click the edit icon on any mode card to open the edit dialog. All fields are editable, including on built-in modes. Changes take effect on new sessions — existing running agents keep the mode configuration they were launched with.

​
Resetting Built-in Modes

If you’ve modified a built-in mode and want to restore it to its original configuration, open the edit dialog and click Reset to Default in the bottom left. This button only appears for built-in modes and is only enabled when the mode has diverged from its defaults.

​
Deleting

Custom modes can be deleted by clicking the delete icon on the mode card. Built-in modes cannot be deleted.

​
How Modes Are Applied

When an agent session launches, OpenSwarm resolves the mode and applies it:
1

Resolve mode by ID

Look up the mode definition from the modes store.
2

Load allowed actions

If the mode restricts actions, only those tools are loaded. Otherwise all available tools are included.
3

Resolve working directory

Determined by priority: session-level target directory → mode default folder → global default folder → ~.
4

Compose system prompt

The final prompt is assembled by concatenating the global default prompt, the mode prompt, and the session-level prompt (in that order).
5

Connect MCP servers

MCP servers whose actions are in the allowed set are started and attached to the session.
6

Start Claude Agent SDK session

The session begins with the resolved tools, prompt, and working directory.
The mode configuration is captured at launch time. Changing a mode’s settings after an agent is already running will not affect that session — only new sessions will pick up the changes.