ContextQMD
Back to Mastra

Mastra Code

docs/src/mastra-code/index.mdx

2025-12-184.4 KB
Original Source

import Steps from '@site/src/components/Steps'; import StepItem from '@site/src/components/StepItem'; import YouTube from '@site/src/components/YouTube';

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

<Steps> <StepItem> Install Mastra Code globally: 
```sh npm2yarn
npm install -g mastracode
```

Or run it with `npx`:

```sh npm2yarn
npx mastracode
```
</StepItem> <StepItem> Navigate to your project directory and start Mastra Code: 
```sh
cd your-project
mastracode
```
</StepItem> <StepItem> 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](/configuration#authentication) for all supported providers. </StepItem> <StepItem> 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. </StepItem> </Steps>

Slash commands

Mastra Code provides built-in slash commands for managing sessions and settings:

CommandDescription
/newStart a new conversation thread
/cloneClone the current thread (with optional rename)
/threadsList all threads for this project
/modelsSelect a different AI model
/modeSwitch between Build, Plan, and Fast modes
/costShow token usage for the current conversation
/loginAuthenticate with OAuth providers
/logoutLog out from a provider
/settingsOpen the settings panel
/themeSwitch color theme (auto, dark, or light)
/sandboxAdd external directories to the allowed path list
/diffShow files modified in the current session
/helpShow available commands
/exitExit the TUI

You can also define custom slash commands as markdown files. See Configuration for details.

Keyboard shortcuts

ShortcutAction
Ctrl+CInterrupt current operation or clear input
Ctrl+C ×2Exit (double-tap)
Ctrl+DExit (when editor is empty)
Ctrl+ZSuspend process (fg to resume)
Alt+ZUndo last clear
Ctrl+TToggle thinking blocks visibility
Ctrl+EExpand/collapse all tool outputs
EnterSend a message, or queue a follow-up while the agent is running
Ctrl+YToggle 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.

<YouTube id="Hbgh3Iyd3Mk" />

Next steps