Smart Move Tool

Intelligently move files, functions, or modules across the codebase while automatically updating all imports, references, and dependent code.

When to Use This Command

Run this command when...

• You need to relocate files or directories and want all import paths updated automatically
• You are restructuring a project and moving modules between packages or directories
• A function or class needs to be extracted from one file and placed into another with reference updates
• You want to rename and relocate a component while preserving all existing usages
• You are splitting a monolith file into multiple smaller modules

Quick Start

Copy
# .claude/commands/smart-move-tool.md
---
name: Smart Move Tool
description: Move code elements with automatic reference updates
command: true
---
Move with full reference tracking: $ARGUMENTS

1. Identify source element and destination
2. Trace all references and imports
3. Execute the move
4. Update every affected file
5. Verify no broken references remain

Copy
# Invoke the command
claude "/smart-move-tool src/utils/format.ts to src/shared/formatters/"

# Expected output
# > Analyzing src/utils/format.ts...
# >   Exports: formatCurrency, formatDate, formatNumber (3 functions)
# >   Referenced by: 14 files across 4 directories
# > Moving to src/shared/formatters/format.ts...
# > Updating imports in 14 files...
# > Verifying: 0 broken references
# > Move complete: 1 moved, 14 updated

Core Concepts

Concept	Description
Reference Tracing	Maps every import, require, and dynamic reference before moving anything
Path Resolution	Calculates new relative and absolute import paths for all affected files
Re-export Bridge	Optionally leaves a re-export at the old location for gradual migration
Scope Detection	Identifies whether to move an entire file, specific exports, or a directory
Verification Pass	Post-move scan confirms zero broken imports or references

Smart Move Pipeline
====================

  Source --> Trace Refs --> Calculate Paths --> Execute Move
    |            |               |                   |
  Parse       Find all        Compute new         Move file
  exports     importers       relative paths      or extract
    |            |               |                   |
    +-----+------+------+-------+                   |
          |             |                           v
    Reference Map   Path Map             Update All Imports
                                               |
                                         Verify (0 broken)

Configuration

Parameter	Description	Default	Example	Required
$ARGUMENTS	Source and destination paths or description	none	"src/utils/auth.ts to src/auth/"	Yes
leave_reexport	Leave a re-export at the original location	false	true	No
scope	What to move: file, function, class, or directory	auto-detect	"function"	No
update_tests	Also update test file import paths	true	false	No
dry_run	Preview changes without executing	false	true	No

Best Practices

1. Use dry_run first on large moves -- Preview the impact before executing. A move touching 50+ files deserves a review of the planned path updates before committing.

2. Move one thing at a time -- Sequential moves are safer than bulk relocations. Each move can be verified independently and rolled back cleanly.

3. Consider re-exports for library code -- If external consumers depend on the old path, use leave_reexport: true to maintain backward compatibility during a migration period.

4. Run tests after every move -- Even with automated reference updates, edge cases like dynamic imports or string-based paths may not be caught. A test run confirms nothing broke.

5. Commit before moving -- Ensure your working tree is clean so you can git diff the move results and git checkout to revert if needed.

Common Issues

Dynamic imports not updated: Paths constructed with template literals or variables cannot be statically traced. Search for the old path string manually after the move to catch dynamic references.

Circular dependency introduced: Moving a module into a directory that already imports it can create circular imports. Check the dependency graph post-move and restructure if cycles appear.

Path alias mismatches: Projects using TypeScript path aliases (@/utils) or webpack aliases need alias-aware path resolution. Ensure tsconfig.json paths are considered during the move.