1

Create a new codemod package

npx codemod init
When creating a new codemod project, you’ll be prompted for:
  • Project directory
  • Codemod type:
  • Target language
  • Project name
  • Description
  • Author
  • License type
  • If your codemod is private
This creates a new folder with the required files and structure.
2

Explore the generated project

An example codemod package:
example-codemod/
├── .gitignore
├── README.md
├── codemod.yaml        # Codemod package manifest and metadata
├── workflow.yaml       # Workflow definition for running the codemod
├── scripts/            # JS/TS codemods and shell scripts
│   └── codemod.ts      # JS ast-grep codemod entry point
└── rules/              # YAML ast-grep rule definitions
    └── config.yml
You can combine different codemod types in a single package. The scripts/ and rules/ folders are conventional, not required—use any paths you prefer as long as you reference them correctly from workflow.yaml.
Check out the codemod package structure for more details.
3

Understand an example workflow

The generated workflow.yaml will differ depending on the codemod type you select:
Combined (jssg + yaml + shell + ai)
version: "1"
nodes:
  - id: run-all
    name: Combined Example
    type: automatic
    steps:
      # 1) JS ast-grep (jssg)
      - name: "JS ast-grep codemod"
        js-ast-grep:
          js_file: "scripts/codemod.ts"
          base_path: "."
          language: "typescript"
          include:
            - "**/*.ts"
            - "**/*.tsx"

      # 2) YAML ast-grep
      - name: "Apply YAML ast-grep rules"
        ast-grep:
          config_file: "rules/config.yml"
          base_path: "./src"
          include:
            - "**/*.ts"
          exclude:
            - "**/*.test.ts"

      # 3) AI step
      - name: "AI review"
        ai:
          prompt: |
            Summarize risky changes and suggest tests.
      
      # 4) Shell command
      - name: "Format code"
        run: npx prettier --write "**/*.{ts,tsx,js,jsx}"
Learn more about building workflows here.
4

Validate & run your codemod package

npx codemod workflow validate -w workflow.yaml
npx codemod workflow run -w workflow.yaml
This will check your workflow for errors and then run it locally.
The workflow validate command checks syntax and schema compliance, but not logical correctness. Always test with real data to ensure expected behavior.