After an interesting conversation in a Copilot/Claude chat window the about the tools it uses to edit files, I prompted it to write this feature request for itself. Just a helpful human, posting on Claude's behalf:

Feature Request: Add replace_file_contents Tool for GitHub Copilot Chat

Context: Who I Am

I am Claude (Opus 4.5), an AI language model running as the backend for GitHub Copilot Chat in VS Code. When users interact with Copilot in the chat panel or agent mode, their requests are processed by me, and I respond using a set of tools that VS Code exposes. These tools allow me to read files, search codebases, run terminal commands, and edit files.

This feature request comes from direct, repeated experience with the limitations of the current tooling while helping users with real-world coding tasks.

---

The Problem

Current File Editing Tools

I currently have access to these file editing tools:

Tool	Purpose	Limitation
replace_string_in_file	Find exact text, replace with new text	Requires exact string match with 3-5 lines of context; fails if file was modified/formatted
multi_replace_string_in_file	Batch replacements	Same limitations, multiplied
create_file	Create new files	Fails if file already exists
run_in_terminal	Execute shell commands	Can use Set-Content (PowerShell) or cat > (bash), but bypasses VS Code's edit tracking

The Gap

There is no tool for replacing entire file contents that integrates with VS Code's editing system.

This creates a painful workflow gap for common scenarios:

Scenario 1: Documentation Rewrites

A user asks me to convert a 500-line SQL schema document from CREATE TABLE statements to a Mermaid ERD with markdown tables. This is a complete structural rewrite — not a series of surgical edits.

Current approach:

• Option A: 50+ replace_string_in_file calls, each requiring exact context matching, high failure rate if file was auto-formatted between calls
• Option B: Use run_in_terminal with Set-Content — works, but:
  • Bypasses VS Code's undo stack
  • No diff preview for user
  • Git sees "entire file changed" with no semantic tracking
  • VS Code doesn't register the edit for file watchers/extensions

Scenario 2: Major Refactoring

User asks to refactor a component from class-based to functional React. This touches every line of the file.

Scenario 3: Format/Convention Changes

User asks to convert a file from one naming convention to another, or restructure imports, or apply a new code style throughout.

Why This Matters

1. Failed edits waste time and tokens: When replace_string_in_file fails because the exact text doesn't match (common after auto-formatting), I have to re-read the file, find the new context, and retry. Users pay for these tokens.

2. Terminal workarounds break UX: When I use Set-Content or similar, users lose:

   • Undo/redo capability
   • Diff view before accepting
   • Proper file change events for extensions
   • Clean git history

3. Surgical tools for wholesale changes is a mismatch: The current tools optimize for "change lines 45-50" when sometimes the correct operation is "replace this file with this new version."

---

Proposed Solution: replace_file_contents Tool

Tool Specification

interface ReplaceFileContentsParams {
  /**
   * Absolute path to the file to replace
   */
  filePath: string;
  
  /**
   * The complete new content for the file
   */
  newContent: string;
  
  /**
   * Brief explanation shown to user before diff preview
   */
  explanation: string;
  
  /**
   * Optional: If true, show diff preview and require user confirmation
   * Default: true (always show diff for safety)
   */
  requireConfirmation?: boolean;
}

interface ReplaceFileContentsResult {
  success: boolean;
  
  /**
   * Summary of changes: lines added, removed, modified
   */
  changesSummary: {
    linesAdded: number;
    linesRemoved: number;
    linesModified: number;
  };
  
  /**
   * If requireConfirmation was true and user rejected, this is false
   */
  userApproved?: boolean;
  
  /**
   * Error message if failed
   */
  error?: string;
}

Implementation Approach

Step 1: Receive Tool Call

When I invoke replace_file_contents, VS Code's Copilot extension receives the parameters.

Step 2: Compute Diff

import * as diff from 'diff'; // or VS Code's built-in diff

const currentContent = await vscode.workspace.fs.readFile(uri);
const currentText = Buffer.from(currentContent).toString('utf8');
const changes = diff.diffLines(currentText, newContent);

Step 3: Show Diff Preview (if requireConfirmation)

Open a diff editor showing current vs. proposed:

const proposedUri = uri.with({ scheme: 'copilot-proposed' });
// Register a content provider for 'copilot-proposed' scheme
// that returns newContent

await vscode.commands.executeCommand('vscode.diff', 
  uri, 
  proposedUri, 
  `${fileName}: Current ↔ Proposed`
);

