Command Relationships

High-Level Commands (Production)

# Run a published package from the registry
npx codemod @org/my-package

# Run a local workflow package
npx codemod workflow run -w ./my-package/

Quick Testing Commands (Development)

# Test a jssg transform directly
npx codemod jssg run ./transform.ts ./src --language tsx

# Test jssg transform with fixtures
npx codemod jssg test ./transform.ts --language tsx

Package Lifecycle

# Scaffold a new package
npx codemod init

# Validate workflow
npx codemod workflow validate -w workflow.yaml

# Publish to registry
npx codemod publish

Telemetry

CLI Command Reference

codemod ai

npx codemod ai [--harness <claude|goose|opencode|cursor|codex|auto>] [--project|--user] [--force] [--no-interactive] [--update-policy <manual|notify|auto-safe>] [--update-source <local|registry|URL>] [--require-signed-manifest|--allow-unsigned-manifest] [--format <logs|table|json|yaml>]

{
  "mcpServers": {
    "codemod": {
      "command": "npx",
      "args": ["-y", "codemod@<installing CLI version>", "mcp"]
    }
  }
}

• The project MCP launcher needs Node.js and npm (npx) on every machine that uses the committed config. The first launch of a pinned version downloads it from the npm registry unless it is already in the npm cache.
• If npm is not available, use --user with an installed codemod executable instead.
• The Claude periodic update hook runs a POSIX shell script. Claude Code runs hook commands with sh on macOS and Linux and with Git Bash on Windows, so Windows machines need Git for Windows; the hook does not run under PowerShell.

• claude: ./.mcp.json (project), ~/.claude.json (user, the same file claude mcp add -s user writes; other keys in it are kept)
• goose: ./.goose/mcp.json (project), ~/.config/goose/mcp.json (user)
• opencode: ./opencode.json (project), ~/.config/opencode/opencode.json (user)
• cursor: ./.cursor/mcp.json (project), ~/.cursor/mcp.json (user)
• codex (CLI + macOS app): ./.codex/config.toml (project), ~/.codex/config.toml (user) under [mcp_servers.codemod]

• claude: CLAUDE.md
• goose: AGENTS.md and .goosehints
• cursor: AGENTS.md
• opencode: AGENTS.md
• codex: AGENTS.md ai also installs /codemod where the harness has a native command or workflow file surface:
• claude: ./.claude/commands/codemod.md (project), ~/.claude/commands/codemod.md (user)
• goose: ~/.config/goose/recipes/codemod.yaml + ~/.config/goose/config.yaml registration (user only)
• opencode: ./.opencode/commands/codemod.md (project), ~/.config/opencode/commands/codemod.md (user)
• cursor: ./.cursor/commands/codemod.md (project), ~/.cursor/commands/codemod.md (user) The installed /codemod command routes by intent:
• create, scaffold, or refine codemods -> codemod authoring flow
• search, run, or apply existing codemods -> registry discovery and execution flow

• SKILL.md: the main skill instructions and Codemod-specific authoring and execution defaults
• agents/openai.yaml: the Codemod agent interface definition used by compatible harnesses
• commands/codemod.md: the /codemod command routing rules for harnesses with a native command surface

• npx codemod ai docs: list docs resources exposed through the CLI
• npx codemod ai docs <resource-id>: read a specific docs resource such as codemod-cli, codemod-creation-workflow, or codemod-troubleshooting
• npx codemod ai dump-ast <file> or npx codemod ai dump-ast --: inspect AST shape for a file or stdin
• npx codemod ai node-types <language>: inspect tree-sitter node kinds for a language
• npx codemod ai call validate_codemod_package --input '{"package_path":"."}': validate whether a codemod package still contains starter scaffold markers or other package-surface issues
• npx codemod ai feedback --category <category> --message <message>: submit short anonymous platform feedback after consent is recorded

