Skip to main content
This guide walks you through creating, testing, and publishing a codemod from scratch. You’ll scaffold a package, bootstrap Codemod’s AI-native CLI setup, build a workflow with Codemod MCP in your IDE, then test and publish it to the registry.

​
1. Scaffold your project

Run the interactive scaffolder to create a new codemod package: 
npx codemod@latest init my-codemod
You’ll be prompted for a codemod type:
  • jssg codemod for AST-based transformations
  • multi-step workflow for orchestrated migrations that combine shell, YAML, and JSSG steps
  • agent skill codemod for authored skill packages used in coding-agent workflows
For this guide, choose jssg codemod. The scaffolder may also ask whether to add an . This quickstart builds a workflow package, so leave that option disabled.

​
2. Bootstrap Codemod’s AI-native CLI

Set up Codemod MCP in your IDE with Codemod’s AI-native CLI: 
npx codemod agent install --harness auto --project
This installs Codemod’s assistant-side skill bundle, adds the Codemod MCP server to the detected coding assistant, and updates local discovery guidance files. If you prefer to configure MCP yourself, see the manual setup in Codemod MCP.

​
3. Build your codemod

With Codemod’s MCP + skill bootstrap installed, ask your AI assistant to create a codemod. After restarting your IDE or harness session, it can discover Codemod guidance and MCP tools automatically. Be specific about the transformation you need:

Extract React components from inside other components to module scope to prevent re-creation on render.

CursorOpen in Cursor

Prompting tips

Tips for writing effective prompts and getting the most out of MCP.
 The AI will use MCP tools to analyze your code, generate the transform script, and set up the package. You’ll get a complete Codemod package:
my-codemod
codemod.yaml
workflow.yaml
scripts
codemod.ts
tests
fixtures
input.tsx
expected.tsx
schema_version: "1.0"

name: "extract-inner-components"
version: "0.1.0"
description: "Move React components defined inside other components to module scope"
author: "Your Name <you@example.com>"
license: "MIT"
workflow: "workflow.yaml"

targets:
  languages: ["tsx"]

keywords: ["react", "performance", "components"]

registry:
  access: "public"
  visibility: "public"

capabilities: []

​
4. Validate and test

Validate the workflow schema: 
npx codemod@latest workflow validate -w workflow.yaml
Run tests against your input/expected fixtures: 
npx codemod jssg test -l tsx ./scripts/codemod.ts
Tests use fixtures in the tests/ directory. You can use simple input.*/expected.* file pairs or input/ + expected/ directory snapshots when your codemod creates or deletes files. If MCP generated test fixtures, they will run automatically. For test structure, CI integration, and debugging strategies, see Testing.

​
5. Run your codemod

Run your codemod on a target codebase: 
npx codemod workflow run -w . -t /path/to/your/project
AI-powered steps: If your workflow includes an AI step gated by a parameter, enable it at runtime:
LLM_API_KEY=your-key npx codemod workflow run -w . -t /path/to/project --param run_ai_step=true
Set LLM_API_KEY as an environment variable for your chosen provider. With an API key, the built-in AI step runs normally. Without one, Codemod prints [AI INSTRUCTIONS], which parent agents such as Codex- or Claude-style tooling can pick up. See Workflow Reference — AI steps for provider configuration.
For all CLI options, see CLI reference.

​
6. Publish

Share your codemod with your team or the community: 
npx codemod login
npx codemod publish
Your codemod is now in the Codemod Registry and runnable by anyone via npx codemod @your-scope/codemod-name. For CI/CD automation, trusted publishers, and API keys, see the Publishing guide.

​
Next steps

​
Scale your migrations

Your migration experience does not stop here. When you’re managing migrations across large codebases or multiple teams, the same codemod package can power Campaigns for automated multi-repo rollouts and Insights for tracking adoption progress. See the Platform quickstart for the full enterprise workflow.

​
Getting help

Join the community

Ask questions, get help, and connect with other codemod users on Slack.

Book a call

Schedule a demo or get hands-on help from the Codemod team.

​
Learn more

CLI reference

Full CLI command reference.

Workflow reference

Complete workflow.yaml specification.

JSSG

Learn the transformation engine in depth.

Publishing

Authentication methods and CI/CD setup.