codemap_replace_many

Perform multiple find-and-replace operations in one file. Supports symbol targeting (relativePath$symbolName) to scope all replacements within a specific function or class. Supports regex with capture groups via useRegex.

iowritereplacebulkbatchrefactorsymbol-targeting

Parameters

Name	Type	Required	Description
`target`	`string`	✅ Required	Relative path to the file, or symbol reference (relativePath$symbolName) to scope all replacements to that symbol
`replacements`	`string`	✅ Required	JSON array of replacement objects: [{oldString: string, newString: string, useRegex?: boolean}]. Set useRegex: true to treat oldString as a regex pattern with capture group support.
`skipValidation`	`boolean`	❌ Optional	Skip syntax validation after replacements. Default: false (default: `false`)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_replace_many",
  "arguments": {
    "target": "src/constants.ts",
    "replacements": "[{\"oldString\":\"localhost\",\"newString\":\"production.com\"},{\"oldString\":\"3000\",\"newString\":\"443\"},{\"oldString\":\"http://\",\"newString\":\"https://\"}]"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "updated": "P:\\Workspace\\my-project\\src\\config.ts",
    "replacements": 3,
    "requested": 3
  }
}

ℹ️When to Use This Tool

codemap_replace_many

Update multiple related configuration values in a single file (API URLs, ports, hosts)
Refactor import paths from relative to absolute across one file
Rename multiple functions, variables, or types for consistency
Migrate from old API patterns to new patterns in one operation
Update multiple deprecated method calls to their modern equivalents
Perform complex refactoring with multiple coordinated string replacements

💡Common Patterns

Configuration Migration Pattern

1. Define all replacements as array: [{oldString, newString}, ...]
2. Encode as JSON string: JSON.stringify(replacements)
3. Call replace_many with JSON string
4. Verify replacement count matches expectations

Standard pattern for config file updates.

Import Path Refactoring

1. Search for files with old import style
2. For each file: build replacement list
3. Call replace_many to update all imports at once
4. Reindex to update code graph

Efficient for converting relative to absolute imports.

Regex-Based Bulk Update

1. For each pattern: set useRegex: true in replacement object
2. Use capture groups in oldString: "const (\\w+) = require"
3. Reference groups in newString: "import $1 from"
4. Encode array as JSON and execute

Powerful for complex transformations.

💡Pro Tips

Use JSON.stringify for replacements parameter: The parameter expects a JSON string, not an array object. Always wrap your replacements array in JSON.stringify().
Set useRegex: true per replacement: Each replacement in the array can independently use regex. Mix literal and regex replacements in the same call by setting useRegex flag appropriately.
Order matters for overlapping replacements: Replacements execute sequentially. If later replacements depend on earlier ones, order your array carefully. For independent replacements, order doesn't matter.
Check replacement counts in response: The response shows how many replacements succeeded. If count is lower than expected, some oldStrings weren't found - investigate why.
Use for single-file refactoring: Replace-many is optimized for multiple changes in one file. For multi-file operations, call it once per file in a loop.

✅Best Practices

Always JSON.stringify the replacements array before passing as parameter
Group logically related replacements together (all imports, all config values)
Use regex mode sparingly - literal string replacement is safer and faster
Test regex patterns separately before using in production refactoring
After refactoring source code, run codemap_reindex() to update symbols
For critical files, read content before and after to verify changes

⚠️Common Mistakes

❌ Mistake: Passing replacements as JavaScript array instead of JSON string
✅ Instead: Always use JSON.stringify([{oldString, newString}]) to encode the array

❌ Mistake: Forgetting useRegex: true when using regex patterns, causing literal string match failure
✅ Instead: Explicitly set useRegex: true in each replacement object that uses regex patterns

❌ Mistake: Assuming all replacements will succeed without checking the response
✅ Instead: Check totalReplacements in response. If it's less than array length, investigate missing matches.

❌ Mistake: Using replace-many for cross-file refactoring instead of per-file operations
✅ Instead: Call replace-many once per file in a loop for multi-file refactoring

❌ Mistake: Creating replacement conflicts where later replacements undo earlier ones
✅ Instead: Ensure replacements are independent or order them so dependencies execute first

❌ Mistake: Using complex regex without testing, causing unexpected transformations
✅ Instead: Test regex patterns separately with simple replace-text calls before using in replace-many

Changelog

1 release

- 🐛FixedSymbol-scoped batch replaces (file.ts$symbolName) now work on multi-line files of any size. A newline-handling bug in TargetResolver.extractSymbolContent caused symbol content lookups to return undefined from the first symbol onward on any multi-line file.

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_replace-text

codemap_io_write

codemap_io_read