Codemod CLI: workflows, ast-grep transforms and a registry for large refactors

The repository is the CLI and the engine, not the platform

The distinction matters, because the project describes itself as a platform and the repository is not the platform. The README calls Codemod an AI-powered, community-led platform for automating code migrations, framework upgrades and large-scale changes, and then says what this particular repository houses: the Codemod CLI and its underlying workflow engine, everything needed to scaffold, test and run codemods locally or in CI.

The hosted pieces are separate and optional. The CLI can connect to the Codemod Registry and the Codemod Platform when you want to publish a codemod or orchestrate a migration across many repositories. The Platform is described as the thing that powers campaigns, adding insights, orchestration, dashboards and authoring tools, and the CLI is described as the engine that powers those campaigns. So the local part is genuinely the local part.

The feature list divides into five pieces. The Codemod CLI runs, tests and publishes codemods from a terminal or in CI. Workflows orchestrate multi-step migrations with YAML configuration, matrix strategies and manual approval gates. JSSG is JavaScript ast-grep, where transformations are written in TypeScript with pattern matching and semantic analysis. The Codemod Registry shares and discovers community codemods. The Codemod MCP exposes AI tools for code analysis, AST manipulation and codemod creation in AI-powered IDEs.

The primary language is Rust, the licence is Apache-2.0, and the project is not archived, with the last push on 2026-10-14 and a release of `[email protected]` the same day.

Five commands cover the whole lifecycle

The getting started sequence is short enough to read as a tutorial, and each step corresponds to a stage of the work.

# 1) Open the interactive launcher
npx codemod

# 2) Scaffold a new codemod project
npx codemod init my-codemod

# 3) Test it locally
npx codemod workflow run -w my-codemod/workflow.yaml

# 4) Publish it when you're ready
npx codemod publish my-codemod

# 5) Run it from the Registry
npx codemod @codemod/my-codemod

Step one is the interactive launcher, and it is worth knowing where its boundary is. In an interactive terminal a bare `npx codemod` opens a launcher for creating a package or running one from the registry. In non-interactive contexts it prints the next steps and exits with status `1`. That is a deliberate design for CI, where a command that opened a menu would hang, and it means a pipeline that expects a non-zero exit will see one from a harmless invocation.

Step two scaffolds a project, step three runs the workflow file that the scaffold produced against the working tree, and step four publishes the package. Step five is the interesting one for a consumer: a published codemod is invoked by its registry name, so a team that has written a migration once can run it anywhere with the same command.

Everything goes through `npx`, so there is no global install step in the documented path, and the full command reference lives in the CLI documentation.

Workflows are YAML with matrix strategies and approval gates

The unit of work in this project is a workflow, not a single transform. Workflows orchestrate multi-step migrations with YAML configuration, matrix strategies and manual approval gates.

A YAML file is a better carrier for a migration than a pile of scripts for a reason that shows up on day two of a framework upgrade: a migration usually has an order. Some steps have to run before others, some steps only apply to part of the codebase, and some steps need a human to look at the result before the next one touches anything. The `npx codemod workflow run -w my-codemod/workflow.yaml` form makes the whole thing a single file that can be reviewed, versioned and run in CI.

Matrix strategies are the second feature, and they are the answer to running the same migration across a matrix of situations, for example a set of packages or a set of configurations, without writing one file per combination.

Manual approval gates are the third. A gate in the workflow means the run stops and waits for a person, which is what makes a semi-automatic migration acceptable to a team that does not want a script rewriting a thousand files without a checkpoint. The three features together are the difference between the tool this project is and a plain find and replace, and they are the reason the project describes itself as a workflow engine rather than a transformer.

JSSG writes AST transformations in TypeScript

JSSG is the JavaScript ast-grep layer, and it is the part of the stack aimed at people who want to express a transformation precisely.

The description is that you write powerful AST transformations in TypeScript with pattern matching and semantic analysis. Both halves of that sentence matter. Pattern matching means the transform is written against the shape of the tree, so it fires on a call expression of a given shape rather than on a text pattern that might also match a comment or a string. Semantic analysis means the transform can consult meaning, not just structure, which is what separates a pattern match from a naive rewrite.

The repository's own dependency list shows how the language support is put together. There is a `crates/language-core` crate, a `crates/language-javascript` crate and a `crates/language-python` crate, plus a separately published package, `@jssg/utils`, whose most recent release is 0.0.10. A `crates/tree-sitter-loader` crate suggests tree-sitter grammars are loaded at runtime for parsing, and a `crates/semantic-factory` crate produces the semantic layer, with `ruff_python_semantic` named in the workspace dependencies for Python semantic analysis alongside `ty_ide`.

The polyglot claim in the project description rests on those crates, and the split between the Rust core and the TypeScript authoring layer is the interesting part: the transforms are written in the language of the codebase being transformed, and the engine that runs them is Rust.

A Rust workspace named butterflow, wrapped in a pnpm monorepo

The build is a hybrid, and the `Cargo.toml` shows the Rust half.

[workspace.package]
authors = ["Codemod.com"]
description = "A self-hostable workflow engine for code transformations"
documentation = "https://docs.rs/butterflow"
repository = "https://github.com/codemod/codemod"
homepage = "https://github.com/codemod/codemod"
license = "Apache-2.0"
rust-version = "1.76"
version = "1.18.5"
edition = "2021"