• claude: hooks.SessionStart command in ./.claude/settings.json (project) or ~/.claude/settings.json (user). The project hook runs "$CLAUDE_PROJECT_DIR"/.claude/codemod/periodic-update/check-updates.sh, so it keeps working after the project is cloned or moved. Re-running ai replaces a project hook that an earlier install wrote with an absolute runner path, including one written from a different checkout. Only unmodified generated hooks with an unambiguous absolute runner command are migrated automatically. Commands containing whitespace (including old unquoted paths with spaces), quoting, arguments or shell syntax are preserved, as are hooks with custom matchers, timeouts or other fields. Review and remove obsolete preserved hooks manually when moving a checkout; install adds the portable hook without deleting those commands.
• cursor: hooks.afterAgentResponse command in ./.cursor/hooks.json (project) or ~/.cursor/hooks.json (user)
• opencode: plugin codemod-periodic-update.js in ./.opencode/plugins/ (project) or ~/.config/opencode/plugins/ (user), listening to session.idle
• goose: managed codemod-periodic-update block in ./.goosehints (project) or ~/.config/goose/.goosehints (user) as fallback guidance
• codex: notify = ["sh", "<runner>"] in ./.codex/config.toml (project) or ~/.codex/config.toml (user) Managed update policy is install-flag driven and shared by install-time reconciliation and periodic checks:
• --update-policy <manual|notify|auto-safe> (default: auto-safe)
• --update-source <local|registry|URL> (default: registry)
• --require-signed-manifest or --allow-unsigned-manifest (optional override) --update-source only accepts local, registry, or an absolute http(s) URL (legacy registry:/url: aliases are rejected). Project periodic runners use the same pinned npx -y codemod@<installing CLI version> launcher as project MCP, even when another global CLI version is installed. User runners retain their local executable/PATH fallback. Periodic runs enforce signed manifest verification via --require-signed-manifest in the generated runner command. After install, restart or reload your harness session so newly installed skills and command entrypoints are picked up.

npx codemod ai feedback --category <category> --message <message>

npx codemod ai feedback --category jssg --message "I wish JSSG had clearer examples for multi-file transforms."
npx codemod ai feedback --category ai-docs --message "The docs resource for runtime capabilities should explain which Node APIs are unavailable."

npx codemod ai update [--harness <claude|goose|opencode|cursor|codex|auto>] [--project|--user] [--force] [--no-interactive] [--update-policy <manual|notify|auto-safe>] [--update-source <local|registry|URL>] [--require-signed-manifest|--allow-unsigned-manifest] [--format <logs|table|json|yaml>]

npx codemod ai list [--harness <claude|goose|opencode|cursor|codex|auto>] [--format <logs|table|json|yaml>]

npx codemod ai dump-ast [FILE] [--language <language>] [--json]

• Omit FILE or pass - to read from stdin.
• If you do not pass --language, the CLI infers it from the file extension when possible and otherwise defaults to tsx for stdin.

# Parse a file and print AST text
npx codemod ai dump-ast ./src/component.tsx

# Parse stdin as TypeScript and emit JSON
cat ./src/index.ts | npx codemod ai dump-ast - --language typescript --json

npx codemod ai node-types <language> [--json]

npx codemod ai node-types tsx
npx codemod ai node-types python --json

npx codemod ai docs [query...] [--json]

• Run without a query to list available docs-backed resources.
• Pass a resource name or URI to read it.
• Pass a search phrase to search across available resources.

# List available docs resources
npx codemod ai docs

# Read one resource by name
npx codemod ai docs codemod-cli-instructions

# Search across docs-backed resources
npx codemod ai docs semantic analysis

npx codemod ai tools [--json]
npx codemod ai tool <name> [--json]

• ai tools lists available tool names and descriptions.
• ai tool <name> prints metadata and the JSON input schema for a single tool.

npx codemod ai call <name> [--input <JSON|@path|- >]

• Omit --input to pass an empty object ({}).
• Use --input @request.json to load input from a file.
• Use --input - to read JSON input from stdin.

npx codemod ai call dump_ast --input '{"language":"tsx","source":"const x = 1;"}'

npx codemod ai resources [--json]
npx codemod ai resource <uri-or-name> [--json]

• ai resources lists the available resource names and URIs.
• ai resource reads one resource by URI or resource name.

Package skill install (prompted from package run)

npx codemod <package-id>

