# 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](https://mastra.ai/reference/harness/harness-class) that drives the TUI or any other frontend.

## Usage example

```typescript
import { createMastraCode } from 'mastracode'

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

Pass a config object to customize behavior:

```typescript
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`): Working directory for project detection. Mastra Code uses this path to find the Git root, determine the project name, and scope threads. (Default: `process.cwd()`)

**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`): Disable MCP server discovery and connection. (Default: `false`)

**disableHooks?:** (`boolean`): Disable the hooks system (lifecycle shell commands). (Default: `false`)

## 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](https://mastra.ai/reference/harness/harness-class) instance with methods for sending messages, switching modes and models, managing threads, and subscribing to events.

## Related

- [Mastra Code overview](https://mastra.ai/docs/mastra-code/overview)
- [Harness Class reference](https://mastra.ai/reference/harness/harness-class)
- [Mastra Code configuration](https://mastra.ai/docs/mastra-code/configuration)