write_file - Write File

Overview

The write_file tool writes content to a specified file in the local filesystem. It supports creating new files or overwriting existing files.

Tool Name

• Internal Name: write_file
• Display Name: WriteFile
• Icon: Pencil

Parameters

Required Parameters

Parameter	Type	Description
file_path	string	The absolute path to the file to write to (e.g., /home/user/project/file.txt). Relative paths are not supported.
content	string	The content to write to the file.

Optional Parameters

Parameter	Type	Description
modified_by_user	boolean	Whether the proposed content was modified by the user. Used for internal tracking.

Features

1. File Operations:

   • Create new files
   • Overwrite existing files
   • Automatically create necessary parent directories

2. User Confirmation:

   • Shows diff preview before writing
   • User can modify content in confirmation dialog
   • Supports VSCode IDE integrated diff view

3. Security Restrictions:

   • File path must be absolute
   • File must be within project root directory
   • Cannot write to directories

4. Content Correction:

   • Automatically corrects common formatting issues
   • Normalizes line endings
   • Ensures content integrity

Best Practices

1. For existing files: Use read_file first to verify current content before overwriting
2. For large files: Consider using replace tool for targeted edits instead
3. Avoid token limits: If content is very large, split into smaller operations

Usage Examples

Create New File

{
  "file_path": "/home/user/project/src/new-file.ts",
  "content": "export const greeting = 'Hello, World!';\n"
}

Overwrite Existing File

{
  "file_path": "/home/user/project/README.md",
  "content": "# My Project\n\nThis is an updated README.\n"
}

Write Configuration File

{
  "file_path": "/home/user/project/config.json",
  "content": "{\n  \"version\": \"1.0.0\",\n  \"name\": \"my-app\"\n}\n"
}

Return Value

The tool returns an object containing:

• llmContent: Operation result description
• returnDisplay: User-friendly display information (including file diff)
• summary: Operation summary

Error Handling

Possible error scenarios:

1. Path Errors:

   • Path is not absolute
   • Path is outside project root directory
   • Path is a directory, not a file

2. File Access Errors:

   • No write permission
   • Insufficient disk space
   • Parent directory doesn't exist and cannot be created

3. Parameter Errors:

   • Missing required parameters
   • Incorrect parameter types
   • Content truncated (exceeds token limit)

User Interaction

Confirmation Dialog

Outside of AUTO_EDIT mode, the tool displays a confirmation dialog:

• Title: Shows filename and operation type (new/modify)
• Diff View: Shows comparison between original and new content
• Options:
  • Proceed Once
  • Proceed Always
  • Modify with Editor
  • Cancel

VSCode Integration

In VSCode IDE mode:

• Automatically opens diff view
• Supports inline editing
• Real-time change preview

Notes

1. Data Loss Risk: Overwriting files permanently deletes original content, consider backing up first
2. Content Size: Very large content may exceed token limits, consider splitting operations
3. Line Endings: Tool automatically normalizes line endings to LF (\n)
4. Encoding: Defaults to UTF-8 encoding

Related Tools

• read_file: Read file
• replace: Replace specific text in file
• list_directory: List directory contents
• glob: Find files