Modes

Modes are behavioral presets that inject developer instructions and can adjust permissions/tool visibility.

Source modules:

• model and validation: crates/core/src/config/modes/mod.rs
• registry and built-ins: crates/core/src/config/modes/registry.rs
• custom mode file loading: crates/core/src/config/modes/resolver.rs
• runtime switch handler: crates/core/src/handlers/mode.rs

Built-in Modes

ModeRegistry::new() includes two built-ins:

• default: full access, autonomous execution (read_only = false)
• plan: read-only exploration/planning (read_only = true)

Runtime Switching

Mode switch flow (Op::ModeSwitch):

1. Core resolves mode from registry.
2. Core builds a developer message using:
   • <mode_switch>{mode}</mode_switch>
   • mode developer_instructions
3. Core appends that developer message to conversation history.
4. Core emits Event::ModeSwitched.

In the TUI, Shift+Tab cycles visible modes (crates/tui/src/app/update/keys.rs).

Custom Modes

Custom modes are loaded from .swarmie/modes (project + home), first-match precedence:

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

File formats

• TOML file: <name>.toml
• Markdown mode file: MODE.md with TOML frontmatter delimited by +++

MODE.md body is appended to developer_instructions.

Fields

ModeDefinition supports:

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

extends supports inheritance; child mode overrides parent fields, and developer instructions are concatenated.

Name Rules

Mode names must match: [a-z][a-z0-9_-]*.