RooPrompts/docs/advanced-usage/available-tools/write-to-file.md

# write_to_file

The `write_to_file` tool creates new files or completely replaces existing file content with an interactive approval process. It provides a diff view for reviewing changes before they're applied.

## Parameters

The tool accepts these parameters:

- `path` (required): The path of the file to write to, relative to the current working directory
- `content` (required): The complete content to write to the file
- `line_count` (required): The number of lines in the file, including empty lines

## What It Does

This tool writes content to a specified file, either creating a new file if it doesn't exist or completely overwriting an existing file. All changes require explicit user approval through a diff view interface, where users can review and even edit the proposed changes before they're applied.

## When is it used?

- When Roo needs to create a new file from scratch
- When Roo needs to completely rewrite an existing file
- When creating multiple files for a new project
- When generating configuration files, documentation, or source code
- When you need to review changes before they're applied

## Key Features

- Interactive Approval: Shows changes in a diff view requiring explicit approval before applying
- User Edit Support: Allows editing the proposed content before final approval
- Safety Measures: Detects code omission, validates paths, and prevents truncated content
- Editor Integration: Opens a diff view that scrolls to the first difference automatically
- Content Preprocessing: Handles artifacts from different AI models to ensure clean content
- Access Control: Validates against `.rooignore` restrictions before making changes
- Parent Directories: May handle directory creation through system dependencies
- Complete Replacement: Provides a fully transformed file in a single operation

## Limitations

- Not suitable for existing files: Much slower and less efficient than `apply_diff` for modifying existing files
- Performance with large files: Operation becomes significantly slower with larger files
- Complete overwrite: Replaces entire file content, cannot preserve original content
- Line count required: Needs accurate line count to detect potential content truncation
- Review overhead: The approval process adds extra steps compared to direct edits
- Interactive only: Cannot be used in automated workflows that require non-interactive execution

## How It Works

When the `write_to_file` tool is invoked, it follows this process:

1. **Parameter Validation**: Validates the required parameters and permissions
   - Checks that `path`, `content`, and `line_count` are provided
   - If `line_count` is missing/invalid, reverts any diff view changes and returns an error suggesting alternative tools (`apply_diff`, `insert_content`, etc.) if modifying an existing file.
   - Validates the file is allowed (not restricted by `.rooignore`)
   - Ensures the path is within the workspace boundaries
   - Tracks consecutive mistake counts for missing parameters
   - Shows specific error messages for each validation failure

2. **Content Preprocessing**:
   - Removes code block markers that might be added by AI models
   - Handles escaped HTML entities (specifically for non-Claude models)
   - Strips line numbers if accidentally included in content
   - Performs model-specific processing for different AI providers

3. **Diff View Generation**:
   - Opens a diff view in the editor showing the proposed changes
   - Adds a 300ms delay to ensure UI responsiveness
   - Scrolls automatically to the first difference
   - Highlights changes for easy review

4. **User Approval Process**:
   - Waits for explicit user approval to proceed
   - Allows users to edit the content in the diff view
   - Captures any user edits for the final content
   - Provides option to reject changes entirely
   - Detects and incorporates user modifications into the final result

5. **Safety Validation**:
   - Detects potential content truncation by comparing with provided line count
   - Shows warnings if content appears incomplete
   - Validates file path and access permissions
   - Specifically checks if files are outside the workspace with `isOutsideWorkspace` flag

6. **File Writing**:
   - Writes the approved content (with any user edits) to the file
   - Provides confirmation of successful write
   - Resets the consecutive mistakes counter on success

## Examples When Used

- When creating a new project, Roo generates multiple files but lets you review each before committing changes.
- When setting up configuration files, Roo shows the proposed configuration in a diff view for approval.
- When generating documentation, Roo creates markdown files but lets you make final adjustments in the diff view.
- When developing a prototype, Roo shows complete source files in a diff view where you can fine-tune before saving.

## Usage Examples

Creating a new JSON configuration file:
```
<write_to_file>
<path>config/settings.json</path>
<content>
{
  "apiEndpoint": "https://api.example.com",
  "theme": {
    "primaryColor": "#007bff",
    "secondaryColor": "#6c757d",
    "fontFamily": "Arial, sans-serif"
  },
  "features": {
    "darkMode": true,
    "notifications": true,
    "analytics": false
  },
  "version": "1.0.0"
}
</content>
<line_count>14</line_count>
</write_to_file>
```

Creating a simple HTML file:
```
<write_to_file>
<path>src/index.html</path>
<content>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Application</title>
  <link rel="stylesheet" href="styles.css">
</head>
<body>
  <div id="app"></div>
  <script src="app.js"></script>
</body>
</html>
</content>
<line_count>13</line_count>
</write_to_file>
```

Creating a JavaScript module:
```
<write_to_file>
<path>src/utils/helpers.js</path>
<content>
/**
 * Utility functions for the application
 */

export function formatDate(date) {
  return new Date(date).toLocaleDateString();
}

export function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

export function debounce(func, delay) {
  let timeout;
  return function(...args) {
    clearTimeout(timeout);
    timeout = setTimeout(() => func.apply(this, args), delay);
  };
}
</content>
<line_count>18</line_count>
</write_to_file>
```