Quickstart

This guide takes you from zero to a published codemod. Each step includes just enough to get started, with links to deeper documentation.

Building codemods

Codemods can be built using:

MCP — AI-assisted creation in your IDE (recommended for getting started)
CLI — Scaffold and build locally with npx codemod init
Studio — Web-based prototyping with live runner and AST viewer

Once you have a codemod package, validation, running, and publishing work the same way regardless of how you built it.

MCP (AI-assisted)
CLI (Manual)
Studio (Web)

Generate a codemod

Make sure you have MCP installed, then ask your AI assistant to create a codemod. Be specific about what you want to transform:

Create a jssg codemod that converts all console.log statements to console.info in TypeScript files. 

The codemod should:
- Target .ts and .tsx files
- Only transform console.log calls (not console.error, console.warn, etc.)
- Preserve all arguments and formatting
- Include test cases for the transformation

MCP best practices

Tips for writing effective prompts and getting the most out of your AI assistant.

You’ll get a complete package structure:

my-codemod

README.md

codemod.yaml

workflow.yaml

scripts

codemod.ts

tests

fixtures

input.tsx

expected.tsx

For more on package structure, see Package Structure.Need the live runner or AST viewer? If you need tools like the live runner, AST viewer, or shareable links, you can bring your codemod into Codemod Studio and continue development there.

Validate your codemod

Run tests to ensure your codemod works correctly:

npx codemod jssg test ./scripts/codemod.ts --language tsx

For test structure, CI integration, and debugging strategies, see Testing.

Run your codemod

Run your codemod on a target codebase:

npx codemod workflow run -w ./my-codemod/ -t /path/to/your/project

For all CLI options and running from the registry, see CLI reference.

Publish your codemod

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 via npx codemod @codemod-name.For CI/CD automation and more publishing features, see Publishing guide.

Scaffold a new codemod

npx codemod init

You’ll be prompted for:

Codemod type: JSSG (most use cases) or multi-step workflow
Target language: JavaScript/TypeScript, Python, etc.
Project details: name, description, author, license
Package options: manager (npm/pnpm/yarn), private/public, monorepo structure
CI setup: optionally generate GitHub Actions workflow for publishing

This creates a complete package structure:

my-codemod

README.md

codemod.yaml

workflow.yaml

scripts

codemod.ts

tests

fixtures

input.tsx

expected.tsx

For more on package structure, see package structure.

Write your transform

Edit scripts/codemod.ts to define your transformation logic. Here’s a simple example that converts console.log to logger.log:

scripts/codemod.ts

import type { Transform } from "codemod:ast-grep";
import type TSX from "codemod:ast-grep/langs/tsx";

const transform: Transform<TSX> = (root) => {
  const rootNode = root.root();
  const consoleCalls = rootNode.findAll({
    rule: { pattern: "console.log($$$ARGS)" },
  });

  if (consoleCalls.length === 0) return null;

  const edits = consoleCalls.map((node) => {
    const args = node.getMultipleMatches("ARGS")
      .map(arg => arg.text())
      .join(", ");
    return node.replace(`logger.log(${args})`);
  });

  return rootNode.commitEdits(edits);
};

export default transform;

For the full JSSG API, see JSSG Quickstart.

Test your codemod

Run tests to ensure your codemod works correctly:

npx codemod jssg test ./scripts/codemod.ts --language tsx

For test structure, CI integration, and debugging strategies, see Testing.

Run on a target codebase

npx codemod workflow run -w ./my-codemod/ -t /path/to/your/project

For all CLI options and running from the registry, see CLI reference.

Publish your codemod

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 via npx codemod @codemod-name.For CI/CD automation and more publishing features, see Publishing guide.

Getting help

Join the community

Ask questions, get help, and connect with other framework maintainers on Slack.

Book a call

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

Next steps

CLI

Learn more about Codemod CLI.

Workflows

Orchestrate complex multi-step migrations.

JSSG

Learn the transformation engine in depth.

Publishing

Authentication methods and CI/CD setup.

First steps

Enterprise

Community

Other Resources

Building codemods

MCP best practices

Getting help

Join the community

Book a call

Next steps

CLI

Workflows

JSSG

Publishing

First steps

Enterprise

Community

Other Resources

​Building codemods

MCP best practices

​Getting help

Join the community

Book a call

​Next steps

CLI

Workflows

JSSG

Publishing

Building codemods

Getting help

Next steps