Agent-consumable CLI for applying Martin Fowler's catalog of refactorings to TypeScript codebases with guaranteed semantic preservation.
Designed to be called by AI coding agents (Claude Code, OpenCode, etc.) but works just as well from the command line.
Every refactoring is validated against 18 open-source TypeScript projects spanning classes, generics, decorators, functional composition, algebraic data types, and proxy patterns:
- Compile-and-test (12 repos): zod, date-fns, inversify, ts-pattern, superstruct, neverthrow, remeda, immer, true-myth, purify-ts, class-validator, class-transformer — each refactoring must compile cleanly and pass the project's own test suite on the changed files
- Compile-only (6 repos): typeorm, rxjs, fp-ts, io-ts, immutable-js, mobx — each refactoring must produce valid TypeScript
The test runner applies refactorings to real symbols in each repo, checks compilation with the project's own tsc, and for compile-and-test repos runs scoped tests (vitest --related / jest --findRelatedTests) to catch semantic-breaking changes. Failures are triaged into fixture tests that guard against regressions.
npm install -g refactoring-cliOr run without installing:
npx refactoring-cli list --jsonRequires Node.js >= 18.
# List all 66 available refactorings
refactor list
# Get details about a specific refactoring
refactor describe extract-variable
# Apply a refactoring (params are passed as key=value pairs)
refactor apply extract-variable file=src/app.ts target="x + 1" name=total
# Preview changes without writing to disk
refactor apply extract-variable file=src/app.ts target="x + 1" name=total --dry-run
# Target a project in a different directory
refactor --path /path/to/project apply inline-variable file=src/utils.ts target=temp| Command | Description |
|---|---|
refactor list |
List all available refactorings |
refactor describe <name> |
Show params, preconditions, and example for a refactoring |
refactor apply <name> [key=value...] |
Apply a refactoring to the target project |
refactor search <pattern> |
Search for symbols in the project |
refactor references <name> |
Find all references to a symbol |
refactor unused |
Find unused symbols in the project |
refactor fix-imports |
Detect and fix broken imports |
refactor help |
Show usage guide with examples |
All commands support --json for structured output and --path <dir> to target a different project directory.
The CLI finds your project by locating tsconfig.json. It searches upward from the current directory (or the directory given via --path) through parent directories until it finds one. The nearest tsconfig.json wins.
This means you can run refactor from any subdirectory of your project and it will find the root automatically.
Monorepo note: In monorepos with multiple tsconfig.json files (e.g., one per package), the CLI picks the nearest ancestor. If you need to target a specific package root, pass --path explicitly:
refactor --path packages/api apply extract-variable file=src/app.ts target="x + 1" name=totalYou can also point directly at a specific tsconfig with --config:
refactor --config tsconfig.lib.json apply ...66 refactorings organized across 4 tiers, covering variables, functions, conditionals, classes, and inheritance:
Full list
Variables: extract-variable, inline-variable, rename-variable, replace-temp-with-query, split-variable, replace-magic-literal, encapsulate-variable, encapsulate-record, encapsulate-collection, replace-primitive-with-object, change-reference-to-value, change-value-to-reference, replace-derived-variable-with-query, rename-field
Statements: slide-statements, remove-dead-code, introduce-assertion, replace-control-flag-with-break, substitute-algorithm
Functions: extract-function, inline-function, change-function-declaration, parameterize-function, remove-flag-argument, move-statements-into-function, move-statements-to-callers, replace-inline-code-with-function-call, combine-functions-into-transform, split-phase, split-loop, replace-loop-with-pipeline, separate-query-from-modifier, replace-parameter-with-query, replace-query-with-parameter, preserve-whole-object, introduce-parameter-object, remove-setting-method, replace-function-with-command, replace-command-with-function, return-modified-value, combine-functions-into-class, replace-error-code-with-exception, replace-exception-with-precheck, move-function
Conditionals: consolidate-conditional-expression, decompose-conditional, replace-nested-conditional-with-guard-clauses, replace-conditional-with-polymorphism, introduce-special-case
Classes: extract-class, inline-class, move-field, hide-delegate, remove-middle-man, extract-superclass, collapse-hierarchy, pull-up-method, pull-up-field, pull-up-constructor-body, push-down-method, push-down-field, remove-subclass, replace-subclass-with-delegate, replace-superclass-with-delegate, replace-constructor-with-factory-function, replace-type-code-with-subclasses
Add this to your project's CLAUDE.md, .opencode/instructions.md, or AGENTS.md:
## Refactoring with refactoring-cli
This project has `refactoring-cli` available globally. When performing refactorings,
prefer using the `refactor` CLI over manual AST edits.
### Workflow
1. `refactor search <pattern>` to find the symbol to refactor
2. `refactor describe <name>` to check params and preconditions
3. `refactor apply <name> file=<path> target=<name> [key=value...]` to apply
4. `refactor apply <name> ... --dry-run` to preview changes first
### Key commands
- `refactor list --json` — all available refactorings
- `refactor describe <name> --json` — params and preconditions for a refactoring
- `refactor apply <name> [params...] --json` — apply with structured output
- `refactor unused --json` — find dead code to clean up
- `refactor fix-imports --json` — fix broken imports after moves
### Project resolution
The CLI finds the project by walking up from `cwd` to the nearest `tsconfig.json`.
In a monorepo, pass `--path` to target the correct package:
`refactor --path packages/api apply ...`MIT