Mastra Code
Mastra Code is a terminal-based AI coding agent that never compacts. Built on Mastra's AgentController, Agent, and Memory primitives. It runs in your terminal, connects to thousands of AI models, and provides tools for reading, searching, editing, and executing code.
Mastra Code organizes its capabilities around these areas:
- Modes: Switch between Build, Plan, and Explore modes to match your workflow.
- Goals: Keep Mastra Code working across turns until a judge model marks the objective complete or waits for your input.
- Tools: Built-in tools for file viewing, editing, searching, shell commands, and web search.
- Configuration: Project-scoped threads, MCP servers, hooks, custom commands, skills, and database settings.
- Terminal notifications: Show clickable notifications for Mastra Code running in an inactive terminal pane.
- Customization: Extend Mastra Code programmatically with custom modes, tools, subagents, and storage.
- Themes: Pick a bundled theme, follow your terminal's light or dark appearance, or write your own.
- Headless mode: Run Mastra Code non-interactively from your shell or from Node and CI with the
runMCAPI.
In this demo, you'll see Mastra Code in action:
Learn how Mastra Code came to be on YouTube.
When to use Mastra Code
- Long-running projects: Mastra Code's persistent threads and Observational Memory make it ideal for ongoing projects where context builds up over time.
- No compaction headaches: With Observational Memory, you never have to worry about losing important context due to token limits. Mastra Code automatically manages what to remember and what to forget.
- Day-to-day coding: Ask questions about your codebase, make edits, run tests, and manage Git.
- Code exploration: Use Plan mode to analyze architecture and create implementation plans before writing code.
- Quick lookups: Switch to Explore mode for read-only codebase questions with minimal latency.
- Multi-model workflows: Compare responses across different AI providers by switching models mid-conversation.
Prerequisites
Mastra Code requires Node.js 22.19.0 or later. To enable @ filename suggestions, install the dependency described in File autocomplete.
Get started
Install Mastra Code globally:
- npm
- pnpm
- Yarn
- Bun
npm install -g mastracodepnpm add -g mastracodeyarn global add mastracodebun add --global mastracodeOr run it with
npx:- npm
- pnpm
- Yarn
- Bun
npx mastracodepnpm dlx mastracodeyarn dlx mastracodebun x mastracodeNavigate to your project directory and start Mastra Code:
cd your-project mastracodeOn your first startup, Mastra Code starts an onboarding wizard to help you connect and choose your models. You can always rerun this with the
/setupcommand.In the first step, log in to Anthropic or OpenAI through OAuth. Alternatively, skip this step and run
/connectlater to add an account or API key. Next, choose models for each mode. You can later change the model for the current mode with/modelor switch packs with/models. When you select a model without a configured provider API key, Mastra Code prompts you to enter one.Observational Memory models default to Auto and follow the active main model's provider. Onboarding doesn't ask you to choose them. Use
/memorylater to pin or reset the Observer and Reflector independently.In the last step, choose whether you want to run in "YOLO" mode or not. You're all set up with Mastra Code!
Type a message and press Enter. If the agent is already working, Enter delivers text messages to the active run, runs slash and
!shell commands immediately, and queues messages with images. Press Ctrl+F instead to queue any message until the current run finishes.
Start with a prompt
Pass --tui-initial-prompt to open Mastra Code with a first message already submitted, as if you had typed it. The session stays open, so you can follow up as usual:
mastracode --tui-initial-prompt "Review the changes on this branch"
Slash commands and skills work too:
mastracode --tui-initial-prompt "/skill/review-pr https://github.com/org/repo/pull/1"
--tui-initial-prompt only starts a new conversation. If Mastra Code resumes an existing conversation for the directory, it shows that conversation and doesn't send the prompt, so relaunching in the same place doesn't repeat the task. Use --tui-prompt to send the prompt either way, including into a resumed conversation:
mastracode --tui-prompt "Pick up where we left off and run the tests"
Launchers that can only pass environment variables through, such as an editor pane or a terminal multiplexer, can set MASTRACODE_TUI_INITIAL_PROMPT instead. It works like --tui-initial-prompt, and Mastra Code removes the variable at startup so shells and nested sessions it starts don't send the prompt again. A flag takes precedence over the variable.
Piped stdin is added after a plain-text prompt in the same first message, and is skipped with the prompt when --tui-initial-prompt resumes a conversation. A prompt that is a slash command or starts with ! can't be combined with piped stdin. To run a task without the interactive UI and exit, use headless mode.
Update Mastra Code
Run mastracode update to install the latest version with the package manager that installed Mastra Code. It exits with code 0 when the update succeeds or Mastra Code is already up to date. It exits with code 1 when the npm registry can't be reached, or when the update fails or leaves the running install unchanged. In the last two cases, it prints the command to run manually:
mastracode update
Inside the TUI, use /update instead.
Slash commands
Mastra Code provides built-in slash commands for managing sessions and settings:
After exit, run mastracode resume <thread-id> to continue the same thread directly.
| Command | Description |
|---|---|
/new | Start a new conversation thread |
/clone | Clone the current thread (with optional rename) |
/threads | List all threads for this project |
/resume | Alias for /threads |
/thread | Show current thread info |
/name | Rename the current thread |
/rename | Alias for /name |
/model | Change the current mode model; create Custom when a built-in pack is active, or update the active custom pack |
/models | Switch the model pack for all modes |
/packs | Alias for /models |
/mode | Switch or list modes |
/goal | Start, inspect, pause, resume, or clear a persistent goal (use /goal judge to configure the judge model and attempt limit) |
/think | Set the thinking level (off/low/medium/high/xhigh/max) |
/permissions | Configure tool approval permissions |
/yolo | Toggle YOLO mode (auto-approve all tools) |
/settings | Open the settings panel |
/memory, /om | Configure Observational Memory |
/context, /ctx | Show a context audit for the current session |
/knowledge | Inspect scoped knowledge when it is enabled |
/schedules | Create, run, pause, resume, or delete recurring prompts |
/subagents | Configure subagent model defaults |
/skills | List available skills |
/skill/<name> | Activate a specific skill |
/plugins | Install or manage trusted plugins |
/workflows, /workflow | List, inspect, run, or delete chat-built workflows |
/profile | Control process memory diagnostics |
/prune | Delete data older than the retention policies and exit; add vacuum to reclaim disk or keep-memory to keep chat history |
/cost | Show token usage and costs |
/diff | Show modified files or git diff |
/resource | Show or switch the resource ID (tag for sharing) |
/thread:tag-dir | Tag the current thread with this directory |
/sandbox | Manage sandbox allowed paths |
/review | Review a GitHub pull request |
/github | Subscribe, sync, or debug GitHub PR signals |
/report-issue | Open or browse mastracode issues |
/connect | Connect a provider account or API key |
/factory | Connect to or switch to a Mastra Factory environment |
/local | Switch back to the local runtime |
/login | Sign in with a provider account |
/logout | Log out from an OAuth provider |
/api-keys | Manage API keys for model providers |
/custom-providers | Manage custom providers and models |
/observability | Configure cloud observability |
/gateway | Configure the Mastra gateway URL and API key for memory models |
/feedback | Submit feedback about Mastra Code |
/voice | Toggle push-to-talk voice input |
/setup | Run the setup wizard |
/theme | Switch color theme (picker, list, or name) |
/browser | Configure browser automation |
/update | Check for and install updates |
/hooks | Show/reload configured hooks |
/mcp | Show/reload MCP connections, disable or enable servers |
/help | Show available commands |
/exit | Exit the TUI |
You can also define custom slash commands as markdown files. See Configuration for details.
Keyboard shortcuts
| Shortcut | Action |
|---|---|
Ctrl+C | Interrupt current operation or clear input |
Ctrl+C ×2 | Exit (double-tap) |
Ctrl+D | Exit (when editor is empty) |
Ctrl+Z | Suspend process (fg to resume) |
Alt+Z | Undo last clear |
Ctrl+T | Toggle thinking blocks visibility |
Ctrl+E | Expand/collapse all tool outputs |
Enter | Send a message. While the agent is running, text messages are delivered to the active run, slash commands and ! shell commands run immediately, and messages with images are queued |
Ctrl+F | Queue a follow-up message to send after the current run finishes. When no run is active, sends the message immediately |
Ctrl+Y | Toggle YOLO mode |