codemap_create_symbol

Insert a new symbol (function, method, class, interface, type, const, or enum) into an existing file with precise placement control. Automatically handles indentation and spacing based on file conventions. Triggers automatic re-parse so the knowledge graph stays current.

iosymbolscreateinsertplacementrefactor

Parameters

Name	Type	Required	Description
`file`	`string`	✅ Required	Relative path to the file to insert the symbol into
`symbolName`	`string`	✅ Required	Name of the symbol to create (e.g. "deleteUser", "UserService", "IRepository")
`symbolType`	`string`	✅ Required	Type of symbol to create. One of: function \| method \| class \| interface \| type \| const \| enum
`content`	`string`	✅ Required	Full symbol body as a string (code without leading indentation — SymbolWriter handles indentation automatically)
`placement`	`object`	✅ Required	Placement configuration controlling where the symbol is inserted. Contains strategy (required) and optional strategy-specific fields.
`skipIndentation`	`boolean`	❌ Optional	Skip automatic indentation detection and application. Default: false (default: `false`)
`skipValidation`	`boolean`	❌ Optional	Skip syntax validation after insertion. Default: false (default: `false`)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_create_symbol",
  "arguments": {
    "file": "src/utils/formatters.ts",
    "symbolName": "formatCurrency",
    "symbolType": "function",
    "content": "export function formatCurrency(amount: number, currency = 'USD'): string {\n  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amount);\n}",
    "placement": {
      "strategy": "append"
    }
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "file": "/path/to/project/src/services/UserService.ts",
    "symbolName": "deleteUser",
    "symbolType": "method",
    "insertedAt": {
      "line": 87,
      "column": 3
    },
    "linesAdded": 4,
    "placementStrategy": "endOfClass"
  },
  "hint": "💡 The file was automatically re-parsed - symbols and dependencies are now up to date"
}

ℹ️When to Use This Tool

codemap_create_symbol

Add a method to an existing class without rewriting the entire file
Insert a utility function at a precise location relative to other symbols
Scaffold new interface methods during iterative development
Add constants or type aliases at the top of a file after imports
Extract functionality by inserting a symbol before deleting it from another file

💡Common Patterns

Safe Class Extension Pattern

1. codemap_get_symbols({ target: "src/services/UserService.ts" }) → confirm class exists
2. codemap_create_symbol with strategy: endOfClass, className: "UserService"
3. codemap_get_symbols({ target: "src/services/UserService.ts" }) → verify insertion

Use endOfClass rather than afterSymbol when extending classes — it's the safest strategy because it doesn't require knowing an existing method name.

Symbol Extraction Pattern

1. codemap_read_file({ path: "src/utils/auth.ts$validateToken" }) → read the symbol
2. codemap_create_symbol in destination file with strategy: append
3. codemap_delete({ target: "src/utils/auth.ts$validateToken" }) → remove from source
4. Update all import references

This is the safest way to move symbols between files without accidental data loss.

Interface-Driven Development Pattern

1. Create interface method with strategy: endOfInterface
2. Implement the method in the class with strategy: endOfClass
3. codemap_get_dependencies to verify the class still satisfies the interface

💡Pro Tips

Auto-sync is free — after insertion, the file is automatically re-parsed and the knowledge graph updates; no need to call codemap_reindex
Content without indentation — pass the symbol body at zero indentation; SymbolWriter detects file conventions (tabs vs spaces, indent size) and applies them correctly
endOfClass is the safest insertion — avoids brittle line-number targeting and doesn't require knowing adjacent symbol names
prepend puts constants in the right place — symbols inserted with prepend go after the import block, keeping the file structure clean
Pair with codemap_rollback — if an insertion corrupts the file, rollback restores the pre-insertion state instantly

✅Best Practices

Verify the target class or symbol exists with codemap_get_symbols before using strategies that reference it (endOfClass, afterSymbol, beforeSymbol)
Use symbolType: method for class methods and symbolType: function for top-level functions — SymbolWriter applies appropriate indentation for each
Keep content clean: don't add leading whitespace to your content string, SymbolWriter handles all indentation
For multi-method additions, call codemap_create_symbol once per method rather than trying to inject multiple symbols in one call
For large symbols (>30 lines), consider codemap_write with symbol targeting instead — it replaces rather than inserts, which is safer for significant additions

⚠️Common Mistakes

❌ Mistake: Providing indented content
✅ Instead: Pass content at zero indentation — "async deleteUser(id: string): Promise {...}" not " async deleteUser...". SymbolWriter will indent it correctly.

❌ Mistake: Using atLine strategy when a symbol reference would work
✅ Instead: Use endOfClass or afterSymbol — line numbers change as files evolve, symbol names don't.

❌ Mistake: Not verifying the className/interfaceName exists before using endOfClass/endOfInterface
✅ Instead: Call codemap_get_symbols first to confirm the target class is in the file.

❌ Mistake: Using this tool to add symbols to files that don't exist yet
✅ Instead: Use codemap_create to create the file first, then use codemap_create_symbol to populate it.

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_write

codemap_io_delete

codemap_io_get-symbols

codemap_io_read