Codemod CLI and workflow features are free for local use. For large-scale refactoring across many repos, the Codemod app provides:
- Visual parameter configuration - Edit workflow parameters through the UI instead of YAML
- Centralized state management - Coordinate migrations with persistent state across repos and teams
- Multi-repo orchestration - Run workflows across your entire codebase with progress tracking
- Business insights - Track migration progress with custom metrics and dashboards
This is an advanced topic. If you’re just getting started, we recommend using Codemod Studio or Codemod MCP to create your Codemod package with the help of AI.
Package Structure
Directory Layout
npx codemod workflow run -w ./my-codemod-package/.
You can combine types in a single package. The 
scripts/ and rules/ folders are conventional, not required—use any paths and reference them from workflow.yaml.workflow.yaml and any scripts, rules, or assets referenced by your workflow.
1
Scaffolding packages
2
Validating workflows
3
Running workflows
Package Metadata (codemod.yaml)
Thecodemod.yaml file defines your Codemod package’s metadata and configuration.
Example codemod.yaml file:
codemod.yaml
Available codemod.yaml fields
Available codemod.yaml fields
Codemod workflow schema version.
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/nameprovides better discoverability in the Codemod Registry)
Semantic version of the package.
Brief description of what the codemod does.
Author name and email, e.g., 
Jane Doe <jane@example.com>.License identifier (SPDX), e.g., 
MIT.Relative path to your workflow file.
Category for the codemod.
Languages targeted by this codemod (selected language during 
codemod init; editable later).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: 
1. Transformation Type TagsConsider these categories when describing why the codemod exists:
2. Target Version TagsUse these to indicate the framework/library version the codemod prepares for.
3. Framework / Library / SDK TagsAlways add the ecosystem name to improve discoverability.
4. Example Tag SetsHere are some examples to illustrate how tags combine:
keywords: ["react", "v18-to-v19", "migration"]Best practices and conventions
Best practices and conventions
- 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.
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: vXorvX-to-vY(for upgrades).
- Examples:
- v17-to-v18(React 17 → 18)
- v5-to-v6(React Router 5 → 6)
- v16(Angular 16 breaking changes)
 
3. Framework / Library / SDK TagsAlways add the ecosystem name to improve discoverability.
- Examples:
- react
- nextjs
- nodejs
- angular
- msw
- i18next
 
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
 
- Tags: 
- Adopt React Hooks
- Tags: upgrade,feature-adoption,react
 
- Tags: 
- Migrate from Moment.js to Day.js
- Tags: cross-migration,momentjs,dayjs
 
- Tags: 
- Remove Hardcoded Strings for i18n
- Tags: i18n,i18next
 
- Tags: 
- Add ARIA labels for accessibility
- Tags: a11y,react
 
- Tags: 
- Detect Insecure crypto API usage
- Tags: security,nodejs,crypto
 
