@mastra/codemod

Mastra Codemods

Mastra provides automated code transformations (codemods) to help upgrade your codebase when features are deprecated, removed, or changed between versions.

Codemods are transformations that run on your codebase programmatically, allowing you to apply many changes without manually editing every file.

Quick Start

Run Version-Specific Codemods

npx @mastra/codemod v1

Run Individual Codemods

To run a specific codemod:

npx @mastra/codemod <codemod-name> <path>

Examples:

# Transform a specific file
npx @mastra/codemod v1/mastra-core-imports src/mastra.ts

# Transform a directory
npx @mastra/codemod v1/mastra-core-imports src/lib/

# Transform entire project
npx @mastra/codemod v1/mastra-core-imports .

Available Codemods

v1 Codemods (v0 → v1 Migration)

Codemod	Description
v1/agent-abort-signal	Moves abortSignal from modelSettings to top-level options in agent method calls
v1/agent-generate-stream-v-next	Renames agent.generateVNext() → agent.generate() and agent.streamVNext() → agent.stream()
v1/agent-processor-methods	Renames agent.getInputProcessors() → agent.listInputProcessors() and similar output processor methods
v1/agent-property-access	Transforms agent property access to method calls: agent.llm → agent.getLLM()
v1/agent-voice	Moves agent voice methods to namespace: agent.speak() → agent.voice.speak()
v1/client-get-memory-thread	Updates client.getMemoryThread(threadId, agentId) to use object parameter
v1/client-msg-function-args	Transforms MastraClient agent method calls to use messages as the first argument
v1/client-offset-limit	Renames pagination properties from offset/limit to page/perPage
v1/client-sdk-types	Renames Client SDK types from Get* to List* pattern
v1/client-to-ai-sdk-format	Renames toAISdkFormat to toAISdkStream
v1/evals-prebuilt-imports	Updates prebuilt scorer imports from scorers/llm and scorers/code to scorers/prebuilt
v1/evals-run-experiment	Renames runExperiment() → runEvals() in imports and usages
v1/evals-scorer-by-name	Renames mastra.getScorerByName() → mastra.getScorerById()
v1/experimental-auth	Renames experimental_auth to auth in Mastra configuration
v1/mastra-core-imports	Updates imports from @mastra/core to use new subpath imports
v1/mastra-plural-apis	Renames Mastra plural API methods from get* to list*
v1/mcp-get-tools	Renames mcp.getTools() → mcp.listTools()
v1/mcp-get-toolsets	Renames mcp.getToolsets() → mcp.listToolsets()
v1/memory-message-v2-type	Renames MastraMessageV2 type → MastraDBMessage in imports and usages
v1/memory-query-to-recall	Renames memory.query() → memory.recall()
v1/memory-vector-search-param	Renames vectorMessageSearch parameter → vectorSearchString in memory.recall() calls
v1/memory-readonly-to-options	Moves memory.readOnly to memory.options.readOnly in agent method calls
v1/runtime-context	Renames RuntimeContext to RequestContext and updates parameter names from runtimeContext to requestContext
v1/storage-get-messages-paginated	Renames storage.getMessagesPaginated() → storage.listMessages() and offset/limit → page/perPage
v1/storage-get-threads-by-resource	Renames storage.getThreadsByResourceId() → storage.listThreadsByResourceId()
v1/storage-list-messages-by-id	Renames storage.getMessagesById() → storage.listMessagesById()
v1/storage-list-workflow-runs	Renames storage.getWorkflowRuns() → storage.listWorkflowRuns()
v1/storage-postgres-schema-name	Renames schema property → schemaName in PostgresStore constructor
v1/vector-pg-constructor	Converts new PgVector(connectionString) to new PgVector({ connectionString })
v1/voice-property-names	Renames voice property names in Agent configuration: speakProvider → output
v1/workflow-create-run-async	Renames workflow.createRunAsync() → workflow.createRun()
v1/workflow-list-runs	Renames workflow.getWorkflowRuns() → workflow.listWorkflowRuns()
v1/workflow-run-count	Renames context.runCount → context.retryCount in step execution functions
v1/workflow-stream-vnext	Renames streamVNext(), resumeStreamVNext(), and observeStreamVNext()

CLI Options

Commands

npx @mastra/codemod <command> [options]

Available Commands:

• <codemod-name> <path> - Apply specific codemod

Global Options

• --dry - Preview changes without applying them
• --print - Print transformed code to stdout
• --verbose - Show detailed transformation logs

Examples

# Show verbose output for specific codemod
npx @mastra/codemod --verbose v1/mastra-core-imports src/

# Print transformed code for specific codemod
npx @mastra/codemod --print v1/mastra-core-imports src/mastra.ts

Contributing

Adding New Codemods

• Create the codemod in src/codemods/<version>

• Add test fixtures in src/test/__fixtures__/

• Create tests in src/test/

• Use the scaffold script to generate boilerplate:

  pnpm scaffold
  

Testing Codemods

First, navigate to the codemod directory:

cd packages/codemod

Then run the tests:

# Run all tests
pnpm test

# Run specific codemod tests
pnpm test mastra-core-imports

# Test in development
pnpm test:watch