Skip to main content
This guide walks you through creating, testing, and publishing a codemod from scratch. You’ll first set up Codemod in your coding agent, then scaffold and build a JSSG codemod, then test and publish it to the registry.

​
1. Set up Codemod in your coding agent

Start by installing Codemod Master Skill and Codemod MCP for your preferred coding agent: 
npx codemod agent install --harness auto --user
This is the default setup path for Codemod’s AI-native CLI. It installs Codemod Master Skill and Codemod MCP so your agent can use Codemod CLI with built-in best practices for building, running, testing, and publishing codemods. If you’d rather scope the setup to the current repo or workspace, use --project.

​
2. Scaffold and build your codemod

Create a dedicated folder or repo for your codemod work, then scaffold a starter package: 
npx codemod init
The starter package gives your agent a concrete structure to refine or replace while keeping the workflow, tests, and publishing flow in place. Once the package is scaffolded, you can ask your AI agent to help you build codemods for things like framework upgrades, design system migrations, i18n work, code-mining tasks, and more. For example:

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

CursorOpen in Cursor

Prompting best practices

Tips for writing effective prompts and getting the most out of building codemods with AI.
You will end up with a 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 <[email protected]>"
license: "MIT"
workflow: "workflow.yaml"

targets:
  languages: ["tsx"]

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

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

capabilities: []

​
3. Validate and test

From your scaffolded codemod package directory, validate the workflow and run the generated tests. Validate the workflow schema: 
npx codemod 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.

​
4. Run your codemod

From the same package directory, 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.

​
5. Publish

When you’re happy with the result, publish from the package directory: 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.