# Mastra Code overview

Mastra Code is a terminal-based AI coding agent built on Mastra's [Harness](https://mastra.ai/reference/harness/harness-class), [Agent](https://mastra.ai/docs/agents/overview), and [Memory](https://mastra.ai/docs/memory/overview) 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**](https://mastra.ai/docs/mastra-code/modes): Switch between Build, Plan, and Fast modes to match your workflow.
- [**Tools**](https://mastra.ai/docs/mastra-code/tools): Built-in tools for file viewing, editing, searching, shell commands, and web search.
- [**Configuration**](https://mastra.ai/docs/mastra-code/configuration): Project-scoped threads, MCP servers, hooks, custom commands, skills, and database settings.
- [**Customization**](https://mastra.ai/docs/mastra-code/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**:

   ```sh
   npm install -g mastracode
   ```

   **pnpm**:

   ```sh
   pnpm add -g mastracode
   ```

   **Yarn**:

   ```sh
   yarn global add mastracode
   ```

   **Bun**:

   ```sh
   bun add --global mastracode
   ```

   Or run it with `npx`:

   **npm**:

   ```sh
   npx mastracode
   ```

   **pnpm**:

   ```sh
   pnpm dlx mastracode
   ```

   **Yarn**:

   ```sh
   yarn dlx mastracode
   ```

   **Bun**:

   ```sh
   bun x mastracode
   ```

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

   ```sh
   cd your-project
   mastracode
   ```

3. Run the `/login` command to authenticate with your AI providers (Anthropic, OpenAI).

4. Type a message and press Enter. The agent responds with streaming text and can read, edit, and run code in your project.

## Slash commands

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

| Command     | Description                                       |
| ----------- | ------------------------------------------------- |
| `/new`      | Start a new conversation thread                   |
| `/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                           |
| `/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](https://mastra.ai/docs/mastra-code/configuration) for details.

## Keyboard shortcuts

| Shortcut | Action                                              |
| -------- | --------------------------------------------------- |
| `Ctrl+C` | Interrupt current operation                         |
| `Ctrl+D` | Exit (when editor is empty)                         |
| `Ctrl+T` | Toggle thinking blocks visibility                   |
| `Ctrl+E` | Expand/collapse all tool outputs                    |
| `Ctrl+F` | Send a follow-up message while the agent is running |

## 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

## Next steps

- [Modes](https://mastra.ai/docs/mastra-code/modes)
- [Tools](https://mastra.ai/docs/mastra-code/tools)
- [Configuration](https://mastra.ai/docs/mastra-code/configuration)
- [Customization](https://mastra.ai/docs/mastra-code/customization)
- [API reference](https://mastra.ai/reference/mastra-code/createMastraCode)