codemap_delete

Delete a file, directory, or an entire symbol from a file. Use symbol targeting (relativePath$symbolName) to surgically remove a function or class without touching the rest of the file.

iowritedeleteremovecleanupsymbol-targeting

Parameters

Name	Type	Required	Description
`target`	`string`	✅ Required	Relative path to the file or directory, or symbol reference (relativePath$symbolName) to delete that symbol from the file
`recursive`	`boolean`	❌ Optional	Allow recursive directory deletion. Required for non-empty directories. Default: false (default: `false`)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_delete",
  "arguments": {
    "target": "src/deprecated/old-utils.ts"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "deleted": "/home/user/project/build/old-version",
    "type": "directory",
    "recursive": true
  }
}

ℹ️When to Use This Tool

codemap_delete

Remove deprecated code files or modules that are no longer needed
Clean up build artifacts, temporary files, and cache directories
Delete generated files before regenerating them (build outputs, API schemas)
Remove test fixtures or mock data after test completion
Clean up old branches' orphaned files during project reorganization

💡Common Patterns

Safe Deletion Workflow

1. Verify target: {"name": "codemap_peek", "arguments": {"path": target}}
2. Check if in use: {"name": "codemap_search_in_files", "arguments": {"query": target}}
3. Backup if important: copy to backups/ directory
4. Delete: {"name": "codemap_delete", "arguments": {"path": target, "recursive": true}}
5. Verify removal: confirm path no longer exists
6. Reindex: call codemap_reindex() to update graph

Always verify before deleting, especially with recursive: true.

Build Cleanup Pattern

1. List build directories: ['build', 'dist', '.cache']
2. For each directory: try delete with recursive: true
3. Ignore ENOENT errors (already deleted)
4. Log results: files deleted, space freed
5. Continue on errors to clean what you can

Robust for CI/CD pipelines where builds may not exist.

Conditional Deletion

1. Check file age: stat({ path })
2. If older than threshold: mark for deletion
3. Batch delete marked files
4. Report: deleted count, space freed

Useful for time-based cleanup (logs older than 7 days).

💡Pro Tips

Always use recursive: true for directories with contents: Attempting to delete a non-empty directory without this flag will fail. The error message will remind you, but plan ahead.
Backup critical files before deletion: Even if you're certain, create a backup first for anything that's not easily regenerated. Use timestamped backup directories like backups/2026-04-07-component/.
Check references before deleting source files: Run search_in_files to find imports or references. Deleting a file that's imported elsewhere will break your build.
Use peek() to preview impact: Before recursive deletion, call peek() to see how many files and directories will be removed. The response includes fileCount and totalSize.
Ignore ENOENT gracefully: In cleanup scripts, wrap delete calls in try/catch and ignore "file not found" errors. If it's already gone, that's success.

✅Best Practices

Never delete files without checking if they're under version control first - use git status
For directories, always explicitly set recursive: true or recursive: false - be intentional
After deleting source files, run codemap_reindex() to update the code graph
Log deletion operations in production systems - capture what was deleted, when, and why
Test deletion logic in a sandbox or with dry-run mode before running on real data
Keep backups of deleted files for at least 30 days in automated cleanup scripts

⚠️Common Mistakes

❌ Mistake: Deleting a directory without recursive: true, causing the operation to fail
✅ Instead: Always specify recursive: true when deleting directories with contents. Make it explicit in your code.

❌ Mistake: Not checking if files are referenced elsewhere before deletion
✅ Instead: Run codemap_search_in_files() to find imports and references. Fix or remove those first.

❌ Mistake: Deleting files without backing them up first, then realizing you needed them
✅ Instead: Copy to a timestamped backup directory before deletion. Disk space is cheap, rebuilding work is expensive.

❌ Mistake: Using hardcoded absolute paths in deletion scripts, breaking portability
✅ Instead: Use relative paths from project root. Let CodeMap resolve them. Scripts work anywhere.

❌ Mistake: Stopping entire cleanup workflow if one deletion fails
✅ Instead: Wrap each delete in try/catch, log failures, continue processing. Clean up what you can.

❌ Mistake: Forgetting to reindex after deleting source files, leaving stale symbols in code graph
✅ Instead: Call codemap_reindex() after deletions that affect source code. Keep graph accurate.

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_create

codemap_io_write

codemap_io_list

codemap_io_rename

codemap_backup_rollback