refactor
Perform cross-file refactoring with automatic reference tracking, locating definitions and usage to apply consistent changes across scope. Ideal for renames, signature changes, and API migrations.
Instructions
Cross-file refactoring with automatic reference tracking. Locates where target is defined and where it's used, then applies the instruction consistently across the matched scope. Use for renames, signature changes, API migrations — any edit where consistency between definition and callers matters. scope bounds how wide the search goes: 'function' / 'class' / 'module' / 'project'. For the same blind edit across files without reference-awareness (cheaper), use batch_modify. For a single-file change, use modify_file. ⚠️ DESTRUCTIVE when review:false: writes to every file touched by the refactor. dryRun:true produces the plan without writing. Returns: shape depends on mode. review:true (default) or dryRun:true: {success, status:'pending_review'|'dry_run', scope, target, instructions, plan:{description, steps:[strings], filesAffected, estimatedChanges}, modifications:[{filePath, status:'pending_review'|'dry_run'|'error', summary, diff, stats, error?}], analysis:{occurrences, references, impact}, backend_used, processing_time, tokens_saved}. Auto-apply (review:false): {success, status:'completed'|'partial', scope, target, instructions, filesModified, filesTotal, modifications:[{filePath, status:'written'|'error', summary, error?}], backend_used, processing_time}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | How wide the reference search goes. `function` = the target function and its direct callers in the same module. `class` = the class definition, its methods, and call sites within the same module. `module` = the file containing `target` plus any file that imports from it. `project` = whole-repo search (slowest, most thorough). Pick the narrowest scope that covers your actual change. | |
| target | Yes | Symbol or pattern to refactor (e.g., "UserService", "handleLogin") | |
| options | No | ||
| instructions | Yes | Refactoring instructions (e.g., "Rename to AuthService and update all references") |