The description calls itself a self-hostable workflow engine, and the documentation link points at `docs.rs/butterflow`, so the engine crates are published under the name butterflow while the CLI is published as `codemod-cli`. A dependency that pins the CLI does not automatically pin the engine, which is a detail to keep in mind when a migration has to be reproducible.

The member list is a map of the system: `crates/models`, `crates/core`, `crates/cli`, `crates/runners`, `crates/state`, `crates/codemod-sandbox` with its own build crate, `crates/telemetry`, `crates/mcp`, `crates/testing-utils`, `xtask`, `crates/llrt-capabilities`, the three language crates, `crates/semantic-factory` and `crates/tree-sitter-loader`. The sandbox crate is the interesting one for a reviewer, because running generated code means running untrusted code, and `crates/mcp` with `rmcp` 0.8 in server mode is the Model Context Protocol server.

The JavaScript half is a pnpm workspace whose root `package.json` is private and describes itself as a monorepo for all the interconnected tools of codemod.com:

  "scripts": {
    "release": "pnpm changeset publish",
    "lint": "oxlint",
    "lint:fix": "oxlint --fix",
    "format:fix": "oxfmt --write",
    "format": "oxfmt --check",
    "format:rust": "cargo fmt --check",
    "format:rust:fix": "cargo fmt",
    "prepare": "husky"
  },

The toolchain is modern and pinned: oxlint and oxfmt for linting and formatting, oxlint-tsgolint for TypeScript aware linting, husky for the git hooks, and changesets for versioning, with a `cliff.toml` in the root for the changelog. The `engines` block asks for Node `>=24.x` and pnpm `>=10.x`, and `packageManager` pins pnpm 10.19.0, so the Node version requirement is the first thing to check against a corporate laptop.

The registry and the MCP server are the two distribution paths

There are two ways for a codemod to leave your machine, and they serve different audiences.

The first is the Codemod Registry, which is where codemods are shared and discovered. The commands are `npx codemod publish` and `npx codemod search`, and a published codemod is run by its registry name, as in `npx codemod @codemod/my-codemod`. The project describes published codemods as helping the whole community migrate faster, and the contributing section invites people to build codemods for framework upgrades, security patches or common refactoring patterns, with a workflows quickstart, a JSSG guide and a publishing guide linked from the README.

The second is the Codemod MCP, which provides AI tools for code analysis, AST manipulation and codemod creation in AI-powered IDEs. The `crates/mcp` crate and the `rmcp` dependency with its server feature are the Rust side of it. The point of an MCP server here is that an assistant can call the same analysis and transformation machinery the CLI uses, rather than editing files by hand.

Both paths sit on top of the same engine, and both are optional. The repository also carries an `AGENTS.md`, a `skills/` directory and a `.agents/` directory, which are the conventions for coding agents working in this codebase, along with `SECURITY.md`, `CODE_OF_CONDUCT.md` and a `CONTRIBUTOR_LICENSE_AGREEMENT.md`.

Where the CLI ends and the hosted platform starts

The boundary is worth drawing precisely, because it decides where a team can start and where it has to buy something.

The CLI covers a migration inside a repository: scaffold a project, write transforms, run them against the working tree, test them, and run the whole workflow in CI. That part is local and the repository contains it.

The Platform covers a campaign: coordinating changes across multiple repositories, tracking progress, dashboards, and authoring tools, with the CLI as the engine underneath. That part is hosted and is not in this repository, which means the CLI is the piece you can adopt on its own and the campaign tooling is the piece you cannot.

There is a second limit, and it is the one the interactive launcher makes visible. `npx codemod` without arguments needs a terminal, and in a script it prints next steps and exits with status `1`. A CI integration therefore has to call the specific subcommands, `init`, `workflow run`, `publish`, or a registry name, rather than the bare launcher. That is a small thing to discover and an annoying thing to discover late.

The alternative approach is worth naming, because it is what many teams do first: a single-purpose script that performs one transformation over the tree, in the style of the jscodeshift tooling the project lists among its own keywords and topics. That approach is faster to set up and it does one thing well. The difference in approach is that a workflow engine treats a migration as a sequence with a schedule, a matrix and checkpoints, and a transform library treats it as one function call, so the choice is really between a migration that can be reviewed as a document and one that is a diff you have to read in the pull request.

On the matching side there is a similar fork: regular expressions and text rewriting, which are fast and fragile, against AST pattern matching, which is slower to write and much harder to get wrong on a codebase you do not fully control.

Editorial conclusion

The Codemod CLI fits a team that wants its migration steps to live in a reviewed YAML file that CI can run, that wants its transforms written as AST patterns rather than regular expressions, and that wants to publish reusable transforms for other repositories. It is the wrong choice for a single one-off edit, where a one-shot script is faster, and for a team that needs progress tracking across many repositories and dashboards, because that is the hosted Platform's job rather than the CLI's. Before adopting it, read the workflows documentation for the YAML schema and the approval gate semantics, check the `engines` block in `package.json`, which asks for Node 24 or later and pnpm 10, and note that the engine crates publish under the name butterflow, so a pin on `codemod-cli` does not pin the whole stack.

Frequently asked questions

Official sources

1. codemod/codemod on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases