Labels & Groups
Semantic organization for AI agents and developers
Beyond Directory Structure
Labels and groups provide persistent, semantic organization of your codebase beyond directory structure. They enable you to organize code by purpose, importance, status, or any other criteria that matters to your workflow.
Labels
Labels are tags with rich metadata that can be assigned to files, symbols, and other entities. Each label includes:
- Emoji - Visual identifier (e.g., đ for auth)
- Name - Human-readable name
- Description - What this label represents
- Colors - Optional background/text colors
Labels are perfect for marking architecture layers (API, Service, Database), tracking work status (In Progress, Needs Review), indicating importance (Critical, High Priority), or categorizing by tech stack.
Groups
Groups collect related files with a shared purpose. Unlike labels which mark individual files, groups create collections that represent features, modules, or subsystems.
Use groups for:
- Feature Modules - Group all files for a feature
- Refactoring Scope - Track all files affected by a change
- Architecture Layers - Organize by application tier
- Tech Stack - Group by framework or library
Use Cases
Labels and groups work together to create a multi-dimensional organization system:
- Label files as "API" while grouping them into "authentication-system"
- Mark files as "In Progress" while tracking them in a "v2.0-migration" group
- Tag components as "Critical" while organizing them by feature group
This flexible system lets you organize code in ways that match your mental model and workflow, not just the filesystem structure.
# Create a label
codemap label-create đ Authentication "User auth and authorization"
# Assign label to files
codemap label-assign lbl_auth_123 src/services/auth.ts src/middleware/auth.ts
# Search by label
codemap label-search lbl_auth_123# Create a group
codemap group-add payment-system "Payment processing components" \
src/services/payment.ts \
src/services/stripe.ts \
src/controllers/payment.ts
# Search groups
codemap group-search payment-systemUse labels to mark transient properties like work status or priority. Use groups to organize stable structural relationships like feature boundaries or architectural layers.
Labels and groups are designed for AI agents to understand and use. When an AI agent needs to find all authentication-related code, it can search by label rather than guessing file locations.
All labels and groups are stored in .codemap/ as JSON. Commit this directory so your entire team shares the same semantic organization.