codemap_group_add

Create or update a code group with members. Groups organize files, directories, and symbols. The description becomes the initial group notation.

groupsorganizationcategorization

Parameters

Name	Type	Required	Description
`name`	`string`	✅ Required	Group name
`description`	`string`	✅ Required	Group description (this becomes the initial notation/comment for the group)
`members`	`array`	✅ Required	Array of relative paths to files, directories, or symbol references (file.ts$symbolName)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_group_add",
  "arguments": {
    "name": "auth-system",
    "description": "Authentication and authorization system components",
    "members": [
      "src/auth/login.ts",
      "src/auth/register.ts",
      "src/middleware/auth.ts",
      "src/models/User.ts"
    ]
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "group": {
      "name": "auth-system",
      "description": "Authentication and authorization module - handles login, JWT tokens, and permissions",
      "memberCount": 5,
      "notationCount": 1,
      "members": [
        {
          "type": "file",
          "path": "src/auth/login.ts"
        },
        {
          "type": "file",
          "path": "src/auth/jwt-handler.ts"
        },
        {
          "type": "file",
          "path": "src/auth/permissions.ts"
        },
        {
          "type": "symbol",
          "path": "src/middleware/auth.ts$authMiddleware"
        },
        {
          "type": "directory",
          "path": "src/auth/validators"
        }
      ],
      "notations": [
        {
          "text": "Authentication and authorization module - handles login, JWT tokens, and permissions",
          "timestamp": 1704067200000,
          "date": "2024-01-01T00:00:00.000Z"
        }
      ],
      "createdAt": 1704067200000,
      "updatedAt": 1704067200000
    },
    "message": "Created group \"auth-system\" with 5 member(s)"
  }
}

ℹ️When to Use This Tool

codemap_group_add

Organize related files into logical collections (features, modules, layers)
Create architectural groups (API layer, Service layer, Components, etc.)
Group files for multi-file refactoring or analysis
Track feature boundaries across multiple files and directories
Document code organization patterns
Build reusable code collections for macros and routines

💡Common Patterns

Feature-Based Grouping

Create group for new authentication feature:
1. Call codemap_group_add({
  name: "auth-feature",
  description: "User authentication and authorization",
  members: ["src/auth/*.ts", "src/middleware/auth.ts", "src/models/User.ts"]
})
2. Group persists in .codemap/groups.json
3. Use group name in routines and search filters

Architecture Layer Organization

Group files by architectural layer:
1. API layer: codemap_group_add("api-layer", "REST API routes and controllers", ["src/api/**/*"])
2. Service layer: codemap_group_add("service-layer", "Business logic services", ["src/services/**/*"])
3. Data layer: codemap_group_add("data-layer", "Database models and queries", ["src/models/**/*", "src/db/**/*"])

Symbol-Level Grouping

Group specific functions across multiple files:
codemap_group_add({
  name: "validation-functions",
  description: "All validation utility functions",
  members: [
    "src/utils/validators.ts$validateEmail",
    "src/utils/validators.ts$validatePhone",
    "src/auth/validators.ts$validatePassword"
  ]
})

💡Pro Tips

Use descriptive group names: Choose names that clearly indicate the group's purpose (e.g., "payment-processing" instead of "group1")
Description becomes first notation: The description you provide automatically becomes the group's first notation, so make it informative
Mix member types freely: Groups can contain files, directories, and symbol references all together
Glob patterns work: Use wildcards like src/auth/*.ts or **/*.test.ts to include multiple files
Groups are idempotent: Calling codemap_group_add with the same name updates the existing group rather than creating a duplicate
Groups persist across sessions: Stored in .codemap/groups.json, groups survive reboots and are version-controlled

✅Best Practices

Start with broad groups (features, modules) then create focused subgroups as needed
Use groups as building blocks for routines - group files first, then reference groups in routine workflows
Add notations to groups (via codemap_group_notate) as you learn more about the code organization
Keep group names consistent with your team's naming conventions
Include both source files and test files in feature groups for complete context
Use directory members for large subsystems, file members for specific implementations

⚠️Common Mistakes

❌ Mistake: Creating groups with empty descriptions

codemap_group_add({ name: "stuff", description: "", members: [...] })

✅ Instead: Use meaningful descriptions that explain the group's purpose

codemap_group_add({ 
  name: "payment-gateway", 
  description: "Stripe integration for payment processing",
  members: [...] 
})

---

❌ Mistake: Using absolute paths instead of relative paths

codemap_group_add({ 
  name: "api",
  members: ["C:\\Projects\\myapp\\src\\api\\routes.ts"]
})

✅ Instead: Use relative paths from project root

codemap_group_add({ 
  name: "api",
  members: ["src/api/routes.ts"]
})

---

❌ Mistake: Creating groups with single files

codemap_group_add({ name: "utils", members: ["src/utils.ts"] })

✅ Instead: Groups should represent collections - use labels for single files

// For single files, use labels instead:
codemap_label_assign({ labelId: "utility", target: "src/utils.ts" })

// For groups, include multiple related items:
codemap_group_add({ 
  name: "utilities",
  members: ["src/utils/*.ts", "src/helpers/*.ts"]
})

---

❌ Mistake: Not using symbol references for cross-cutting concerns

// Grouping entire files when only specific functions are relevant
codemap_group_add({ 
  name: "error-handlers",
  members: ["src/api/users.ts", "src/api/products.ts"] 
})

✅ Instead: Use symbol references to group specific functions

codemap_group_add({ 
  name: "error-handlers",
  members: [
    "src/api/users.ts$handleUserError",
    "src/api/products.ts$handleProductError"
  ]
})

---

❌ Mistake: Forgetting that groups update rather than create duplicates

// Assuming this creates a new group each time
codemap_group_add({ name: "api", members: ["src/new-file.ts"] })

✅ Instead: Understand that calling with same name updates the group

// First call creates the group
codemap_group_add({ name: "api", members: ["src/routes.ts"] })

// Second call UPDATES the group (replaces members)
codemap_group_add({ name: "api", members: ["src/routes.ts", "src/new-file.ts"] })

// To add members without replacing, get current members first
const group = await codemap_group_search({ name: "api" });
const updatedMembers = [...group.data.group.members.map(m => m.path), "src/new-file.ts"];
codemap_group_add({ name: "api", members: updatedMembers })