codemap_label_delete
Delete a label definition. Cannot delete if assignments exist unless force=true.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | ✅ Required | Label ID to delete |
force | boolean | ❌ Optional | If true, unassign all before deleting (default: false) |
Usage Examples
MCP Usage (for AI Agents like Claude)
json
{
"name": "codemap_label_delete",
"arguments": {
"id": "lbl_deprecated_123456"
}
}Example Output
JSON Response
json
{
"success": true,
"message": "Label deleted successfully",
"deleted": {
"id": "lbl_experimental_847291",
"emoji": "🧪",
"name": "Experimental",
"description": "Experimental features under development",
"bgColor": "#9B59B6",
"fgColor": "#FFFFFF",
"createdAt": 1775428847291,
"assignmentCount": 0
},
"unassigned": 12
}When to Use This Tool
-
Use
- Clean up deprecated or unused labels from your label taxonomy
- Remove experimental labels that are no longer needed
- Consolidate duplicate or redundant label definitions
- Reset your labeling system after major project reorganization
- Delete temporary labels created for specific work sessions
codemap_label_delete when you need to:
Common Patterns
Safe Label Removal Workflow
This pattern prevents accidental data loss by ensuring you understand what will be unassigned.
Spring Cleaning Pattern
Use this quarterly to keep your label system clean and relevant.
Migration Before Deletion
This preserves your organizational work when retiring labels.
1. List all labels: codemap_label_list()
2. Check assignment count for target label
3. If assignmentCount > 0, review what's labeled
4. Decide: manually reassign or force delete
5. Delete label with appropriate force flag
6. Verify deletion with label listThis pattern prevents accidental data loss by ensuring you understand what will be unassigned.
Spring Cleaning Pattern
1. List all labels with assignment counts
2. Identify labels with assignmentCount === 0
3. Review each zero-assignment label for relevance
4. Delete all confirmed unused labels
5. Consider migrating assignments from deprecated labelsUse this quarterly to keep your label system clean and relevant.
Migration Before Deletion
1. Create new replacement label
2. Use codemap_label_migrate() to move assignments
3. Verify migration completed successfully
4. Delete old label (should have 0 assignments now)This preserves your organizational work when retiring labels.
Pro Tips
- Check assignment count first: Always run
codemap_label_list({ id: "lbl_id" })to see how many assignments exist before deleting. This prevents surprises. - Use force sparingly: The
forceflag is powerful but destructive. Only use it when you're certain you want to remove all assignments. For important labels, manually reassign first. - Document why you're deleting: Add a note to your session summary explaining which labels were deleted and why. Future you will appreciate the context.
- Batch deletions need transaction-like thinking: When deleting multiple labels, do it in a single session and document the changes. If something goes wrong, you can review the session to undo.
- Consider label migration instead: Before deleting a label with many assignments, ask if those entities should be relabeled rather than unlabeled. Use
codemap_label_migrate()to preserve organizational work.
Best Practices
- Always review assignment count before deletion - labels with 50+ assignments probably shouldn't be casually deleted
- Use descriptive label names that won't become confusing later (avoid "temp", "old", "new" without context)
- Keep a label naming convention document so you know when to retire labels vs create new ones
- Delete labels as part of project milestones (e.g., "After v2.0 release, delete all v1-* labels")
- When force deleting, capture the list of affected files in your session notes for audit purposes
Common Mistakes
❌ Mistake: Deleting a label without checking if it has assignments first
✅ Instead: Always run
❌ Mistake: Using
✅ Instead: Only use force when you've consciously decided that unassigning everything is the right action. Treat it as destructive.
❌ Mistake: Deleting labels one at a time in a cleanup session without tracking what was removed
✅ Instead: Make a list of labels to delete, document the plan in your session, then execute. Keep a record of what was cleaned up and why.
❌ Mistake: Deleting labels that are referenced in documentation or scripts
✅ Instead: Search your codebase for references to the label ID or name before deleting. Update docs and scripts first.
❌ Mistake: Creating new labels instead of reusing deleted ones, leading to ID proliferation
✅ Instead: Maintain a labels registry or convention guide. If you're about to recreate something similar, check if you recently deleted it and consider if deletion was premature.
✅ Instead: Always run
codemap_label_list({ id: "lbl_id", includeAssignments: true }) to see what will be affected❌ Mistake: Using
force: true by default to avoid "has assignments" errors✅ Instead: Only use force when you've consciously decided that unassigning everything is the right action. Treat it as destructive.
❌ Mistake: Deleting labels one at a time in a cleanup session without tracking what was removed
✅ Instead: Make a list of labels to delete, document the plan in your session, then execute. Keep a record of what was cleaned up and why.
❌ Mistake: Deleting labels that are referenced in documentation or scripts
✅ Instead: Search your codebase for references to the label ID or name before deleting. Update docs and scripts first.
❌ Mistake: Creating new labels instead of reusing deleted ones, leading to ID proliferation
✅ Instead: Maintain a labels registry or convention guide. If you're about to recreate something similar, check if you recently deleted it and consider if deletion was premature.