Skip to main content
A Codemod package is a directory containing everything needed to run an automated code transformation: metadata, workflow definition, transformation scripts, and test fixtures. Packages are fully portable—run them locally, in CI, or share them via the Codemod Registry.

​
Directory Layout

Scaffold a new package with: 
npx codemod init
my-codemod-package
codemod.yaml
workflow.yaml
scripts
codemod.ts
rules
config.yml
tests
basic-transform
input.tsx
expected.tsx
File/FolderPurpose
codemod.yamlPackage metadata (name, version, author, etc.)
workflow.yamlWorkflow definition with nodes and steps
scripts/JavaScript/TypeScript codemods (JSSG)
rules/YAML ast-grep rule definitions
tests/Test fixtures with input.*/expected.* pairs or input/ + expected/ directory snapshots
The scripts/ and rules/ folders are conventional, not required—use any paths you prefer as long as you reference them correctly in workflow.yaml.

​
Package Behavior

Codemod packages use a workflow-first model and can be:
  • Workflow-only: workflow.yaml has executable steps and no install-skill steps.
  • Skill-only: workflow.yaml has install-skill steps and no executable steps, with authored skill files under agents/skill/<skill-name>/.
  • Workflow + skill: workflow.yaml has both executable and install-skill steps, with authored skill files under agents/skill/<skill-name>/.
Current CLI behavior:
  • codemod init (default) scaffolds workflow-only packages.
  • codemod init --skill scaffolds skill-only packages.
  • codemod init --with-skill scaffolds workflow + skill packages.
  • --skill and --with-skill are mutually exclusive.
  • --skill and --project-type are mutually exclusive.
  • codemod publish supports workflow-only, skill-only, and workflow + skill packages by validating workflow behavior and skill layout.
  • codemod workflow validate -w <package-root> validates package behavior:
    • workflow-only: workflow checks
    • skill-only: skill structure/frontmatter/reference checks
    • workflow + skill: both workflow and skill checks
Skill-capable packages should keep authored skill content under: 
agents/skill/<skill-name>/
  SKILL.md
  references/
All files in this authored skill directory are treated as install payload and copied recursively when users run npx codemod <package-id> and accept the skill-install prompt.

​
Package Metadata (codemod.yaml)

The codemod.yaml file defines your package’s metadata and configuration.
codemod.yaml
schema_version: "1.0"

name: "my-awesome-codemod"
version: "0.1.0"
description: "Transform legacy patterns to modern syntax"
author: "Your Name <you@example.com>"
license: "MIT"
workflow: "workflow.yaml"
category: "migration"

targets:
  languages: ["typescript"]

keywords: ["upgrade", "breaking-change", "react", "v17-to-v18"]

registry:
  access: "public"
  visibility: "public"
For skill-only packages, keep workflow: "workflow.yaml" and define install-skill steps in that workflow; authored skill content lives under agents/skill/<skill-name>/. Available fields:
​
schema_version
string
default:"1.0"
required
Codemod workflow schema version.
​
name
string
required
Codemod package name (unique within scope).Naming rules: /^[a-z0-9-_/]+$/ (lowercase letters, numbers, hyphens, underscores, and / for scope separation only)Not allowed: uppercase letters, dots, commas, spaces, or other special charactersValid examples:
  • remove-console-logs
  • @scope/remove-console-logs (using @organization-or-project-scope/name provides better discoverability in the Codemod Registry)
