Mastra Code

What is Mastra Code?

Mastra Code is a terminal-based AI coding agent built with Mastra’s Harness, Agent, and Memory primitives. It runs in your terminal, connects to 70+ AI models, and supports interactive coding workflows like reading, searching, editing, and executing code within your project.

The agent’s core purpose is to help you work through coding tasks using an in-terminal TUI (terminal user interface), structured modes, and project-scoped session handling. It’s designed to organize how the agent thinks and acts—whether you want a quick lookup, a planned implementation, or a full build-and-test loop.

Key Features

• Terminal UI (TUI) experience: Provides a polished TUI in your terminal (pi-tui components) for interactive agent use, rather than a separate web app.
• Multi-model support (70+ models): Connects to 70+ AI models and supports switching models mid-conversation for multi-model workflows.
• Mode-based workflow control: Switch between Build, Plan, and Fast modes to match how you want the agent to respond (e.g., implementation vs. quick answers).
• Project-scoped sessions and persistent context: Uses thread persistence and message history so conversations are organized per project.
• Coding tools in the agent: Includes built-in tools for file viewing, editing, searching, shell commands, and web search to support end-to-end coding tasks.
• Configurable agent behavior: Supports project-scoped configuration including MCP servers, hooks, custom commands, skills, and database settings.
• Programmatic customization: Extend Mastra Code with custom modes, tools, subagents, and storage.

How to Use Mastra Code

1. Install globally using one of the provided commands (npm, pnpm, or yarn), e.g. npm install -g mastracode.
2. Navigate to your project directory: cd your-project and start Mastra Code with mastracode.
3. Set an API key for your preferred provider (example shown for Anthropic via export ANTHROPIC_API_KEY=...) or authenticate using /login (Anthropic or OpenAI subscription mentioned).
4. Send a message in the terminal; the agent responds with streaming text and can read, edit, and run code in your project.
5. Use slash commands and keyboard shortcuts to manage sessions, switch models and modes, and control the TUI (e.g., /threads, /models, /mode, /cost, /login, /exit).

Use Cases

• Day-to-day coding assistant: Ask questions about your codebase, request edits, run tests, and manage Git tasks while staying in the same terminal workflow.
• Code exploration and architecture planning: Use Plan mode to analyze architecture and generate an implementation plan before writing code.
• Quick lookups and small changes: Switch to Fast mode for brief answers and minor edits with minimal latency.
• Multi-provider comparison: Compare how different AI models respond to the same coding question by switching models mid-conversation.
• Session and settings management during development: Use slash commands to start new conversation threads, list threads per project, clone threads, view token usage, and adjust settings/theme.

FAQ

What system requirements does Mastra Code have? Mastra Code requires Node.js 22.13.0 or later.

How do I authenticate with an AI provider? You can set an environment variable API key for your provider (an Anthropic example is shown) or run /login to authenticate with an Anthropic or OpenAI subscription.

Can I switch AI models and modes while using the agent? Yes. The agent provides slash commands to select a different AI model and to switch between Build, Plan, and Fast modes.

How does Mastra Code organize conversations? It uses project-scoped threads with persistent conversation history, allowing you to list, clone, and manage threads within a project.

Does Mastra Code support customizing tools or agent behavior? Yes. You can configure features like MCP servers, hooks, custom commands, skills, and database settings, and you can extend the agent with custom modes, tools, subagents, and storage.

Alternatives

• Local IDE-integrated AI coding tools: Alternatives that run inside editors/IDEs can provide contextual code assistance, but typically focus on inline suggestions rather than a terminal-first agent workflow with explicit modes.
• General-purpose terminal LLM chat with custom tooling: A chat agent in the terminal can be extended with scripts for file edits and command execution, but you may need more setup to replicate Mastra Code’s built-in tools, mode handling, and session/thread structure.
• Workflow-based coding assistants (plan/build style): Tools that emphasize planning before implementation can match the “Plan mode” idea; differences usually come from how tool execution (editing/search/shell) and persistent project threads are handled.
• Agent frameworks for coding tasks: General agent frameworks can be used to build a coding agent with memory and tools, but Mastra Code packages these primitives into a ready-to-run terminal TUI.