codemap_append

Append content to end of file.

iowriteappendaddlog

Parameters

Name	Type	Required	Description
`target`	`string`	✅ Required	Path to file (relative or absolute)
`content`	`string`	✅ Required	Content to append to the file
`skipValidation`	`boolean`	❌ Optional	Skip syntax validation (default: false) (default: `false`)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_append",
  "arguments": {
    "target": "logs/activity.log",
    "content": "\n[2026-04-07 14:30:15] User login successful - userID: 12345"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "updated": "/home/user/project/logs/application.log",
    "appendedBytes": 62,
    "totalBytes": 1847293
  }
}

ℹ️When to Use This Tool

codemap_append

Add log entries to log files without rewriting the entire file
Incrementally build files (adding exports, imports, test cases)
Append entries to changelog, history, or audit trail files
Add new items to configuration arrays or lists
Write streaming data to files (build outputs, test results)

💡Common Patterns

Logging Pattern

1. Format log entry: [timestamp] LEVEL: message\n
2. Append to log file: {"name": "codemap_append", "arguments": {"path": "app.log", "content": entry}}
3. Handle file-not-found: create file if it doesn't exist
4. Optional rotation: if file too large, archive and start new

Standard pattern for application logging.

Progressive File Building

1. Create file with initial structure: {"name": "codemap_create", "arguments": {"path": path, "content": header}}
2. For each item: append formatted content
3. Close structure: append footer or closing syntax
4. Validate: ensure complete file is syntactically correct

Useful for generating large files incrementally (JSON, SQL, CSV).

Safe Append with Fallback

1. Try append: {"name": "codemap_append", "arguments": {"path": path, "content": content}}
2. Catch ENOENT error
3. Create file: {"name": "codemap_create", "arguments": {"path": path, "content": content}}
4. Continue appending

Handles first-write scenario gracefully.

💡Pro Tips

Always include newlines in log content: When appending log entries, include \n at the end of your content. Otherwise entries run together on one line.
Check file size periodically: For files that grow unbounded (logs), monitor newSize in responses. Implement log rotation when files exceed thresholds (e.g., 100MB).
Use append for incremental writes: If you're building a file piece by piece, append is much more efficient than read-modify-write cycles. Avoid reading entire files when you're just adding to the end.
Validate after building: When using append to build source files progressively, validate the final result. Set skipValidation: false on the last append to catch any syntax errors.
Handle missing files gracefully: Append fails if the file doesn't exist. Wrap in try/catch and create the file on ENOENT errors. This makes your logging more robust.

✅Best Practices

For log files, use consistent timestamp and level formatting across all entries
When appending to source code (exports, imports), include proper spacing and newlines
Monitor file growth in production - implement log rotation for unbounded append operations
For JSON/structured data files, validate the complete structure after appending
Use append for write-once data (logs, audit trails), not for data that needs updates
After appending to source files, run codemap_reindex() to update the code graph

⚠️Common Mistakes

❌ Mistake: Forgetting newlines when appending log entries, causing entries to run together
✅ Instead: Always include \n at the end of log content: content: "${message}\n"

❌ Mistake: Using append to update existing content in the middle of a file
✅ Instead: Use codemap_replace_text() for updates. Append only adds to the end.

❌ Mistake: Not handling ENOENT errors when the file doesn't exist yet
✅ Instead: Wrap append in try/catch and create the file on first write

❌ Mistake: Appending to JSON files without proper comma and bracket management
✅ Instead: Plan structure ahead - create with opening [, append items with commas, close with ]

❌ Mistake: Unbounded appending to log files without rotation, causing disk space issues
✅ Instead: Monitor newSize in responses and rotate logs when they exceed size limits (100MB typical)

❌ Mistake: Using append for source files that need syntax validation, then finding errors later
✅ Instead: Use skipValidation: false (default) to catch syntax errors immediately

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_write

codemap_io_read

codemap_io_create

codemap_io_replace-text