​
version
string
default:"0.1.0"
required
Semantic version of the package.
​
description
string
required
Brief description of what the codemod does.
​
author
string
required
Author name and email, e.g., Jane Doe <jane@example.com>.
​
license
string
default:"MIT"
required
License identifier (SPDX), e.g., MIT.
​
workflow
string
default:"workflow.yaml"
required
Relative path to your workflow file (required for workflow-only, skill-only, and workflow + skill packages).
​
category
string
default:"migration"
Category for the codemod.
​
targets.languages
string[]
Languages targeted by this codemod (selected language during codemod init; editable later).
​
keywords
string[]
Keyword tags are an optional feature helping developers quickly identify the purpose, scope, and relevance of a codemod. They also enable better search, filtering, and reporting when managing many codemods across frameworks and projects.Example: keywords: ["react", "v18-to-v19", "migration"]
  • Keep tags concise (1–2 words).
  • Use lowercase for consistency.
  • Don’t overload with tags — 2–4 per codemod is ideal.
  • Prioritize transformation type + framework/library + version (if relevant).
1. Transformation Type TagsConsider these categories when describing why the codemod exists:
  • upgrade – helps upgrade code to newer versions (encompasses both breaking changes and feature adoption). You may also consider adding one of the following tags:
    • breaking-change – adapts code to framework/library breaking API changes.
    • feature-adoption – helps adoption of new optional or incremental features.
  • security – addresses known vulnerabilities or unsafe patterns.
  • cross-migration – replaces one library/framework with another.
  • i18n – internationalization migrations or improvements.
  • a11y – accessibility improvements and compliance.
  • standardization – unifies patterns, conventions, or APIs across a codebase.
  • code-mining – identifies, flags, or extracts patterns without transforming. Use if codemod is for detection-only.
Rule of thumb: Pick one primary type tag per codemod. Avoid mixing breaking-change and feature-adoption in the same codemod.
2. Target Version TagsUse these to indicate the framework/library version the codemod prepares for.
  • Format: vX or vX-to-vY (for upgrades).
  • Examples:
    • v17-to-v18 (React 17 → 18)
    • v5-to-v6 (React Router 5 → 6)
    • v16 (Angular 16 breaking changes)
Rule of thumb: If the codemod is version-specific, always tag it.
3. Framework / Library / SDK TagsAlways add the ecosystem name to improve discoverability.
  • Examples:
    • react
    • nextjs
    • nodejs
    • angular
    • msw
    • i18next
Rule of thumb: Use the official, common name of the framework/library.
4. Example Tag SetsHere are some examples to illustrate how tags combine:
  • React Root API Upgrade (17 → 18)
    • Tags: upgrade, breaking-change, v17-to-v18, react
  • Adopt React Hooks
    • Tags: upgrade, feature-adoption, react
  • Migrate from Moment.js to Day.js
    • Tags: cross-migration, momentjs, dayjs
  • Remove Hardcoded Strings for i18n
    • Tags: i18n, i18next
  • Add ARIA labels for accessibility
    • Tags: a11y, react
  • Detect Insecure crypto API usage
    • Tags: security, nodejs, crypto
​
registry.access
string
default:"public"
Access controls who can run/use the codemod (once they can see it).
  • public: Anyone can run the codemod.
  • private: Only the owner can run the codemod.
  • pro: Only Pro plan users can run the codemod.
Access applies on top of visibility. For example, visibility: public with access: pro shows the package publicly, but only Pro users can run it.
​
registry.visibility
string
default:"public"
Visibility controls who can see the package in the Registry (search, listings, and UI).
  • public: Everyone can see the package in the Registry.
  • private: Only the owner can see the package.
  • org: Members of the package’s organization scope can see the package.
  • user: Visible only to the publishing user (user-scoped visibility).
During scaffolding, the CLI sets public/private based on —private. You can change to any supported value above when publishing.
​
capabilities
string[]
default:"[]"
Array of capabilities required by this codemod for accessing sensitive operations.Available capabilities:
  • fs - File system access (fs, fs/promises)
  • fetch - Network requests (global fetch)
  • child_process - Process spawning (child_process)
Only enable capabilities your codemod actually needs. Each capability increases security risk for untrusted codemods.
See Security & Capabilities for detailed information about the security model and usage examples.

​
Next Steps

Workflows

Get started with building Codemod Workflows.

JSSG

Write JavaScript/TypeScript transformations.