codemap_rename
Rename or move a file.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
target | string | ✅ Required | Current file path (relative or absolute) |
newPath | string | ✅ Required | New file path (relative or absolute) |
Usage Examples
MCP Usage (for AI Agents like Claude)
json
{
"name": "codemap_rename",
"arguments": {
"target": "src/utils/helper.ts",
"newPath": "src/utils/helpers.ts"
}
}Example Output
JSON Response
json
{
"success": true,
"data": {
"from": "P:\\Workspace\\my-project\\src\\utils\\helper.ts",
"to": "P:\\Workspace\\my-project\\src\\utils\\utilities.ts"
}
}When to Use This Tool
-
Use
- Rename files to follow naming conventions (PascalCase, camelCase, kebab-case)
- Move files to reorganize project structure
- Refactor module names while preserving file history
- Migrate files between directories during project reorganization
- Update file extensions (e.g., .jsx to .tsx, .js to .ts)
codemap_rename when you need to:
Common Patterns
Rename-Then-Update-References Pattern
Critical for maintaining working code after renames.
Safe Reorganization Pattern
Prevents data loss and conflicts.
Batch Rename with Rollback
Ensures atomic batch operations.
1. Rename file: {"name": "codemap_rename", "arguments": {"target": old, "newPath": new}}
2. Search for importers: {"name": "codemap_search", "arguments": {"query": old}}
3. Update import paths in each file
4. Reindex: call codemap_reindex()
5. Test build to verifyCritical for maintaining working code after renames.
Safe Reorganization Pattern
1. Check source exists: {"name": "codemap_peek", "arguments": {"target": target}}
2. Check destination doesn't exist
3. Rename: {"name": "codemap_rename", "arguments": {"target": target, "newPath": newPath}}
4. Verify: confirm newPath exists
5. Track rename for potential rollbackPrevents data loss and conflicts.
Batch Rename with Rollback
1. Build list of renames
2. Track each successful rename
3. If any fails: rollback in reverse order
4. Report success or failureEnsures atomic batch operations.
Pro Tips
- Always update import statements after renaming: Files that import the renamed file will break. Search for imports and update them before committing changes.
- Rename is also move: There's no separate move operation - rename handles both. To move a file, specify a newPath in a different directory.
- Check for existing destination: Rename fails if newPath already exists. Always verify the destination is available before renaming.
- Reindex after structural changes: When renaming source files, call
codemap_reindex()to update the code graph with new paths and symbols. - Use relative paths consistently: Mixing relative and absolute paths can cause confusion. Stick to one style for clarity.
Best Practices
- Always search for import references before renaming source files
- After renaming, run
codemap_reindex()to update the code graph immediately - For batch renames, implement rollback capability in case of errors
- Test your build after renaming to catch broken imports
- Track renames in version control with clear commit messages
- When reorganizing directories, rename files in a logical order (deepest first)
Common Mistakes
❌ Mistake: Renaming a file without updating imports, breaking the build
✅ Instead: Search for all imports first (
❌ Mistake: Not checking if destination path already exists, causing rename to fail
✅ Instead: Use
❌ Mistake: Forgetting to reindex after renaming source files, leaving code graph stale
✅ Instead: Always call
❌ Mistake: Using absolute paths inconsistently, making renames non-portable
✅ Instead: Use relative paths from project root consistently for better portability
❌ Mistake: Renaming multiple related files without a rollback plan, leaving project in broken state
✅ Instead: Track successful renames and implement rollback logic for batch operations
❌ Mistake: Not testing the build after file renames, discovering errors later
✅ Instead: Run build/test immediately after renaming to catch broken references early
✅ Instead: Search for all imports first (
codemap_search), rename the file, then update all import statements❌ Mistake: Not checking if destination path already exists, causing rename to fail
✅ Instead: Use
codemap_peek() or check file existence before attempting rename❌ Mistake: Forgetting to reindex after renaming source files, leaving code graph stale
✅ Instead: Always call
codemap_reindex() after renaming files that contain code symbols❌ Mistake: Using absolute paths inconsistently, making renames non-portable
✅ Instead: Use relative paths from project root consistently for better portability
❌ Mistake: Renaming multiple related files without a rollback plan, leaving project in broken state
✅ Instead: Track successful renames and implement rollback logic for batch operations
❌ Mistake: Not testing the build after file renames, discovering errors later
✅ Instead: Run build/test immediately after renaming to catch broken references early