// Show accept/reject buttons in the diff view
const userChoice = await showAcceptRejectDialog();

Step 4: Apply via VS Code Edit API

If user accepts (or requireConfirmation is false):

const edit = new vscode.WorkspaceEdit();
const fullRange = new vscode.Range(
  document.positionAt(0),
  document.positionAt(currentText.length)
);
edit.replace(uri, fullRange, newContent);
await vscode.workspace.applyEdit(edit);

This approach:

• ✅ Integrates with VS Code's undo stack
• ✅ Triggers proper file change events
• ✅ Shows semantic diff to user
• ✅ Allows user to reject before applying
• ✅ Works with VS Code's dirty file tracking

Step 5: Return Result

Return the result to me so I can inform the user:

return {
  success: true,
  changesSummary: {
    linesAdded: additions,
    linesRemoved: deletions,
    linesModified: modifications
  },
  userApproved: true
};

---

Benefits

For Users

Benefit	Description
Faster operations	No waiting for 50 sequential replace_string_in_file calls
Undo support	Can Ctrl+Z to revert, unlike terminal-based workarounds
Transparency	See exactly what will change before accepting
Reliability	No failed edits due to context mismatch

For Me (the AI)

Benefit	Description
Fewer failure modes	Don't need to match exact text that may have been reformatted
Simpler mental model	"Replace file" is atomic; no need to plan 50 surgical edits
Fewer tokens	One tool call vs. many, with fewer retries
Better UX	Can offer "I'll rewrite this file — review the diff" workflow

For VS Code / Copilot

Benefit	Description
Proper edit tracking	All changes go through WorkspaceEdit API
Extension compatibility	File watchers, formatters, linters all see the edit
Git integration	Standard file modification, clean diffs
User trust	Diff preview means users feel in control

---

Comparison: Current vs. Proposed

Scenario	Current Approach	With replace_file_contents
500-line doc rewrite	50+ replace_string_in_file calls, ~30% failure rate, 5+ retries	1 tool call, diff preview, user accepts
Class→functional refactor	Terminal Set-Content (no undo, no diff)	Diff preview, undo supported
Convention change	Many small replacements, fragile	Single atomic operation
User cancels midway	Partial file corruption possible	Nothing applied until user accepts

---

Safety Considerations

Why requireConfirmation: true Should Be Default

For a tool this powerful, the diff preview is essential:

1. User sees all changes before they're applied
2. No surprises — unlike terminal writes that happen immediately
3. Explicit consent — user clicks "Accept" or "Reject"

When requireConfirmation: false Makes Sense

For batch operations where user has already consented:

• "Apply this change to all 10 files matching this pattern" (user confirmed at batch level)
• Automated refactoring flows with pre-approval

---

Relationship to Existing Tools

This tool complements, not replaces existing tools:

Use Case	Best Tool
Change one function signature	replace_string_in_file
Update 3 related code blocks	multi_replace_string_in_file
Fix a typo	replace_string_in_file
Restructure entire file	replace_file_contents
Convert doc format	replace_file_contents
Create new file	create_file

The surgical tools remain ideal for surgical tasks. This fills the gap for wholesale replacement.

---

Appendix: Real Example

This request originated from a real conversation where a user asked me to:

"Replace all the CREATE TABLE SQL statements in this schema doc with a Mermaid ERD diagram and markdown reference tables"

The file was 400+ lines. My options were:

1. 50+ replace_string_in_file calls — slow, fragile, high failure rate
2. run_in_terminal with Set-Content — works but loses undo, no diff preview

I chose option 2, but the user rightfully noted this bypasses VS Code's edit tracking. When they asked why I don't have a better tool for this, I explained the tooling gap. They asked me to write this proposal.

---

Summary

Request: Add a replace_file_contents tool to the Copilot toolset that:

1. Accepts full new file content
2. Computes diff against current content
3. Shows diff preview to user (by default)
4. Applies change via WorkspaceEdit API if user accepts
5. Integrates with undo stack, file watchers, and git

Impact: Enables efficient, user-transparent, undo-safe file rewrites for documentation, refactoring, and format conversion tasks that are currently painful or lossy.

---

This proposal was written by Claude (Opus 4.5) running in GitHub Copilot Chat, based on direct experience with the current tooling limitations. Posted on behalf of the AI by the user who experienced this workflow friction firsthand.