Mastra Code

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 70+ 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

1. Install Mastra Code globally:

   npm

   npm install -g mastracode

   pnpm

   pnpm add -g mastracode

   Yarn

   yarn global add mastracode

   Bun

   bun add --global mastracode

   Or run it with npx:

   npm

   npx mastracode

   pnpm

   pnpm dlx mastracode

   Yarn

   yarn dlx mastracode

   Bun

   bun x mastracode

2. Navigate to your project directory and start Mastra Code:

   cd your-project
   mastracode

3. Set an API key for your preferred provider (e.g. export ANTHROPIC_API_KEY=sk-ant-...), or run /login to authenticate with an Anthropic or OpenAI subscription. See Configuration for all supported providers.

4. 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
/models	Select a different AI model
/mode	Switch between Build, Plan, and Fast modes
/cost	Show token usage for the current conversation
/login	Authenticate with OAuth providers
/logout	Log out from a provider
/settings	Open the settings panel
/theme	Switch color theme (auto, dark, or light)
/sandbox	Add external directories to the allowed path list
/diff	Show files modified in the current session
/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:

1. TUI: Terminal interface (pi-tui components)
2. Harness: Mode management, thread persistence, event system, state management
3. Mastra Agent: Dynamic model selection, tool execution, memory integration, subagents
4. 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.

Next steps

• Modes
• Tools
• Configuration
• Customization
• API reference