Mastra Code is a terminal-based AI coding agent built on Mastra's Harness, 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 Fast modes to match your workflow.
- 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.
- Customization: Extend Mastra Code programmatically with custom modes, tools, subagents, and storage.
When to use Mastra Code
- 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 Fast mode for brief answers and small edits with minimal latency.
- Multi-model workflows: Compare responses across different AI providers by switching models mid-conversation.
Prerequisites
Mastra Code requires Node.js 22.13.0 or later.
Get started
Install Mastra Code globally:
- npm
- pnpm
- Yarn
- Bun
npm install -g mastracodeOr run it with
npx:- npm
- pnpm
- Yarn
- Bun
Navigate 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 to later authenticate with an API key. Next, choose models for each mode (you can later switch models with
/models). When you select a model from the model selector that doesn't have an API key configured, Mastra Code prompts you to enter one.By default, Mastra Code uses
google/gemini-2.5-flashfor its Observational Memory models. In the next step, you can choose a different model or continue using Gemini Flash. You can later switch this setting with the/omcommand.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 queues your next message and sends it automatically after the current run finishes.
Slash commands
Mastra Code provides built-in slash commands for managing sessions and settings:
| Command | Description |
|---|---|
/new | Start a new conversation thread |
/clone | Clone the current thread (with optional rename) |
/threads | List all threads for this project |
/thread | Show current thread info |
/name | Rename the current thread |
/models | Switch model pack |
/mode | Switch or list modes |
/permissions | Configure tool approval permissions |
/settings | Open the settings panel |
/om | Configure Observational Memory |
/skills | List available skills |
/cost | Show token usage and costs |
/diff | Show modified files or git diff |
/sandbox | Manage sandbox allowed paths |
/review | Review a GitHub pull request |
/report-issue | Open or browse mastracode issues |
/login | Authenticate with OAuth provider |
/logout | Log out from an OAuth provider |
/setup | Run the setup wizard |
/theme | Switch color theme (auto/dark/light) |
/browser | Configure browser automation |
/update | Check for and install updates |
/hooks | Show/reload configured hooks |
/mcp | Show/reload MCP connections |
/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, or queue a follow-up while the agent is running |
Ctrl+Y | Toggle YOLO mode |
Architecture
Mastra Code is built on four layers:
- TUI: Terminal interface (
pi-tuicomponents) - Harness: Mode management, thread persistence, event system, state management
- Mastra Agent: Dynamic model selection, tool execution, memory integration, subagents
- LibSQL Storage: Thread persistence, message history, token usage tracking, observational memory
Demo Video
In this demo, you'll see Mastra Code in action and learn how it came to be.