codemap_remove_annotation

Remove a @codemap annotation from a file.

annotationswritedelete

Parameters

Name	Type	Required	Description
`path`	`string`	✅ Required	File path (relative or absolute)
`key`	`string`	✅ Required	Annotation key to remove

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_remove_annotation",
  "arguments": {
    "path": "src/utils/helpers.ts",
    "key": "author"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "path": "src/utils/helpers.ts",
  "key": "author",
  "action": "removed",
  "storage": "meta"
}

ℹ️When to Use This Tool

codemap_remove_annotation

Clean up temporary markers - Remove 'wip', 'draft', or 'experimental' annotations when work is complete
Remove obsolete metadata - Delete version annotations from deprecated APIs or old documentation links
Fix mistakes - Remove annotations added by error or with incorrect keys
Workflow cleanup - Remove annotations after migration, refactoring, or deployment completes
Data privacy - Remove annotations containing sensitive or outdated personal information
Reduce noise - Delete annotations that are no longer relevant to keep metadata clean
Pre-deletion cleanup - Remove all annotations before deleting files

💡Common Patterns

Temporary Annotation Cleanup

// Remove work-in-progress markers after completion
const wipFiles = await codemap.annotations.search({
  key: 'status',
  value: 'wip'
});

for (const file of wipFiles) {
  // Verify work is actually complete
  const annotations = await codemap.annotations.get(file.path);
  const completedDate = annotations.find(a => a.key === 'completed');
  
  if (completedDate) {
    await codemap.annotations.remove({
      path: file.path,
      key: 'status'
    });
  }
}

Migration Cleanup

// Remove migration metadata after successful migration
const completedMigrations = await codemap.annotations.search({
  key: 'migration-status',
  value: 'complete'
});

for (const file of completedMigrations) {
  await codemap.annotations.remove({
    path: file.path,
    key: 'migration-status'
  });
  
  await codemap.annotations.remove({
    path: file.path,
    key: 'migration-target'
  });
}

Bulk Deprecation Cleanup

// Remove all deprecated flags from deleted features
const deprecatedFiles = await codemap.annotations.search({
  key: 'deprecated',
  value: 'true'
});

for (const file of deprecatedFiles) {
  // Verify file still exists
  try {
    await codemap.peek({ target: file.path });
    // File exists, remove annotation
    await codemap.annotations.remove({
      path: file.path,
      key: 'deprecated'
    });
  } catch {
    // File doesn't exist, annotation already orphaned
    console.log(File ${file.path} no longer exists);
  }
}

Conditional Removal Based on Status

// Remove 'experimental' flag when feature becomes stable
const files = await codemap.annotations.search({
  key: 'experimental'
});

for (const file of files) {
  const annotations = await codemap.annotations.get(file.path);
  const status = annotations.find(a => a.key === 'status');
  
  if (status?.value === 'production-ready') {
    await codemap.annotations.remove({
      path: file.path,
      key: 'experimental'
    });
  }
}

💡Pro Tips

Check before removing - Use codemap_get_annotations to verify the annotation exists before attempting removal. This prevents unnecessary errors in automation scripts.

Remove related annotations together - If annotations are logically grouped (e.g., 'migration-status' and 'migration-target'), remove them in the same workflow to avoid partial states.

Use search for bulk removal - Combine codemap_search_annotations with remove to clean up annotations across multiple files efficiently.

Consider editing instead - If you need to change an annotation value, use codemap_edit_annotation instead of remove + add. This preserves the annotation's history.

Clean before deleting files - Remove all annotations from a file before deleting it to prevent orphaned metadata.

Automate cleanup - Integrate annotation removal into deployment scripts to automatically clean up temporary markers when code ships.

✅Best Practices

Verify file exists - Before bulk removals, check that files still exist in the project to avoid errors on orphaned annotations.

Log removals in critical workflows - For production deployments or migrations, log which annotations were removed for audit trails.

Use try-catch for bulk operations - When removing annotations from multiple files, wrap each removal in error handling to prevent one failure from stopping the entire batch.

Remove in reverse dependency order - If annotations have dependencies (e.g., 'reviewed' depends on 'reviewer'), remove them in the correct order.

Document removal reasons - In scripts, add comments explaining why annotations are being removed to help future maintainers.

Clean up periodically - Schedule regular reviews to remove obsolete annotations and keep metadata fresh.

⚠️Common Mistakes

❌ Mistake: Removing annotations without checking if they exist

// This will throw an error if annotation doesn't exist
await codemap.annotations.remove({
  path: 'src/app.ts',
  key: 'temporary'
});

✅ Instead: Use try-catch or check first

try {
  await codemap.annotations.remove({
    path: 'src/app.ts',
    key: 'temporary'
  });
  console.log('Removed temporary annotation');
} catch (error) {
  if (!error.message.includes('No annotation with key')) {
    throw error; // Re-throw unexpected errors
  }
  // Annotation doesn't exist, that's fine
}

---

❌ Mistake: Removing the wrong annotation by key typo

// Typo in key name
await codemap.annotations.remove({
  path: 'src/api.ts',
  key: 'verison' // Meant to type 'version'
});
// Fails, but the typo might not be obvious

✅ Instead: Use constants for keys

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

await codemap.annotations.remove({
  path: 'src/api.ts',
  key: KEYS.VERSION // Type-safe, autocomplete helps
});

---

❌ Mistake: Removing annotations before verifying workflow completion

// Dangerous: removing migration marker too early
await codemap.annotations.remove({
  path: 'src/feature.ts',
  key: 'migration-in-progress'
});
// What if migration actually failed?

✅ Instead: Verify completion first

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

if (migrationStatus?.value === 'success') {
  await codemap.annotations.remove({
    path: 'src/feature.ts',
    key: 'migration-in-progress'
  });
  console.log('Migration complete, cleaned up marker');
} else {
  console.warn('Migration not yet complete, keeping marker');
}

---

❌ Mistake: Not handling bulk removal failures gracefully

// One error stops everything
const files = await codemap.annotations.search({ key: 'temp' });
for (const file of files) {
  await codemap.annotations.remove({
    path: file.path,
    key: 'temp'
  }); // If this fails, remaining files aren't processed
}

✅ Instead: Continue on errors, log results

const files = await codemap.annotations.search({ key: 'temp' });
const results = { success: 0, failed: 0 };

for (const file of files) {
  try {
    await codemap.annotations.remove({
      path: file.path,
      key: 'temp'
    });
    results.success++;
  } catch (error) {
    results.failed++;
    console.error(Failed to remove from ${file.path}:, error.message);
  }
}

console.log(Removed ${results.success} annotations, ${results.failed} failures);