API Reference
The createMastraCode() factory function bootstraps Mastra Code and returns a configured controller, MCP manager, and other components. Use it to embed Mastra Code in custom applications or extend its functionality.
createMastraCode()
import { createMastraCode } from 'mastracode'
const {
controller,
mcpManager,
hookManager,
authStorage,
resolveModel,
storageWarning,
builtinPacks,
builtinOmPacks,
effectiveDefaults,
} = await createMastraCode(options)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
options | MastraCodeConfig | No | Configuration options |
Returns
| Property | Type | Description |
|---|---|---|
controller | AgentController | The main orchestrator for modes, threads, messages, and tools |
session | Session<MastraCodeState> | The wired local session. Pass this (with controller) to runMC |
sessionId | string | Identity of the eager local session |
ownerId | string | Owner ID for the local session |
storage | StorageConfig | The resolved storage backend |
memory | Memory | MemoryFactory | The resolved memory instance or factory |
observability | object | Observability handles |
mcpManager | MCPManager | Manager for MCP server connections |
hookManager | HookManager | Manager for lifecycle hooks |
signalsPubSub | PubSub | PubSub used for signal routing |
githubSignals | object | GitHub PR signal handles |
authStorage | AuthStorage | Storage for OAuth credentials |
resolveModel | (modelId: string, options?: { thinkingLevel?: ThinkingLevel; remapForCodexOAuth?: boolean; requestContext?: RequestContext }) => ResolvedModel | Model resolution function |
storageWarning | string | null | Warning message if storage fallback occurred |
observabilityWarning | string | null | Warning message if observability setup fell back |
builtinPacks | ModePack[] | Built-in mode packs |
builtinOmPacks | OmPack[] | Built-in Observational Memory packs |
effectiveDefaults | object | Effective default settings after merging |
setActiveSession | (session: Session<MastraCodeState>) => void | Publishes a session back into config closures |
MastraCodeConfig
| Option | Type | Default | Description |
|---|---|---|---|
cwd | string | process.cwd() | Working directory for project detection |
homeDir | string | os.homedir() | Home directory for global config discovery |
modes | AgentControllerMode[] | false | build, plan, fast (displayed as Explore) | Override modes (model IDs, colors, which modes exist). false runs every session as a single Build agent |
subagents | AgentControllerSubagent[] | [] | Subagent definitions to register. None are registered by default. Pass [...builtinSubagents] to enable Explore, Plan and Execute |
extraTools | Record<string, Tool> | ((ctx) => Record<string, Tool> | Promise<Record<string, Tool>>) | — | Extra tools merged into the dynamic tool set |
postToolObserver | (context: ToolAfterHookContext) => void | Promise<void> | — | Observes completed tool calls without replacing tools. Errors are logged without failing successful tool calls |
inputProcessors | InputProcessor[] | ((ctx) => InputProcessor[] | Promise<InputProcessor[]>) | — | Processors prepended before Mastra Code's built-in input processors |
outputProcessors | OutputProcessor[] | ((ctx) => OutputProcessor[] | Promise<OutputProcessor[]>) | — | Processors appended after Mastra Code's built-in output processors |
disabledTools | string[] | [] | Tools removed from the dynamic tool set before exposure to the model |
disableBuiltinTools | BuiltinToolId[] | [] | Agent controller built-in tools (for example, submit_plan) removed from every session. Tool guidance skips disabled tools, and plan mode writes the plan file instead of calling submit_plan when it's disabled |
storage | StorageConfig | MastraCompositeStore | Local LibSQL | Custom storage config instead of auto-detected default, or a pre-built store |
storageBackend | 'libsql' | 'pg' | Inferred for LibSQL and Postgres | Backend for an injected store. Inferred for LibSQLStore and PostgresStore; required for any other MastraCompositeStore |
vector | MastraVector | Default recall store | Pre-built vector store for recall search |
knowledge | { key: string; instance: Knowledge } | — | Host-owned Knowledge instance registered on the mounted Mastra runtime |
omScope | 'thread' | 'resource' | Auto-detected | Observational Memory scope. 'resource' is deprecated |
settingsPath | string | Global settings | Path to a custom settings.json file |
initialState | Partial<MastraCodeState> | Default state | Initial state overrides (yolo, thinkingLevel, etc.) |
resolveDefaultThinkingLevel | (ctx) => ThinkingLevelSetting | Promise<ThinkingLevelSetting> | Settings defaults | Host-owned thinking default applied when a request has no level |
createInitialThread | boolean | true | Create a thread during local boot when no existing thread matches |
hostInstructions | string | ((ctx) => string | undefined | Promise<string | undefined>) | — | Trusted host instructions resolved outside mutable session state |
coAuthor | { name?: string; email?: string } | Core defaults | Commit co-author identity used in coding-agent commit guidance |
idGenerator | () => string | Default | Override id generation for threads/messages (useful for deterministic tests) |
intervalHandlers | IntervalHandler[] | gateway-sync | Override interval (background task) handlers |
workspace | Workspace | Local FS + sandbox | Override the workspace |
configDir | string | .mastracode | Override the config directory name |
mcpServers | Record<string, McpServerConfig> | {} | Programmatic MCP server configs, merged with file-based configs |
disableMcp | boolean | false | Disable MCP server discovery |
disableHooks | boolean | false | Disable hooks |
disableEnvFile | boolean | false | Skip loading cwd/.env into the process environment |
disablePlugins | boolean | false | Disable plugin discovery and loading |
disableGithubSignals | boolean | false | Disable the polling GitHub signal provider even when enabled in global settings |
disableSettingsOmSeed | boolean | false | Skip seeding observational memory settings from settings.json |
pluginManager | PluginManager | Built-in manager | Override the plugin manager |
memory | Memory | MemoryFactory | false | Built-in gateway | Override the memory instance or factory |
browser | BrowserProvider | — | Browser provider; when set the agent gains browser tools |
pubsub | PubSub | — | PubSub for signal routing |
unixSocketPubSub | boolean | false | Use the built-in Unix socket PubSub for local cross-process signal routing |
crossProcessPubSub | boolean | false | Mark the configured PubSub as cross-process-safe (skips file thread locks) |
agentConnections | AgentConnectionsSignalProviderOptions | — | Agent connection state and discovery options |
crossAgentSignals | boolean | Global setting (off) | Enable experimental cross-agent communication |
scheduleTools | boolean | Global setting (off) | Enable the experimental schedule tools |
prepareWakeRequestContext | (args) => void | Promise<void> | — | Prepare request context before a wake runs on an idle thread |
resumeWakeSession | (args) => Promise<void> | — | Bring the session that owns a resource online for a deferred notification |
AgentControllerMode
Each mode defines a display configuration and optional tool and instruction overrides. All modes share the backing agent.
| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique identifier (e.g., "build", "plan") |
name | string | No | Display name shown in the TUI |
defaultModelId | string | No | Model for sessions that start in this mode and fallback for subagents. Mode switches do not apply it |
description | string | No | Description shown in mode pickers and Studio |
instructions | string | No | Instructions layered above the backing agent's instructions |
availableTools | string[] | No | Tool allowlist for this mode. undefined allows all tools; [] hides all tools |
transitionsTo | string | No | Mode to switch to when a submitted plan is approved |
metadata | Record<string, unknown> | No | User-defined metadata. metadata.color sets the TUI indicator color and metadata.default: true marks the startup mode |
agent | Agent | No | Deprecated. Use the shared backing agent |
AgentControllerSubagent
Subagent definitions for spawning focused child agents.
| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique identifier (e.g., "explore") |
name | string | Yes | Display name in tool output |
description | string | Yes | What this subagent does |
instructions | DynamicArgument<AgentInstructions> | Yes | System prompt for the subagent. Accepts a string, array of strings, system message object, array of system messages, or a function that returns any of these (or a promise of one) |
tools | ToolsInput | No | Tools available to this subagent |
allowedControllerTools | string[] | No | Tool IDs from controller tools this subagent can use |
defaultModelId | string | No | Default model for this subagent type |
maxSteps | number | No | Optional maximum number of steps for the spawned subagent; defaults to 50 unless stopWhen is set |
stopWhen | LoopOptions['stopWhen'] | No | Optional stop condition for the spawned subagent loop |
StorageConfig
Database connection configuration.
| Property | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Database URL (LibSQL or PostgreSQL) |
authToken | string | No | Auth token for remote LibSQL |
MastraCodeState
AgentController state fields available through initialState. OMModel accepts "auto" or a concrete model ID.
| Field | Type | Default | Description |
|---|---|---|---|
yolo | boolean | true | Auto-approve all tool calls. A saved preference overrides this default |
thinkingLevel | "off" | "low" | "medium" | "high" | "xhigh" | "max" | "off" | Extended thinking depth |
smartEditing | boolean | true | Use AST-based analysis for code edits |
notifications | "bell" | "system" | "both" | "off" | "off" | Alert style when TUI needs attention |
permissionRules | PermissionRules | Default policies | Per-category and per-tool approval policies |
observerModelId | string | — | Legacy concrete model for the observational memory observer |
reflectorModelId | string | — | Legacy concrete model for the observational memory reflector |
observerModelSelection | OMModel | "auto" | Automatic or explicit observer model selection |
reflectorModelSelection | OMModel | "auto" | Automatic or explicit reflector model selection |
observationThreshold | number | 30000 | Token count triggering observation pass |
reflectionThreshold | number | 40000 | Token count triggering reflection pass |
PermissionRules
Tool permission configuration.
interface PermissionRules {
// Keyed by category (e.g. "read", "edit", "execute", "mcp")
categories: Record<string, 'allow' | 'ask' | 'deny'>
// Keyed by tool id, overriding the category policy
tools: Record<string, 'allow' | 'ask' | 'deny'>
}
IntervalHandler
Background task definition.
| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique identifier for this handler |
intervalMs | number | Yes | Interval between executions in milliseconds |
handler | () => void | Promise<void> | Yes | Sync or async function to execute |
AgentController
The AgentController instance returned by createMastraCode() is the main orchestrator. See the AgentController Class reference for the complete API.
MastraTUI
The MastraTUI class provides the terminal interface. Import it separately to build custom TUI applications:
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 Agent',
version: '1.0.0',
})
tui.run()
MastraTUIOptions
| Option | Type | Required | Description |
|---|---|---|---|
controller | AgentController | Yes | The controller instance |
session | Session | Yes | The session created from the controller |
hookManager | HookManager | No | Hook manager from createMastraCode() |
authStorage | AuthStorage | No | Auth storage from createMastraCode() |
mcpManager | MCPManager | No | MCP manager from createMastraCode() |
appName | string | No | Application name shown in header |
version | string | No | Version shown in header |
Examples
Basic usage
createMastraCode boots the controller and returns a ready-to-use session. Subscribe to events and send messages on the session:
import { createMastraCode } from 'mastracode'
const { session } = await createMastraCode({
cwd: '/path/to/project',
})
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' })
For one-shot/headless runs, prefer runMC, which wraps this subscribe/send/aggregate loop and resolves to a typed result.
Custom mode
import { createMastraCode } from 'mastracode'
import { Agent } from '@mastra/core/agent'
const reviewAgent = new Agent({
id: 'review-agent',
name: 'Review Agent',
instructions: 'You are a code review specialist.',
model: 'anthropic/claude-sonnet-4-6',
})
const { controller } = await createMastraCode({
modes: [
{
id: 'review',
name: 'Review',
default: true,
defaultModelId: 'anthropic/claude-sonnet-4-6',
color: '#f59e0b',
agent: reviewAgent,
},
],
})
Custom tools
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 }) => {
// Deploy logic here
return { content: `Deployed to ${environment}` }
},
})
const { controller } = await createMastraCode({
extraTools: { deploy: deployTool },
})
Remote storage
import { createMastraCode } from 'mastracode'
const { controller } = await createMastraCode({
storage: {
url: 'libsql://my-db.turso.io',
authToken: process.env.TURSO_AUTH_TOKEN,
},
})
Disable YOLO mode
import { createMastraCode } from 'mastracode'
const { controller } = await createMastraCode({
initialState: {
yolo: false,
permissionRules: {
categories: {
read: 'allow',
edit: 'ask',
execute: 'ask',
mcp: 'deny',
},
tools: {},
},
},
})