codemap_label_list
List all labels with pagination. If ID provided, shows detailed view with assignments.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | ❌ Optional | Optional: specific label ID for detailed view |
includeAssignments | boolean | ❌ Optional | Include assignment details (default: false) |
page | number | ❌ Optional | Page number for pagination (default: 1) |
pageSize | number | ❌ Optional | Results per page (max: 100) (default: 20) |
Usage Examples
MCP Usage (for AI Agents like Claude)
json
{
"name": "codemap_label_list",
"arguments": {}
}Example Output
JSON Response
json
{
"labels": [
{
"id": "lbl_api_312956",
"emoji": "🔌",
"name": "API",
"description": "API endpoints and server routes",
"bgColor": "#4ECDC4",
"fgColor": "#FFFFFF",
"createdAt": 1775428312956,
"updatedAt": 1775428312956,
"assignmentCount": 5
},
{
"id": "lbl_components_317849",
"emoji": "🧩",
"name": "Components",
"description": "Reusable UI components",
"bgColor": "#95E1D3",
"fgColor": "#000000",
"createdAt": 1775428317849,
"updatedAt": 1775428317849,
"assignmentCount": 12
},
{
"id": "lbl_documentation_399133",
"emoji": "📚",
"name": "Documentation",
"description": "Documentation files and content",
"bgColor": "#F9C74F",
"fgColor": "#000000",
"createdAt": 1775428399133,
"updatedAt": 1775428399133,
"assignmentCount": 8
},
{
"id": "lbl_work_in_progress_241291",
"emoji": "⚙️",
"name": "Work In Progress",
"description": "Files currently being developed or modified",
"bgColor": "#4169E1",
"fgColor": "#FFFFFF",
"createdAt": 1775528241291,
"updatedAt": 1775528241291,
"assignmentCount": 3
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"totalLabels": 4,
"totalPages": 1
}
}When to Use This Tool
- Discover Available Labels: Before assigning labels, see what labels already exist in your project
- Audit Label Usage: Check which labels are actively used (assignment counts) and which are unused
- Detailed Label Information: Get complete details about a specific label including all its assignments
- Project Overview: Understand the organizational structure of your codebase through label distribution
Common Patterns
Quick Label Inventory
Start with a simple list to see all available labels:
This gives you a quick overview of all labels with their emoji identifiers and assignment counts.
Finding Unused Labels
Labels with zero assignments might be candidates for removal:
Label Audit Workflow
1. List all labels to see what exists
2. Check assignment counts to find popular vs unused labels
3. Use
4. Consider migrating or consolidating underused labels
Pagination for Large Projects
For projects with 20+ labels, use pagination:
Start with a simple list to see all available labels:
codemap_label_list()This gives you a quick overview of all labels with their emoji identifiers and assignment counts.
Finding Unused Labels
Labels with zero assignments might be candidates for removal:
const result = await codemap.labelStore.list();
const unusedLabels = result.labels.filter(label => label.assignmentCount === 0);Label Audit Workflow
1. List all labels to see what exists
2. Check assignment counts to find popular vs unused labels
3. Use
includeAssignments: true for labels you want to investigate further4. Consider migrating or consolidating underused labels
Pagination for Large Projects
For projects with 20+ labels, use pagination:
// Get first page
const page1 = await codemap.labelStore.list(undefined, 1, 20);
// Get specific page
const page2 = await codemap.labelStore.list(undefined, 2, 20);Pro Tips
-
Check Assignment Counts First
Before deleting a label, always check its assignment count. A label with assignments will fail to delete unless you use
- Use
listto see all available labels - Use
label_searchto find specific labeled entities
force: true.
Use Detailed View Sparingly
The includeAssignments: true option returns full assignment details, which can be verbose for heavily-used labels. Use it only when you need to see exactly what's labeled.
Label Discovery
When joining a project, run codemap_label_list() to understand the labeling conventions used by the team.
Performance Consideration
Listing labels is fast - the label store is optimized for quick retrieval. Don't hesitate to call this tool frequently.
Combine with Label Search
Common Mistakes
❌ Don't assume label IDs - Always list labels first to get the correct ID format
❌ Don't fetch assignments for all labels - Use
✅ Do check pagination - Look at
✅ Do cache results - Label definitions don't change often, safe to cache briefly in your application
❌ Don't fetch assignments for all labels - Use
includeAssignments only when needed✅ Do check pagination - Look at
totalPages to ensure you're not missing labels✅ Do cache results - Label definitions don't change often, safe to cache briefly in your application