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:
- Understand: Read the relevant code and check existing conventions.
- Implement: Make the change following existing patterns.
- Verify: Run tests, type-check, or manually confirm the behavior.
- 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:
| Platform | Default 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 filessearch_content: Search file contentsfind_files: Find files by patternfile_stat: Inspect file and directory metadatalsp_inspect: Inspect code with the language serverwrite_fileandstring_replace_lsp: Create and edit plan files onlyask_user: Ask clarifying questionssubmit_plan: Submit the plan for reviewtask_write,task_update,task_complete, andtask_check: Track plan worklist-workflowsandget-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-workflowsandget-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:
| Mode | Default model |
|---|---|
| Build | openai/gpt-5.6-sol |
| Plan | openai/gpt-5.6-sol |
| Explore | openai/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.
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:
| Subagent | Access | Use case |
|---|---|---|
| Explore | Read-only | "Find all usages of X", "How does module Y work" |
| Plan | Read-only | "Create an implementation plan for X", "Analyze the architecture of Y" |
| Execute | Read + 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.