codemap_copy

Copy a file or directory to a new location, preserving the original

file-operationscopybackupduplicate

Parameters

Name	Type	Required	Description
`source`	`string`	✅ Required	Source file or directory path
`destination`	`string`	✅ Required	Destination file or directory path
`recursive`	`boolean`	❌ Optional	Copy directory contents recursively (required for directories)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_copy",
  "arguments": {
    "source": "src/utils/validator.ts",
    "destination": "src/utils/validator-backup.ts"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "message": "Directory copied successfully",
  "source": "src/features/authentication",
  "destination": "src/features/auth-v2",
  "filescopied": 12,
  "timestamp": "2026-04-11T14:30:45.123Z"
}

ℹ️When to Use This Tool

codemap_copy

Create a backup of a file or directory before making risky changes
Duplicate a template or boilerplate for reuse in another location
Archive a working version of code before refactoring
Create multiple variants of a configuration file for different environments
Preserve original files while experimenting with modifications

💡Common Patterns

Safe Edit Pattern

1. codemap_copy({ source: 'file.ts', destination: 'file.ts.bak' })
2. Edit file.ts with your changes
3. Test the changes
4. If successful: delete backup; If failed: copy backup back

Use this pattern when making risky edits to critical files. Always create a backup first.

Template Instantiation Pattern

1. codemap_copy({ source: 'templates/component.tsx', destination: 'src/NewComponent.tsx' })
2. codemap_replace_text to customize placeholders
3. Modify as needed for specific use case

Perfect for scaffolding new files from templates while keeping the template intact.

Directory Migration Pattern

1. codemap_copy({ source: 'src/old-structure', destination: 'src/new-structure', recursive: true })
2. Update import paths in new structure
3. Test thoroughly
4. Delete old structure when confident

💡Pro Tips

Use descriptive backup names: Instead of .bak, use .backup.{date} or .pre-{change-description} for better organization
Combine with file history: Even with copy creating backups, CodeMap's automatic file history provides an additional safety net
Directory copies are deep: When copying directories with recursive: true, all subdirectories and files are copied, maintaining the entire structure
Check destination first: Use codemap_list to verify the destination doesn't exist if you want to avoid conflicts
Template workflows: Copy is perfect for template systems - copy the template, then use replace_text or replace_many to customize

✅Best Practices

Always use recursive: true when copying directories - it's required and prevents accidental partial copies
Create backups before running batch operations or refactoring tools
Use consistent naming conventions for backups (.backup, .bak, .v1, etc.)
Document why backups were created using commit messages or project notes
Clean up old backups periodically to avoid clutter
Consider using templates stored in a dedicated templates/ directory for common file patterns

⚠️Common Mistakes

❌ Mistake: Forgetting recursive: true when copying directories
✅ Instead: Always include recursive: true for directory operations - CodeMap requires it to prevent accidental mistakes

❌ Mistake: Using generic backup names like file.bak for multiple versions
✅ Instead: Use descriptive names like config.pre-refactor.json or utils.2026-04-11.ts so you know what each backup contains

❌ Mistake: Copying entire large directories when you only need specific files
✅ Instead: Copy only the files you need, or use selective patterns. Large directory copies can be slow and waste disk space

❌ Mistake: Not verifying the copy succeeded before deleting the original
✅ Instead: Always check the response for success: true and verify the destination exists before removing the source

❌ Mistake: Copying files with sensitive data (API keys, passwords) to multiple locations
✅ Instead: Use environment variables or secure vaults for sensitive data instead of duplicating it in multiple config files

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_move

codemap_io_create

codemap_backup_list-history