createMastraCode()

createMastraCode() is the main factory function that bootstraps the Mastra Code coding agent. It wires together project detection, storage, authentication, MCP servers, hooks, modes, subagents, and the Harness that drives the TUI or any other frontend.

Usage example

src/main.ts

import { createMastraCode } from 'mastracode'

const { harness, mcpManager, hookManager, authStorage } = createMastraCode()

Pass a config object to customize behavior:

src/custom.ts

import { createMastraCode } from 'mastracode'

const { harness } = createMastraCode({
  cwd: '/path/to/project',
  disableMcp: true,
  initialState: { yolo: false },
})

await harness.init()
await harness.selectOrCreateThread()
await harness.sendMessage({ content: 'Explain the auth flow' })

Parameters

createMastraCode() accepts an optional MastraCodeConfig object:

cwd?:

string

= process.cwd()

Working directory for project detection. Mastra Code uses this path to find the Git root, determine the project name, and scope threads.

modes?:

HarnessMode[]

Override the default agent modes. Each mode defines an agent, a default model, and a display color. When omitted, Mastra Code ships with Build, Plan, and Fast modes.

subagents?:

HarnessSubagent[]

Override the default subagent definitions. When omitted, Mastra Code includes Explore (read-only codebase exploration), Plan (read-only analysis and planning), and Execute (task execution with write access).

extraTools?:

Record<string, any>

Additional tools merged into the dynamic tool set available to the agent.

storage?:

{ url: string; authToken?: string }

Custom LibSQL storage configuration. When omitted, Mastra Code auto-detects storage from environment variables, project config, global config, or falls back to a local SQLite database.

initialState?:

Record<string, unknown>

Initial harness state overrides. Merged with defaults like `yolo`, `thinkingLevel`, and project info.

heartbeatHandlers?:

HeartbeatHandler[]

Override the default periodic background tasks. The default handler syncs model gateways every 5 minutes.

disableMcp?:

boolean

= false

Disable MCP server discovery and connection.

disableHooks?:

boolean

= false

Disable the hooks system (lifecycle shell commands).

Return value

createMastraCode() returns an object with four properties:

harness:

Harness

The Harness instance that orchestrates modes, threads, state, memory, and agent interactions. This is the primary interface for sending messages, switching models, and managing conversations.

mcpManager:

McpManager | undefined

The MCP manager for connecting to external MCP servers. `undefined` when `disableMcp` is `true`.

hookManager:

HookManager | undefined

The hook manager for executing lifecycle shell commands. `undefined` when `disableHooks` is `true`.

authStorage:

AuthStorage

The authentication storage instance. Manages OAuth credentials for AI providers (Anthropic Claude Max, OpenAI Codex).

Default modes

When no modes are specified, Mastra Code creates three modes:

Mode	Default model	Description
Build (default)	anthropic/claude-opus-4-6	Full tool access. Read, write, edit files, and execute commands.
Plan	openai/gpt-5.2-codex	Read-only mode. Explore the codebase and produce implementation plans.
Fast	cerebras/zai-glm-4.7	Quick answers and small edits with minimal overhead.

Default subagents

When no subagents are specified, Mastra Code creates three subagent types:

Subagent	Tools	Description
Explore	view, search_content, find_files	Read-only codebase exploration for answering questions about code structure.
Plan	view, search_content, find_files	Read-only analysis and planning with structured plan output.
Execute	All read tools + string_replace_lsp, write_file, execute_command, task_write, task_check	Focused task execution with full write capabilities.

Project detection

Mastra Code automatically detects project identity from the working directory:

1. Git remote URL — if available, normalizes SSH and HTTPS URLs to create a stable identifier shared across clones and worktrees.
2. Absolute path — falls back to the filesystem path when Git isn't available.

The resulting resourceId scopes threads to the project, so conversations are shared across clones, worktrees, and SSH/HTTPS URLs of the same repository.

Storage resolution

Storage configuration is resolved in priority order:

1. storage parameter passed to createMastraCode()
2. MASTRA_DB_URL and MASTRA_DB_AUTH_TOKEN environment variables
3. Project config at .mastracode/database.json
4. Global config at ~/.mastracode/database.json
5. Local SQLite database at the platform-specific app data directory

note

The returned harness object is a full Harness instance with methods for sending messages, switching modes and models, managing threads, and subscribing to events.

Related

• Mastra Code overview
• Harness Class reference
• Mastra Code configuration