> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codemod.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Orchestrate automated code transformations at scale with Codemod Workflows.

**Codemod Workflows** is an execution engine that orchestrates automated code transformations at scale. It schedules, runs, and coordinates codemods across files, repositories, and teams.

## How workflows work

A workflow is defined in `workflow.yaml` and consists of **nodes** that execute in a dependency-aware order. Each node contains **steps**—atomic actions that perform transformations or run commands.

The engine handles:

* **Scheduling**: Determines execution order based on node dependencies
* **Parallelization**: Runs independent nodes concurrently via matrix strategies
* **State management**: Persists progress for resumable, interruptible migrations
* **Coordination**: Synchronizes work across shards, teams, or repositories

## Core concepts

### Nodes

Nodes are the primary execution units. They can depend on other nodes, run automatically or require manual approval, and fan out across matrix dimensions.

In Campaign/cloud runs, a node can also drive git automation: you can create a task branch before the node runs, create commits after successful steps, and open a pull request when the node finishes with commits. See [Workflow Reference](https://docs.codemod.com/community/workflows/reference.md#nodes).

### Steps

Steps are the atomic actions within a node. Different transformation challenges require different tools: some patterns are best expressed as AST queries, others need shell scripts for setup/teardown, and ambiguous cases may benefit from LLM assistance.

By composing multiple step types in a single workflow, teams can tackle complex refactors while decreasing reliance on manual intervention or multiple disconnected scripts.

| Step Type | Purpose |
| - | - |
| `js-ast-grep` | JavaScript/TypeScript codemods using [JSSG](https://docs.codemod.com/community/jssg) |
| `ast-grep` | Declarative YAML pattern matching |
| `run` | Shell commands for setup, cleanup, or external tools |
| `ai` | LLM-powered transformations for complex or ambiguous cases |
| `codemod` | Run codemods from [Codemod Registry](https://go.codemod.com/registry) |
| `install-skill` | Install an authored package skill into a supported coding-agent harness |
| `shard` | [Split migrations into multiple PRs](https://docs.codemod.com/community/workflows/sharding.md) by directory, codeowner, or custom logic |

### Matrix strategies

Matrix strategies fan out a single node into multiple parallel tasks. Use them for:

* Sharding work by team or directory
* Running transforms across multiple configurations
* Distributing load across repositories

### State

Workflows can declare shared state that persists across runs. This enables:

* Resuming interrupted migrations
* Coordinating work across repositories
* Tracking progress for large-scale refactors

### Parameters

Parameters make workflows configurable and reusable. Define a schema in your workflow, then pass values at runtime or configure them visually in the Codemod app.

## Package structure

A Codemod package bundles everything needed to run a workflow: metadata, workflow definition, transformation scripts, and test fixtures.

> [card] [Package Structure](https://docs.codemod.com/community/package-structure.md)
>
> Directory layout, codemod.yaml reference, and package metadata.

## Next steps

> [card] [Workflow Reference](https://docs.codemod.com/community/workflows/reference.md)
>
> Complete workflow\.yaml specification with all options.

> [card] [AI step](https://docs.codemod.com/community/workflows/ai-harness-rig.md)
>
> How the `ai` step runs under Codemod's Rig-based harness.

> [card] [Sharding](https://docs.codemod.com/community/workflows/sharding.md)
>
> Split migrations into multiple PRs by directory, codeowner, or custom logic.

> [card] [JSSG](https://docs.codemod.com/community/jssg)
>
> Write JavaScript/TypeScript transformations with ast-grep.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.