{
  "ok": false,
  "code": "E_SKILL_PACKAGE_NOT_FOUND",
  "exit_code": 27,
  "message": "Unknown skill package id: jest-to-vitestx",
  "hint": "Run `codemod search <migration> --format json` to locate a valid package id."
}

codemod workflow

• ✅ Production codemods with multiple steps
• ✅ Parameterized transformations
• ✅ Multi-repo orchestration
• ✅ State management and resumption

• Use npx codemod workflow run -w <path> for local Codemod packages and directories
• Use npx codemod <package-name> to run packages directly from the Codemod Registry

npx codemod workflow run -w <workflow.yaml|directory>

npx codemod <package-name>

# Specify a target directory
npx codemod workflow run -w ./my-codemod -t /abs/path/to/repo

# Specify a target directory
npx codemod @codemod/my-test-pkg -t /abs/path/to/repo

# Single parameter:
npx codemod workflow run -w workflow.yaml --param format=cjs

# Multiple parameters:
npx codemod workflow run -w workflow.yaml --param format=cjs --param strict=true

npx codemod workflow run -w workflow.yaml --no-interactive --install-skill
npx codemod <package-name> --no-interactive --install-skill

# Run a named workflow defined in the package's codemod.yaml
npx codemod workflow run -w ./my-codemod --workflow-name sharded

# Capture nested LLM usage while running a registry package
npx codemod @org/my-package --llm-usage-output ./artifacts/llm-usage.json

# Capture nested LLM usage for a local package run
npx codemod workflow run -w ./my-codemod --llm-usage-output ./artifacts/llm-usage.json

npx codemod workflow resume -i <ID> [-t <TASK>] [--trigger-all]

npx codemod workflow resume -w workflow.yaml -i <ID> --trigger-all --no-interactive --install-skill

npx codemod workflow validate -w <workflow.yaml>

• Workflow-only package: validates workflow behavior.
• Skill-only package: validates workflow install-skill behavior plus authored skill layout (agents/skill/<skill-name>/...).
• Workflow + skill package: validates both executable workflow and authored skill behavior.

npx codemod workflow status -i <ID>

npx codemod workflow list [-l <LIMIT>]

npx codemod workflow cancel -i <ID>

codemod jssg

• ✅ Quick testing of a single transform
• ✅ Iterating on pattern matching
• ✅ Development and debugging

• ❌ Multi-step transformations → use codemod workflow
• ❌ Parameterized transforms → use codemod workflow with --param
• ❌ Production deployments → use codemod workflow for orchestration

npx codemod jssg run my-codemod.js ./src --language javascript

npx codemod jssg test my-codemod.js --language javascript

npx codemod jssg run <codemod_file> <target_directory> [options]

npx codemod jssg test <codemod_file> [options]

codemod init

npx codemod init [PATH] [options]

• Single codemod repo: Triggers on v* tags (e.g., v1.0.0)
• Monorepo: Triggers on *@v* tags (e.g., my-codemod@v1.0.0) and extracts the codemod name

codemod login

npx codemod login [--api-key <API_KEY>] [--registry <REGISTRY>] [--scope <SCOPE>]

codemod logout

npx codemod logout [--registry <REGISTRY>] [--all]

codemod whoami

npx codemod whoami [--registry <REGISTRY>] [--detailed]

codemod publish

npx codemod publish [PATH]

codemod unpublish

npx codemod unpublish <PACKAGE> [options]

# Preview removal of a single version
npx codemod unpublish my-codemod --version 0.1.0 --dry-run

# Remove a single version (will prompt)
npx codemod unpublish my-codemod --version 0.1.0

# Remove all versions (will prompt)
npx codemod unpublish my-codemod --force

# Unpublish from a custom registry
npx codemod unpublish my-codemod --force --registry https://registry.example.com

codemod search

npx codemod search [OPTIONS] [QUERY]

npx codemod search react

npx codemod search --language typescript --category migration

npx codemod search --format json next

codemod cache

npx codemod cache info

npx codemod cache list [--detailed]

npx codemod cache clear [PACKAGE] [--all]

npx codemod cache prune [--max-age <MAX_AGE>] [--dry-run]