codemap_write

Write or update file contents. Supports symbol targeting (relativePath$symbolName) to replace an entire symbol (function, class, method) without touching the rest of the file.

iowriteeditupdatesymbol-targeting

Parameters

Name	Type	Required	Description
`target`	`string`	✅ Required	Relative path to the file, or symbol reference (relativePath$symbolName) to replace that entire symbol
`content`	`string`	✅ Required	Content to write. For symbol targeting, provide the full new symbol body including its signature.
`skipValidation`	`boolean`	❌ Optional	Skip syntax validation after write. Default: false (default: `false`)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_write",
  "arguments": {
    "path": "config/database.json",
    "content": "{\n  \"host\": \"localhost\",\n  \"port\": 5432,\n  \"database\": \"production_db\"\n}"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "path": "/home/user/project/src/components/Button.tsx",
  "size": 387
}

ℹ️When to Use This Tool

codemap_write

Overwrite entire file contents with new data (config files, generated code, templates)
Update source files after code generation or refactoring operations
Create or replace files as part of automated workflows
Write processed data back to disk after transformation
Save modified content that has been edited programmatically

💡Common Patterns

Read-Modify-Write Pattern

1. Read file: {"name": "codemap_read_file", "arguments": {"path": "config.json"}}
2. Parse and modify content: const data = JSON.parse(content); data.version++
3. Write back: {"name": "codemap_write", "arguments": {"path": "config.json", "content": JSON.stringify(data, null, 2)}}
4. Verify: {"name": "codemap_read_file", "arguments": {"path": "config.json"}}

This is the safest pattern for updating files - always read first to preserve data you don't intend to change.

Template Generation Pattern

1. Define template structure
2. Populate with dynamic values
3. Write to target location: {"name": "codemap_write", "arguments": {"path": "generated/output.ts", "content": filled}}
4. Reindex to update code graph: call codemap_reindex()

Use this when generating source files from templates or scaffolding.

Batch Configuration Update

1. List all config files: search for .json files in config directory
2. For each file: read, modify specific fields, write back
3. Track changes in session notes
4. Test configuration after batch update

Efficient for updating multiple related configuration files.

💡Pro Tips

Always read before write for updates: Unless you're creating a new file from scratch, read the existing content first. This prevents accidental data loss and helps you preserve parts of the file you don't want to change.
Use skipValidation for work-in-progress: When writing incomplete code snippets or experimenting, set skipValidation: true to avoid syntax errors blocking your work. Remember to validate later when the code is complete.
Pretty-print JSON files: When writing JSON, use JSON.stringify(data, null, 2) to include proper indentation. This makes files readable and diff-friendly for version control.
Track file sizes: The response includes size and linesWritten - monitor these for large files. If a write unexpectedly creates a huge file, you may have a bug in your content generation logic.
Consider file watching: After writing files that are part of your build system, tools like TypeScript compiler or bundlers may need to re-run. Write files in batches when possible to reduce rebuild churn.

✅Best Practices

Always validate file paths before writing - ensure directories exist and paths are correct
For generated code, include a header comment like "// AUTO-GENERATED - DO NOT EDIT" to prevent manual edits
Write atomic updates when possible - avoid writing half-complete files that could break the system if interrupted
Use consistent line endings (LF vs CRLF) appropriate for your platform and version control settings
Test write permissions before attempting batch operations - a single permission error shouldn't halt entire workflows
After writing source files, run codemap_reindex() to update the code graph and symbol index

⚠️Common Mistakes

❌ Mistake: Writing to a file path without checking if directories exist
✅ Instead: Ensure parent directories exist or use a file creation method that creates them automatically

❌ Mistake: Overwriting files without reading them first, losing data you wanted to preserve
✅ Instead: Always use the read-modify-write pattern: read the current content, modify only what needs to change, then write back

❌ Mistake: Writing large files synchronously without progress indication
✅ Instead: For files over 1MB, consider chunking or provide progress feedback. Monitor the size field in responses.

❌ Mistake: Forgetting to stringify objects when writing JSON files
✅ Instead: Always use JSON.stringify(data, null, 2) for JSON files. The tool writes raw strings, not objects.

❌ Mistake: Writing generated code without a "do not edit" warning
✅ Instead: Include header comments in generated files: // AUTO-GENERATED on 2026-04-07 - DO NOT EDIT MANUALLY

❌ Mistake: Using write when you only need to append or replace specific sections
✅ Instead: Use codemap_append() for adding content or codemap_replace_text() for targeted edits. Write overwrites everything.

Changelog

1 release

- 🐛FixedLine-range targets (file.ts:10-20) now resolve correctly for writes. A stray double-escape (\\d instead of \d) in the TargetResolver line-range regex caused ranges to fail silently.
- 🐛FixedSymbol-scoped writes (file.ts$symbolName) now work on multi-line files of any size. Fixed a newline-handling bug in TargetResolver.extractSymbolContent that caused symbol lookups to return undefined on any multi-line file. Tested on a 1168-line file — getStats() replaced at line 680 with surrounding code untouched.

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_read

codemap_io_create

codemap_io_replace-text

codemap_io_append