Skip to main content

Mastra Code

Mastra Code is a terminal-based AI coding agent that never compacts. Built on Mastra's AgentController, 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 Explore modes to match your workflow.
  • Goals: Keep Mastra Code working across turns until a judge model marks the objective complete or waits for your input.
  • 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.
  • Terminal notifications: Show clickable notifications for Mastra Code running in an inactive terminal pane.
  • Customization: Extend Mastra Code programmatically with custom modes, tools, subagents, and storage.
  • Themes: Pick a bundled theme, follow your terminal's light or dark appearance, or write your own.
  • Headless mode: Run Mastra Code non-interactively from your shell or from Node and CI with the runMC API.

In this demo, you'll see Mastra Code in action:

Learn how Mastra Code came to be on YouTube.

When to use Mastra Code​

  • Long-running projects: Mastra Code's persistent threads and Observational Memory make it ideal for ongoing projects where context builds up over time.
  • No compaction headaches: With Observational Memory, you never have to worry about losing important context due to token limits. Mastra Code automatically manages what to remember and what to forget.
  • 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 Explore mode for read-only codebase questions with minimal latency.
  • Multi-model workflows: Compare responses across different AI providers by switching models mid-conversation.

Prerequisites​

Mastra Code requires Node.js 22.19.0 or later. To enable @ filename suggestions, install the dependency described in File autocomplete.

Get started​

  1. Install Mastra Code globally:

    npm install -g mastracode

    Or run it with npx:

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

    cd your-project
    mastracode
  3. On your first startup, Mastra Code starts an onboarding wizard to help you connect and choose your models. You can always rerun this with the /setup command.

    In the first step, log in to Anthropic or OpenAI through OAuth. Alternatively, skip this step and run /connect later to add an account or API key. Next, choose models for each mode. You can later change the model for the current mode with /model or switch packs with /models. When you select a model without a configured provider API key, Mastra Code prompts you to enter one.

    Observational Memory models default to Auto and follow the active main model's provider. Onboarding doesn't ask you to choose them. Use /memory later to pin or reset the Observer and Reflector independently.

    In the last step, choose whether you want to run in "YOLO" mode or not. You're all set up with Mastra Code!

  4. Type a message and press Enter. If the agent is already working, Enter delivers text messages to the active run, runs slash and ! shell commands immediately, and queues messages with images. Press Ctrl+F instead to queue any message until the current run finishes.

Start with a prompt​

Pass --tui-initial-prompt to open Mastra Code with a first message already submitted, as if you had typed it. The session stays open, so you can follow up as usual:

mastracode --tui-initial-prompt "Review the changes on this branch"

Slash commands and skills work too:

mastracode --tui-initial-prompt "/skill/review-pr https://github.com/org/repo/pull/1"

--tui-initial-prompt only starts a new conversation. If Mastra Code resumes an existing conversation for the directory, it shows that conversation and doesn't send the prompt, so relaunching in the same place doesn't repeat the task. Use --tui-prompt to send the prompt either way, including into a resumed conversation:

mastracode --tui-prompt "Pick up where we left off and run the tests"

Launchers that can only pass environment variables through, such as an editor pane or a terminal multiplexer, can set MASTRACODE_TUI_INITIAL_PROMPT instead. It works like --tui-initial-prompt, and Mastra Code removes the variable at startup so shells and nested sessions it starts don't send the prompt again. A flag takes precedence over the variable.

Piped stdin is added after a plain-text prompt in the same first message, and is skipped with the prompt when --tui-initial-prompt resumes a conversation. A prompt that is a slash command or starts with ! can't be combined with piped stdin. To run a task without the interactive UI and exit, use headless mode.

Update Mastra Code​

Run mastracode update to install the latest version with the package manager that installed Mastra Code. It exits with code 0 when the update succeeds or Mastra Code is already up to date. It exits with code 1 when the npm registry can't be reached, or when the update fails or leaves the running install unchanged. In the last two cases, it prints the command to run manually:

mastracode update

Inside the TUI, use /update instead.

Slash commands​

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

After exit, run mastracode resume <thread-id> to continue the same thread directly.

CommandDescription
/newStart a new conversation thread
/cloneClone the current thread (with optional rename)
/threadsList all threads for this project
/resumeAlias for /threads
/threadShow current thread info
/nameRename the current thread
/renameAlias for /name
/modelChange the current mode model; create Custom when a built-in pack is active, or update the active custom pack
/modelsSwitch the model pack for all modes
/packsAlias for /models
/modeSwitch or list modes
/goalStart, inspect, pause, resume, or clear a persistent goal (use /goal judge to configure the judge model and attempt limit)
/thinkSet the thinking level (off/low/medium/high/xhigh/max)
/permissionsConfigure tool approval permissions
/yoloToggle YOLO mode (auto-approve all tools)
/settingsOpen the settings panel
/memory, /omConfigure Observational Memory
/context, /ctxShow a context audit for the current session
/knowledgeInspect scoped knowledge when it is enabled
/schedulesCreate, run, pause, resume, or delete recurring prompts
/subagentsConfigure subagent model defaults
/skillsList available skills
/skill/<name>Activate a specific skill
/pluginsInstall or manage trusted plugins
/workflows, /workflowList, inspect, run, or delete chat-built workflows
/profileControl process memory diagnostics
/pruneDelete data older than the retention policies and exit; add vacuum to reclaim disk or keep-memory to keep chat history
/costShow token usage and costs
/diffShow modified files or git diff
/resourceShow or switch the resource ID (tag for sharing)
/thread:tag-dirTag the current thread with this directory
/sandboxManage sandbox allowed paths
/reviewReview a GitHub pull request
/githubSubscribe, sync, or debug GitHub PR signals
/report-issueOpen or browse mastracode issues
/connectConnect a provider account or API key
/factoryConnect to or switch to a Mastra Factory environment
/localSwitch back to the local runtime
/loginSign in with a provider account
/logoutLog out from an OAuth provider
/api-keysManage API keys for model providers
/custom-providersManage custom providers and models
/observabilityConfigure cloud observability
/gatewayConfigure the Mastra gateway URL and API key for memory models
/feedbackSubmit feedback about Mastra Code
/voiceToggle push-to-talk voice input
/setupRun the setup wizard
/themeSwitch color theme (picker, list, or name)
/browserConfigure browser automation
/updateCheck for and install updates
/hooksShow/reload configured hooks
/mcpShow/reload MCP connections, disable or enable servers
/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. While the agent is running, text messages are delivered to the active run, slash commands and ! shell commands run immediately, and messages with images are queued
Ctrl+FQueue a follow-up message to send after the current run finishes. When no run is active, sends the message immediately
Ctrl+YToggle YOLO mode

Next steps​