- Tags: 
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.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.Workflow File (workflow.yaml)
Theworkflow.yaml file defines your Codemod package’s workflow. A workflow is a collection of nodes that are executed in order. A workflow has four top-level keys:
workflow.yaml
Nodes & Steps
Nodes
Nodes are execution units in your workflow. They can be automatic or manual, depend on other nodes, and may define strategy (e.g., matrix), trigger, runtime, env, and an ordered list of steps.Unique within the workflow.
Display name.
automatic (default) or manual.Environment variables for the node or step.
Steps
Steps are the atomic actions inside a node. They run sequentially and each step performs one transformation or action using a specific engine:- js-ast-grep- Primary transformation engine: JavaScript/TypeScript codemods using ast-grep
- ast-grep- Declarative pattern matching with YAML rules
- run- Shell commands for external tools and setup
- ai- LLM-powered transformations and reviews
- codemod- Compose other published codemods
jssg (JS ast-grep) step
Runs JavaScript/TypeScript codemods with full programmatic control over AST transformations. Use jssg for:- Complex transformations requiring logic (loops, conditions, functions)
- AST manipulations beyond find/replace
- Cross-file analysis or coordination
- Type-safe transformations with TypeScript
New to jssg? Start with the jssg quickstart to write your first transform, then see the jssg API reference for the complete API.
1
Create a jssg codemod:
Under Learn more about how to write jssg codemods: jssg documentation.
scripts/ folder, create a new jssg codemod.scripts/codemod.ts
2
Add a jssg step to your workflow:
workflow.yaml
Available parameters
Available parameters
Step label.
Conditional expression to gate step execution. Supports See Variable resolution for full syntax.
params.x, state.x, and matrix value keys. Operators: ==, !=, >, <, &&, ||.Path to the JS/TS file that implements the codemod.
Target language (e.g., 
typescript, javascript, etc.).Include glob patterns.
Exclude glob patterns.
Base path for resolving globs.
Maximum concurrent threads.
Perform a dry run without applying changes.
AI step
Calls an AI agent with a prompt. This is helpful when your workflow requires leveraging LLM intelligence for more complex tasks for capabilities beyond deterministic transformations. To use a AI step:1
Set the environment variables:
You can either set the environment variables in your shell or in your environment file.
.env
2
Add an AI step to your workflow:
workflow.yaml
Available parameters
Available parameters
Step label.
Conditional expression to gate step execution. Supports See Variable resolution for full syntax.
params.x, state.x, and matrix value keys. Operators: ==, !=, >, <, &&, ||.Prompt to send to the AI agent.
Model identifier. Overrides 
LLM_MODEL if set.System prompt to scope the AI agent’s behavior.
Maximum number of agent steps before stopping.
LLM provider/protocol. Supported: 
openai, anthropic, azure_openai.LLM base URL. If omitted, defaults to the provider’s standard endpoint for the selected protocol. You can override with a custom endpoint.
API key to access the LLM.The AI step requires valid LLM credentials. Provide them via environment variables:
LLM_BASE_URL is optional. If omitted, defaults to the provider’s standard endpoint for the selected protocol. You can override with a custom endpoint.
YAML ast-grep step
Executes ast-grep using declarative YAML rules. Use for simple, fast pattern matching when you don’t need programmatic logic. When to use YAML ast-grep:- Simple find/replace transformations
- No conditional logic needed
- Fastest to write for basic patterns
- Need conditional logic or loops
- Complex AST manipulations
- Cross-file coordination
1
Create a YAML ast-grep rules file:
Under Learn more about how to write YAML ast-grep rules: ast-grep YAML reference
rules/ folder, create a new YAML ast-grep rules file.rules/config.yml
2
Add a YAML ast-grep step to your workflow:
workflow.yaml
Available parameters
Available parameters
Step label.
Conditional expression to gate step execution. Supports See Variable resolution for full syntax.
params.x, state.x, and matrix value keys. Operators: ==, !=, >, <, &&, ||.Path to the ast-grep configuration file (.yaml).
Include glob patterns.
Exclude glob patterns.
Base path for resolving globs.
Maximum concurrent threads.
Codemod Registry step
Runs another codemod by package name (or local path). Use to compose larger migrations by chaining codemods. To use a Codemod Registry step:1
Find or publish a codemod to the Codemod Registry:
You can:
- find and use an existing codemod in Codemod Registry, or
- publish a Codemod package to Codemod Registry.
2
Add a Codemod Registry step to your workflow:
workflow.yaml
Available parameters
Available parameters
Step label.
Conditional expression to gate step execution. Supports See Variable resolution for full syntax.
params.x, state.x, and matrix value keys. Operators: ==, !=, >, <, &&, ||.Codemod source (registry package or local path).
Version pinning: specify an exact version in 
source (e.g., @scope/pkg@1.2.3) for reproducible runs. If you omit the version, the latest published version is used.CLI arguments passed to the codemod.
Environment variables used during execution.
Working directory for execution.
Step-level environment variables. For 
codemod steps, these are forwarded to the invoked workflow as parameters with an env_ prefix (e.g., FOO → env_FOO). They are not applied to the OS environment of the nested workflow.You can aggregate multiple codemods by adding more than one 
codemod step in the same node. A Codemod package may itself orchestrate other codemods, enabling nested compositions for larger upgrades.workflow.yaml
- Steps in a node run sequentially from top to bottom.
- Use depends_onor a matrixstrategyacross multiple nodes for gating/parallelism.
- If a step fails, the node fails and subsequent steps in that node are skipped.
Shell command step
Runs shell commands on the host. Use for setup/cleanup, invoking external tools, or glue logic between transformations.workflow.yaml
Available parameters
Available parameters
Step label.
Conditional expression to gate step execution. Supports See Variable resolution for full syntax.
params.x, state.x, and matrix value keys. Operators: ==, !=, >, <, &&, ||.Inline shell command to execute.
Step-level environment variables applied to the process environment for this 
run step.Shared State
State enables workflows to persist data across runs and coordinate work across repositories and teams:- Sharding: Distribute work across teams or repositories
- Progress tracking: Resume interrupted migrations without losing work
- Coordination: Maintain consistency across related codebases
The Codemod app provides centralized state management for large-scale refactoring across many repos. Pro codemods like i18n codemod use state to coordinate multi-repo migrations.
workflow.yaml
workflow.yaml
Parameters
Parameters make workflows configurable and reusable across different projects and teams. Define them in your workflow with a schema:workflow.yaml
Accessing Parameters in Steps
Parameters are exposed differently depending on the step type: In jssg transforms - access viaoptions.params:
codemod.ts
For complete jssg parameter patterns and examples, see jssg Advanced: Accessing Parameters.
PARAM_ prefix:
workflow.yaml
env_ prefix:
workflow.yaml
- Sharding configuration: Method (directory,codeowner) and targets
- PR settings: Size limits, auto AI review, pre/post run scripts
Enterprise Features: In the Codemod app, you can configure parameters visually through the UI. See Campaigns for running parameterized workflows at scale.
Matrix Strategy
workflow.yaml
Dynamic Matrix Task Recompilation
Dynamic Matrix Task Recompilation
When the array referenced by 
from_state changes, Codemod CLI:- Creates new tasks for new items.
- Marks tasks as WontDoif their item is removed.
- Leaves existing tasks untouched if their item remains.
Matrix nodes have a master task that tracks the status of all generated tasks.
Accessing Matrix Values in Steps
Matrix values are exposed differently per step type: In jssg transforms - access viaoptions.matrixValues:
scripts/codemod.ts
For complete jssg sharding patterns and examples, see jssg Advanced: Accessing Matrix Values.
workflow.yaml
Manual Trigger
workflow.yaml
Task UUIDs & Resume
Task UUIDs & Resume
Manual tasks are assigned unique UUIDs. You can resume:
- 
All paused tasks:
- 
A specific task:
State Updates
| Syntax | Meaning | Example | 
|---|---|---|
| KEY=VAL | Set state key to value | count=10 | 
| KEY@=VAL | Append value to array at state key | shards@={"team":"core","shardId":"1"} | 
| Dot notation | Set nested state fields | config.retries=5 | 
| JSON values | Use valid JSON for objects/arrays | user={"name":"Alice","id":123} | 
All state updates must be valid JSON if not a primitive. Updates are applied only if the task exits successfully.
Container Runtimes
Container Runtimes
Planned feature: containerized execution (e.g., Docker/Podman). Currently, workflows run in the host shell. When available, you’ll be able to specify a runtime per node or template.
State Management & Persistence
State Management & Persistence
Workflow state is persisted after every task. If interrupted, you can resume from the last saved state—no work is lost.
Matrix Master Task
Matrix Master Task
For matrix nodes, a master task aggregates the status of all generated tasks.
If all child tasks complete, the master is
If all child tasks complete, the master is
Completed. If any fail, the master is Failed.Cyclic Dependency Example
Cyclic Dependency Example
If your workflow has a cycle:You’ll see:
workflow.yaml
console
This error is shown when you run 
npx codemod workflow validate or npx codemod workflow run on a workflow with a cyclic dependency.Task Statuses
Pending
Queued; waiting for runner.
Running
Currently executing.
Completed
Succeeded; diff applied.
Failed
Script exited non-zero; diff discarded.
AwaitingTrigger
Waiting for manual approval.
Blocked
Dependencies not finished.
WontDo
Matrix item removed; task skipped.
Variable Resolution
- Parameter: ${{params.branch}}— Supplied at runtime
- Environment: ${{env.CI}}— Host env var
- Shared State: ${{state.counter}}— Live JSON value
- 
In matrix tasks, each object key becomes an environment variable (e.g., $team,$shardId, …). Inside steps, variables are unprefixed.
- 
Operators (==,!=,>,<,&&,||) are supported inside string interpolations like${{ ... }}for resolving parameters, state, and matrix values.
Roadmap
Container runtime support
Support for 
runtime: docker and other container runtimes, allowing tasks to run in isolated environments.Nested matrix strategies
Support for matrix strategies within matrix strategies, enabling more complex task fan-out.