codemap_edit_annotation

Edit an existing @codemap annotation in a file.

annotationswriteedit

Parameters

Name	Type	Required	Description
`path`	`string`	✅ Required	File path (relative or absolute)
`key`	`string`	✅ Required	Annotation key to edit
`value`	`string`	✅ Required	New annotation value

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_edit_annotation",
  "arguments": {
    "path": "src/utils/helpers.ts",
    "key": "author",
    "value": "Sarah Johnson"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "path": "src/utils/helpers.ts",
  "key": "author",
  "value": "Sarah Johnson",
  "action": "edited",
  "storage": "meta"
}

ℹ️When to Use This Tool

codemap_edit_annotation

Update review status - Change status from 'in-review' to 'approved' after code review
Increment version numbers - Update version annotations when APIs are updated
Change ownership - Reassign file ownership when team members change
Update URLs - Fix broken documentation links or migrate to new documentation sites
Correct mistakes - Fix typos or incorrect values in previously added annotations
Workflow progression - Move files through stages (planning → development → testing → production)
Timestamp updates - Record when files were last reviewed, tested, or deployed

💡Common Patterns

Status Progression Workflow

// Move feature through development stages
const stages = {
  initial: 'planning',
  started: 'in-development',
  review: 'in-review',
  qa: 'testing',
  done: 'production'
};

// Update as work progresses
await codemap.annotations.edit({
  path: 'src/features/new-feature.ts',
  key: 'status',
  value: stages.review
});

Version Synchronization

// Keep related files in sync
const apiVersion = '2.1.0';
const apiFiles = ['routes.ts', 'handlers.ts', 'middleware.ts'];

for (const file of apiFiles) {
  await codemap.annotations.edit({
    path: src/api/v2/${file},
    key: 'version',
    value: apiVersion
  });
}

Ownership Transfer

// Reassign ownership when team member leaves
const oldOwner = 'john.doe';
const newOwner = 'jane.smith';

const files = await codemap.annotations.search({ 
  key: 'owner', 
  value: oldOwner 
});

for (const file of files) {
  await codemap.annotations.edit({
    path: file.path,
    key: 'owner',
    value: newOwner
  });
}

Documentation Link Migration

// Update all old documentation URLs
const oldDomain = 'old-docs.example.com';
const newDomain = 'docs.example.com';

const files = await codemap.search({
  query: oldDomain,
  mode: 'text'
});

for (const file of files.matches) {
  const annotations = await codemap.annotations.get(file.path);
  const docAnnotation = annotations.find(a => a.key === 'docs');
  
  if (docAnnotation) {
    const newUrl = docAnnotation.value.replace(oldDomain, newDomain);
    await codemap.annotations.edit({
      path: file.path,
      key: 'docs',
      value: newUrl
    });
  }
}

💡Pro Tips

Check before editing - Use codemap_get_annotations to verify the annotation exists before attempting to edit it. This prevents errors and allows conditional logic.

Batch updates efficiently - When updating multiple files with the same annotation value, process them in a loop to maintain consistency.

Preserve edit history - Consider adding a last-updated annotation whenever you edit other annotations to track when changes were made.

Use edit for corrections - If you added an annotation with a typo or incorrect value, use edit instead of remove + add to maintain the annotation's history.

Automate workflow transitions - Integrate annotation edits into your CI/CD pipeline to automatically update status as code moves through stages.

Track migration progress - When migrating code, use annotations to mark files as 'migrated', 'in-progress', or 'pending', then edit them as work completes.

✅Best Practices

Validate before editing - Always check that the annotation exists before attempting to edit it, especially in automated scripts.

Use consistent value formats - If an annotation uses ISO dates, always use ISO dates. If it uses semantic versions, stick to that format.

Document allowed values - For annotations with limited valid values (like status), document the accepted values in your team's coding standards.

Combine with search - Use codemap_search_annotations to find all files with a specific annotation before bulk editing them.

Edit atomically - Update related annotations together in the same workflow to maintain data consistency.

Log annotation changes - In critical workflows, log annotation edits for audit trails and debugging.

⚠️Common Mistakes

❌ Mistake: Editing a non-existent annotation

// This will fail if 'priority' annotation doesn't exist
await codemap.annotations.edit({
  path: 'src/app.ts',
  key: 'priority',
  value: 'high'
});

✅ Instead: Check if it exists first, or use try-catch

try {
  await codemap.annotations.edit({
    path: 'src/app.ts',
    key: 'priority',
    value: 'high'
  });
} catch (error) {
  if (error.message.includes('No annotation with key')) {
    // Add it instead
    await codemap.annotations.add({
      path: 'src/app.ts',
      key: 'priority',
      value: 'high'
    });
  }
}

---

❌ Mistake: Changing annotation format inconsistently

// Original: "2024-04-07"
await codemap.annotations.edit({
  path: 'src/file.ts',
  key: 'reviewed',
  value: 'April 7, 2024' // Different format!
});

✅ Instead: Maintain consistent formatting

await codemap.annotations.edit({
  path: 'src/file.ts',
  key: 'reviewed',
  value: new Date().toISOString().split('T')[0] // Always ISO format
});

---

❌ Mistake: Editing without verifying current value

// Blindly updating without checking current state
await codemap.annotations.edit({
  path: 'src/feature.ts',
  key: 'status',
  value: 'production' // Might skip important stages!
});

✅ Instead: Verify current status before transitioning

const annotations = await codemap.annotations.get('src/feature.ts');
const status = annotations.find(a => a.key === 'status');

if (status?.value === 'tested') {
  await codemap.annotations.edit({
    path: 'src/feature.ts',
    key: 'status',
    value: 'production'
  });
} else {
  console.warn(Cannot deploy - current status: ${status?.value});
}

---

❌ Mistake: Editing wrong annotation by key confusion

// Typo in key name
await codemap.annotations.edit({
  path: 'src/api.ts',
  key: 'verison', // Typo!
  value: '2.0.0'
});

✅ Instead: Use constants for annotation keys

const ANNOTATION_KEYS = {
  VERSION: 'version',
  STATUS: 'status',
  OWNER: 'owner'
} as const;

await codemap.annotations.edit({
  path: 'src/api.ts',
  key: ANNOTATION_KEYS.VERSION, // Type-safe
  value: '2.0.0'
});