Codemod Documentation

Codemod provides a suite of tools for automating code migrations and framework upgrades:

• Codemod CLI: The primary interface for running, testing, and publishing codemods from your terminal or CI.
• Workflows: A system for orchestrating multi-step migrations using YAML configuration, supporting matrix strategies and manual approval gates.
• JSSG (JavaScript ast-grep): A tool for writing AST transformations in TypeScript using pattern matching and semantic analysis.
• Codemod Registry: A central hub to discover or share community codemods via npx codemod publish or npx codemod search.
• Codemod MCP: Model Context Protocol tools that enable AI-powered IDEs to perform code analysis, AST manipulation, and codemod creation.

The codemod-ai crate provides AI-powered code modification tools. It is built on top of rig-core and provides an AI execution runtime specifically designed for codemod workflows.

It includes several specialized tools that can be used within workflow ai steps to manipulate codebases and environments:

• bash: Execute shell commands.
• edit: Perform text-based edits.
• glob: Find files using glob patterns.
• json edit: Modify JSON files.
• code knowledge graph: Access and navigate the structural understanding of the code.

JavaScript ast-grep (JSSG) is the engine used by Codemod to run codemods within a sandboxed JavaScript runtime (QuickJS, with LLRT for Node-compatible builtins).

Instead of manually configuring Babel or Recast, you author TypeScript transforms against a specialized AST API provided by the codemod:ast-grep built-in. This built-in handles Tree-sitter parsing, pattern matching, and code edits.

Key characteristics:

• Sandboxed: Executes in a restricted environment for security.
• Tree-sitter based: Uses high-performance parsing and pattern matching.
• Small API: Focuses on direct tree manipulation (find, replace, text) rather than complex, loosely-typed chains.

Codemod Studio is a browser-based workspace designed for building and testing codemod workflows. It provides an environment to edit workflow files, test transformations against local fixtures, inspect AST (Abstract Syntax Tree) matches and diffs, and use Codemod AI to assist in development.

Studio is optimized for desktop use. Signing in allows you to:

• Save projects
• Share private or organization links
• Run workflows against connected repositories
• Package codemods as CLI commands
• Create pull requests directly from the workspace.

Codemod provides tools and infrastructure to automate large-scale code maintenance projects. It is designed to make repetitive tasks invisible to software teams by providing reliable, reusable, and enterprise-scale automations.

Common use cases include:

• Framework or library upgrades: Upgrading React, Node.js, etc.
• Compliance remediation: Automating GDPR, SOC 2, and policy adoption.
• Design system migrations: Migrating UI libraries like Radix or Tailwind.
• i18n: Automating the conversion of static strings to translation keys.
• Codebase sanitization: Unifying or sanitizing codebases after M&A or spin-offs.
• Dependency management: Auditing, updating, and standardizing dependencies at scale.

Butterflow is a lightweight, self-hostable workflow engine designed for large-scale code transformations. Key capabilities include:

• Execution Models: Supports local execution, parallel execution of nodes, matrix execution (dynamic inputs), and OCI container support.
• Durability: Features durable execution with diff-based state updates, resumable workflows, and backend-agnostic state management (local, API, or database).
• State Management: Uses a centralized, schema-validated Global Shared State that allows for dynamic task recompilation.
• Code Transformation Tools: Includes built-in AST grep support with automatic language extension inference and fix application, plus cycle detection for codemod dependencies.
• Flexibility: Supports reusable templates and multiple workflow sources (files, bundles, or registries).

Codemod is designed for two primary user groups:

1. Enterprise engineering teams: Platform engineers, security engineers, i18n engineers, or engineering leaders looking to automate large-scale migrations with confidence.
2. Open-source maintainers: Framework or library builders who want to provide an exceptional upgrade experience for their users.

The Codemod platform offers several key capabilities for managing code transformations and maintenance:

• Insights: Plan and track maintenance projects.
• Campaigns: Orchestrate migrations across multiple teams and repositories.
• Automations: React to events to start repeatable codebase maintenance.
• Registry: A central place to find public, private, or pro codemods.
• Studio: An environment to generate and test codemods with AI assistance.
• MCP (Model Context Protocol): Provides AI tools specifically for codemod creation.
• Codemod Wish: AI-powered assistance available across the platform.
• CLI: An open-source tool to scaffold or run codemods locally.

A codemod package is a portable unit of code transformation. It consists of:

• codemod.yaml: Metadata (name, version, target languages).
• workflow.yaml: Orchestration logic and execution steps.
• scripts/: JavaScript/TypeScript codemods using jssg.
• rules/: YAML-based ast-grep rule files.

Packages can be simple find-and-replace operations or complex multi-step workflows involving shell scripts and AI-assisted steps.

A Campaign is a centralized orchestration unit in the Codemod Platform used to run codemod packages across repositories.

Use Campaigns when you need:

• Centralized tracking of transformations.
• Multi-repo orchestration.
• Team collaboration and governance.
• Advanced features like manual task approval gates, state management across multiple runs, and matrix strategies for parallel execution.

Use the CLI instead of a Campaign when you want to perform local testing or a quick, one-off transformation without the overhead of platform orchestration.

Butterflow distinguishes between the definition of a process and its execution:

Each Workflow Run manages its own independent instance of the global shared state, including task statuses, resolved variables, and execution logs, tied to a unique run UUID.