codemap_add_annotation

Add a @codemap annotation to a file.

annotationswrite

Parameters

Name	Type	Required	Description
`path`	`string`	✅ Required	File path (relative or absolute)
`key`	`string`	✅ Required	Annotation key (e.g., 'author', 'version', 'status')
`value`	`string`	✅ Required	Annotation value

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_add_annotation",
  "arguments": {
    "path": "src/utils/helpers.ts",
    "key": "author",
    "value": "Jane Smith"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "path": "src/utils/helpers.ts",
  "key": "author",
  "value": "Jane Smith",
  "action": "added",
  "storage": "meta"
}

ℹ️When to Use This Tool

codemap_add_annotation

Track authorship and ownership - Record who created or maintains specific files
Document review status - Mark files as reviewed, approved, or pending
Version tracking - Associate version numbers or release dates with API files
Link to documentation - Attach URLs to external docs, wikis, or design specs
Priority and status flags - Label files as experimental, deprecated, high-priority, etc.
Technical debt markers - Note refactoring needs, optimization opportunities, or known issues
Dependency notes - Track upstream dependencies or breaking change impacts

💡Common Patterns

Workflow Tracking

// Mark files through development stages
await codemap.annotations.add({
  path: 'src/features/new-dashboard.ts',
  key: 'status',
  value: 'in-development'
});

// After code review
await codemap.annotations.add({
  path: 'src/features/new-dashboard.ts',
  key: 'reviewed',
  value: '2026-04-07'
});

// After testing
await codemap.annotations.add({
  path: 'src/features/new-dashboard.ts',
  key: 'tested',
  value: 'passed'
});

Team Ownership

// Assign team ownership for maintenance
const apiFiles = await codemap.search({ query: 'api/*.ts' });

for (const file of apiFiles.matches) {
  await codemap.annotations.add({
    path: file.path,
    key: 'team',
    value: 'backend-team'
  });
}

Documentation Links

// Link files to their documentation
await codemap.annotations.add({
  path: 'src/auth/OAuth2Provider.ts',
  key: 'docs',
  value: 'https://wiki.company.com/auth/oauth2'
});

await codemap.annotations.add({
  path: 'src/auth/OAuth2Provider.ts',
  key: 'spec',
  value: 'https://datatracker.ietf.org/doc/html/rfc6749'
});

Migration Tracking

// Track files that need migration to new API
await codemap.annotations.add({
  path: 'src/legacy/UserManager.ts',
  key: 'migrate-to',
  value: 'src/v2/UserService.ts'
});

await codemap.annotations.add({
  path: 'src/legacy/UserManager.ts',
  key: 'migration-priority',
  value: 'high'
});

💡Pro Tips

Use consistent key naming - Establish team conventions for annotation keys (e.g., reviewed, owner, status) to enable easy querying with codemap_search_annotations.

Combine with labels - Use annotations for detailed metadata and labels for visual categorization. Annotations store key-value pairs; labels provide emoji-tagged visual grouping.

Annotations persist across sessions - Unlike comments in code that might be overlooked, CodeMap annotations are indexed and queryable, making them excellent for team-wide metadata.

Leverage for code reviews - Add reviewer name and date as annotations to track review coverage across the codebase.

Version control friendly - Annotations are stored externally by default (storage: "meta"), so they don't create merge conflicts in source files.

Query by annotation - Use codemap_search_annotations to find all files with specific keys (e.g., all files marked status: experimental).

✅Best Practices

Use descriptive keys - Prefer reviewed-by over rb, migration-target over mt. Clear names make annotations self-documenting.

Store URLs as annotation values - Perfect for linking to PRs, tickets, documentation, or design specs.

Timestamp important events - Include dates in ISO format (YYYY-MM-DD) for reviewed, released, deprecated annotations to track timeline.

Don't duplicate source code metadata - Annotations complement code, not replace it. Don't annotate things already in comments or docstrings.

Clean up obsolete annotations - Use codemap_remove_annotation or codemap_edit_annotation to update outdated metadata.

Standardize team conventions - Document your team's annotation schema (approved keys and value formats) to ensure consistency.

⚠️Common Mistakes

❌ Mistake: Using annotations as TODO comments

await codemap.annotations.add({
  path: 'src/app.ts',
  key: 'todo',
  value: 'Refactor this mess'
});

✅ Instead: Use proper issue tracking systems for TODOs. Use annotations for factual metadata like status, owner, or version.

---

❌ Mistake: Storing complex JSON in value field

await codemap.annotations.add({
  path: 'src/config.ts',
  key: 'settings',
  value: '{"port":3000,"host":"localhost"}' // Hard to query
});

✅ Instead: Use separate annotations for each setting

await codemap.annotations.add({ path: 'src/config.ts', key: 'default-port', value: '3000' });
await codemap.annotations.add({ path: 'src/config.ts', key: 'default-host', value: 'localhost' });

---

❌ Mistake: Forgetting to update annotations when code changes

// File moved but annotation points to old path
await codemap.annotations.add({
  path: 'src/old-location/file.ts', // File is now at src/new-location/file.ts
  key: 'owner',
  value: 'team-a'
});

✅ Instead: Update annotations when refactoring. Use codemap_rename which preserves annotations across file moves.

---

❌ Mistake: Using annotations for data that changes frequently

// Anti-pattern: Annotation updated 100x per day
await codemap.annotations.add({
  path: 'src/cache.ts',
  key: 'last-request-count',
  value: '47283'
});

✅ Instead: Annotations are for stable metadata. Use logging, metrics systems, or runtime state management for frequently changing data.