Skip to main content

Customization

Mastra Code is designed as a composable library. The createMastraCode() factory function accepts configuration overrides, and the returned AgentController can drive any frontend, not just the built-in TUI.

Programmatic usage​

Import createMastraCode to bootstrap Mastra Code in your own application:

TypeScriptsrc/custom-agent.ts
import { createMastraCode } from 'mastracode'

const { controller, session, mcpManager, authStorage } = await createMastraCode({
  cwd: '/path/to/project',
  initialState: {
    yolo: false,
  },
})

session.subscribe(event => {
  if (event.type === 'message_update' && event.event.type === 'text-delta') {
    process.stdout.write(event.event.delta)
  }
})

await session.sendMessage({ content: 'Explain the auth module' })

createMastraCode boots the controller and returns a ready-to-use session. Subscribe to events and send messages on the session; use the controller to switch modes, configure tools, and manage shared resources.

Custom modes​

Override the default Build/Plan/Explore modes by passing a modes array:

TypeScriptsrc/custom-modes.ts
import { createMastraCode } from 'mastracode'

const { controller } = await createMastraCode({
  modes: [
    {
      id: 'review',
      name: 'Review',
      defaultModelId: 'anthropic/claude-sonnet-4-6',
      metadata: {
        default: true,
        color: '#f59e0b',
      },
    },
    {
      id: 'build',
      name: 'Build',
      defaultModelId: 'anthropic/claude-opus-4-6',
      metadata: {
        color: '#7c3aed',
      },
    },
  ],
})

Each mode requires an id. The name and defaultModelId fields control the mode's label and starting model. Put TUI display options such as color and the default-mode marker in metadata. All modes share the backing agent.

Passing modes: false runs every session as a single Build agent with no mode switching.

Extra tools​

Add custom tools to the agent's tool set without replacing the built-in tools:

TypeScriptsrc/custom-tools.ts
import { createMastraCode } from 'mastracode'
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

const deployTool = createTool({
  id: 'deploy',
  description: 'Deploy the current branch to staging',
  inputSchema: z.object({
    environment: z.enum(['staging', 'production']),
  }),
  execute: async ({ environment }) => {
    return { content: `Deployed to ${environment}` }
  },
})

const { controller } = await createMastraCode({
  extraTools: { deploy: deployTool },
})

Extra tools are merged with the dynamic tool set and are available to the agent in all modes.

Custom subagents​

Mastra Code registers no subagents by default. Pass the subagents you want with subagents. Spread builtinSubagents to keep the built-in Explore, Plan and Execute subagents alongside your own. Each subagent receives its own set of tools, scoping what it can do:

TypeScriptsrc/custom-subagents.ts
import { builtinSubagents, createMastraCode } from 'mastracode'

const { controller } = await createMastraCode({
  subagents: [
    ...builtinSubagents,
    {
      id: 'test-writer',
      name: 'Test Writer',
      description: 'Write tests for the specified module',
      instructions:
        'You are a test-writing specialist. Generate comprehensive tests for the given module.',
    },
  ],
})

Custom storage​

Connect to a remote database instead of the default local SQLite:

TypeScriptsrc/custom-storage.ts
import { createMastraCode } from 'mastracode'

const { controller } = await createMastraCode({
  storage: {
    url: 'libsql://my-db.turso.io',
    authToken: 'my-auth-token',
  },
})

This is equivalent to setting .mastracode/database.json but allows configuration at the code level.

Custom interval handlers​

Replace or extend the default background tasks:

TypeScriptsrc/custom-intervals.ts
import { createMastraCode } from 'mastracode'

const { controller } = await createMastraCode({
  intervalHandlers: [
    {
      id: 'sync-config',
      intervalMs: 60_000,
      handler: async () => {
        await syncConfigFromRemote()
      },
    },
  ],
})

Interval handlers run on a fixed interval. They start when controller.init() is called and stop when controller.destroy() is called.

Building a custom TUI​

Mastra Code exports the MastraTUI class from mastracode/tui for building custom terminal interfaces. The TUI is driven by the AgentController event system:

TypeScriptsrc/custom-tui.ts
import { createMastraCode } from 'mastracode'
import { MastraTUI } from 'mastracode/tui'

const { controller, session, mcpManager, hookManager, authStorage } = await createMastraCode()

const tui = new MastraTUI({
  controller,
  session,
  hookManager,
  authStorage,
  mcpManager,
  appName: 'My Coding Agent',
  version: '1.0.0',
})

tui.run()

The TUI subscribes to controller events and renders messages, tool calls, approvals, and status information in real time.

Initial state overrides​

Control default behavior through initialState:

TypeScriptsrc/custom-state.ts
import { createMastraCode } from 'mastracode'

const { controller } = await createMastraCode({
  initialState: {
    yolo: false,
    thinkingLevel: 'high',
    smartEditing: true,
    notifications: 'system',
    permissionRules: {
      categories: {
        read: 'allow',
        edit: 'ask',
        execute: 'ask',
        mcp: 'deny',
      },
      tools: {},
    },
  },
})

Available state fields​

OMModel accepts "auto" or a concrete model ID.

FieldTypeDefaultDescription
yolobooleantrueAuto-approve all tool calls
thinkingLevelstring—Session override for model reasoning effort. When unset, Mastra Code uses a host-provided default (such as a Factory default) if one exists, then the per-mode setting, then the global preference
smartEditingbooleantrueUse AST-based analysis for code edits
notifications"bell" | "system" | "both" | "off""off"Alert when the TUI needs attention
permissionRulesobjectDefault policiesPer-category and per-tool approval policies
observerModelIdstring—Legacy concrete model for the observational memory observer
reflectorModelIdstring—Legacy concrete model for the observational memory reflector
observerModelSelectionOMModel"auto"Automatic or explicit observer model selection
reflectorModelSelectionOMModel"auto"Automatic or explicit reflector model selection
observationThresholdnumber30000Token count triggering observation pass
reflectionThresholdnumber40000Token count triggering reflection pass