Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Custom Modes

Custom modes extend built-in default and plan behavior with your own instructions and tool policies.

Primary sources:

  • Mode registry: crates/core/src/config/modes/registry.rs
  • Mode discovery + inheritance: crates/core/src/config/modes/resolver.rs
  • Tool filtering at runtime: crates/core/src/tools_config.rs

File locations and precedence

For mode name <name>, Swarmie resolves in this order:

  1. {cwd}/.swarmie/modes/<name>.toml
  2. {cwd}/.swarmie/modes/<name>/MODE.md
  3. ~/.swarmie/modes/<name>.toml
  4. ~/.swarmie/modes/<name>/MODE.md

Custom modes cannot override built-in names (default, plan).

TOML mode format

name = "review"
description = "Read-heavy review mode"
extends = "plan"
read_only = true
max_turns = 30
allowed_tools = ["read", "grep", "glob"]
developer_instructions = "Prioritize correctness and risk analysis."

Supported fields map to ModeDefinition:

  • description, developer_instructions, extends
  • read_only, max_turns
  • excluded_tools, allowed_tools

MODE.md format

MODE.md supports optional TOML frontmatter delimited by +++. Markdown body is appended to developer_instructions.

Inheritance and tool filtering rules

Inheritance merge behavior:

  • developer_instructions: parent then child (concatenated)
  • max_turns, description, tool lists: child overrides when set
  • read_only: inherited if either parent or child enables it

Tool visibility precedence in build_tools_config():

  1. excluded_tools denylist (highest)
  2. allowed_tools allowlist (only listed tools visible)
  3. Read-only default exclusions (bash, write, edit, patch, notebook_edit, undo)
  4. Agent-level allow/deny lists then apply on top