Skip to main content

Modes

Mastra Code operates in one of three modes, each tailored to a different kind of task. Modes control which tools the agent has access to, how it approaches problems, and which default model it uses.

Switch modes with the /mode slash command.

Build mode​

Build mode is the default. The agent has full access to all tools — reading, writing, editing files, and running shell commands.

Use Build mode when you want the agent to make changes to your codebase: implementing features, fixing bugs, refactoring code, or running tests.

Working style​

  • Simple tasks (typo fixes, single-file changes): The agent acts immediately without planning.
  • Non-trivial tasks (3+ files, architectural decisions): The agent creates a task list, works through each step, and verifies changes before moving on.

Implementation loop​

For each change, the agent follows this cycle:

  1. Understand: Read the relevant code and check existing conventions.
  2. Implement: Make the change following existing patterns.
  3. Verify: Run tests, type-check, or manually confirm the behavior.
  4. Clean up: Remove debug statements and ensure no half-done work.

Approved plans​

When a plan is approved in Plan mode, Mastra Code automatically switches to Build mode and injects the plan into the agent's instructions. The agent then implements the plan step by step.

Approved plans are also persisted to disk as markdown files so you can archive and reference them later. Each file is saved to the platform-specific app data directory under a plans/<resourceId>/ subdirectory:

PlatformDefault path
macOS~/Library/Application Support/mastracode/plans/<resourceId>/
Linux~/.local/share/mastracode/plans/<resourceId>/
Windows%APPDATA%\mastracode\plans\<resourceId>\

Files are named <ISO-timestamp>-<slugified-title>.md and contain the plan title, approval timestamp, and full plan body.

To store approved-plan archives in a different directory, set the MASTRA_PLANS_DIR environment variable. It replaces the global archive directory:

export MASTRA_PLANS_DIR=.mastracode/plans

Plan persistence is best-effort — a write failure does not block or affect the approval flow.

Plan mode​

Plan mode is read-only for project files. The agent can explore the codebase but can't modify project files or run side-effect commands. The only files it can write are the markdown plan files it submits with submit_plan.

Use Plan mode when you want to analyze architecture, design an approach, or create a detailed implementation plan before writing code.

Available tools​

  • view: Read files
  • search_content: Search file contents
  • find_files: Find files by pattern
  • file_stat: Inspect file and directory metadata
  • lsp_inspect: Inspect code with the language server
  • write_file and string_replace_lsp: Create and edit plan files only
  • ask_user: Ask clarifying questions
  • submit_plan: Submit the plan for review
  • task_write, task_update, task_complete, and task_check: Track plan work
  • list-workflows and get-workflow: Inspect saved workflows

Plan mode has no execute_command tool, so the agent cannot run shell commands even when they would only read state. Writing is limited to Markdown files directly inside the project's plan directory.

Plan submission​

The agent writes the plan to a Markdown file directly inside the project's plan directory, then calls submit_plan with that file's path. The plan file contains the overview, implementation steps, and verification details. The tool call suspends so you can review the file before the agent continues.

After submission, you can:

  • Approve: Mastra Code switches to Build mode and starts the plan as a goal, so it keeps executing and checking the plan across turns.
  • Request changes (or Esc): Provide feedback for the agent to revise the same plan file and resubmit it.

Explore mode​

Explore mode is read-only codebase exploration. It uses a faster model and answers questions directly instead of planning or implementing changes.

Use Explore mode for questions like "find all usages of X" or "how does module Y work."

Rules​

  • The agent has read-only access. It cannot modify files or run shell commands.
  • It searches broadly, then reads the relevant files to answer the question.
  • It can inspect saved workflows with list-workflows and get-workflow, but cannot create, run, or delete them.
  • It answers directly in the conversation rather than handing work back to another agent.

The built-in mode keeps the id fast for compatibility. /mode displays it as Explore.

Default models​

Each mode has a default model for sessions that start in it. Switching modes keeps the current model:

ModeDefault model
Buildopenai/gpt-5.6-sol
Planopenai/gpt-5.6-sol
Exploreopenai/gpt-5.4-mini

Mode packs can set a different model for each mode.

Use /model to change the current mode model. The active pack becomes Custom, or the current custom pack is updated for that mode. Use /models to switch packs. /packs is an alias for /models.

Use /login to add a provider account or /api-keys to store an API key.

note

Visit createMastraCode() reference for details on configuring custom modes and default models.

Subagents​

In Build mode, the agent can spawn subagents to parallelize work. Subagents run as focused, independent tasks with their own tool access:

SubagentAccessUse case
ExploreRead-only"Find all usages of X", "How does module Y work"
PlanRead-only"Create an implementation plan for X", "Analyze the architecture of Y"
ExecuteRead + write"Implement feature X", "Fix bug Y", "Refactor module Z"

The parent agent spawns subagents only when multiple tasks can run in parallel. For a single task, the agent handles it directly. Subagent outputs are treated as untrusted — the parent agent verifies results before moving on.

Thinking level​

You can control thinking depth through the /settings panel (or /think). Stored levels remain off, low, medium, high, xhigh, and max across providers. For OpenAI models, the UI shows provider-specific labels (for example, Very High (xhigh)), while non-OpenAI models keep generic labels.

YOLO mode​

YOLO mode auto-approves all tool calls without prompting. It's enabled by default and can be toggled through /settings. When disabled, Mastra Code prompts for approval before executing write operations or shell commands, based on the permission system.