The Problem
When an AI assistant edits your files using built-in tools, changes are written to disk immediately. There is no intermediate step between "the agent decided what to do" and "your file has been modified." If the edit was wrong (a misplaced insertion, a botched replacement, a partial deletion), the damage is already done.
This creates a trust problem. Developers learn to distrust their assistant's edits, working from clean Git states and restoring frequently. They review every line of every diff, not because they want to, but because they have to. One bad edit can cascade into a mess that takes longer to fix than the original task would have taken manually.
How Staging Works
Mouse introduces a staging layer between the assistant's edit and your file. When the assistant uses batch editing (or any edit with staging enabled), changes are held in memory, not written to disk. At that point, the assistant has several options:
- Save: commit all staged changes to disk
- Cancel: discard everything and leave the file untouched
- Review: inspect the staged changes against the original file
- Refine: make additional edits to the staged content without starting over
This isn't a physical UI element; there's no dialog box or panel that appears on screen. It's a state that the assistant enters after staging changes, where every Mouse tool response includes contextual reminders about the pending changes and available next steps. The assistant knows at each turn that it still needs to commit or discard its staged work.
Why This Matters
Agents Verify Their Own Work
The staging workflow encourages the assistant to check its work before saving. After staging a batch of edits, Mouse doesn't celebrate; it reminds the assistant to review the changes and provides the syntax to do so. This nudge often allows assistants to catch mistakes in their own staged output and roll them back before they ever reach your file.
The key insight: the assistant verifies its own work, not just the developer. This reduces the burden on developers to manually review every line, because the assistant has already had an opportunity to catch its own errors.
Nothing Hits Your File Until It's Right
All staged changes are held in memory. Your original file remains untouched on disk until the assistant explicitly saves. If the assistant's edits are wrong (partially or entirely), it can refine or cancel without your file ever being modified.
This provides a critical safety net. File corruption from sweeping AI edits (the kind that forces developers to restore from Git) simply doesn't happen when changes are staged and reviewed before being committed.
Iterative Refinement Without Recalculation
One particularly powerful feature of staging is that all line numbers reference the original file state, regardless of how many edits have been staged. Suppose the assistant needs to make changes at lines 10, 20, and 95 of a 100-line file, and each change replaces one line with three lines. The assistant can stage the edits at lines 10 and 20 in the first pass, then refine the staged changes by inserting another edit at line 95, all without ever recalculating line numbers.
This eliminates the cascading line-drift problem that plagues sequential editing with built-in tools, where each edit shifts all subsequent line numbers and the agent must continuously recalculate positions.
Self-Correction in Practice
Partial Success
The assistant stages 25 edits, and 24 succeed. The 7th edit fails. Perhaps the line range overlaps with another edit, or the find text doesn't match. Mouse responds with details on exactly which edit failed and why, along with guidance on next steps.
The assistant doesn't need to start over. It can:
- Adjust the failed edit's placement if the content was correct but the position was wrong
- Refine the failed edit's content if the position was correct but the replacement text was wrong
- Unstage the failed operation and re-stage a corrected version
All other staged edits remain intact. The assistant iterates on the single problem until all 25 edits are staged correctly, then saves everything together.
Catching Erroneous Output
Even when all edits stage successfully, Mouse reminds the assistant to review the result before saving. This matters most in the hardest scenario to detect: a "200 OK" response that contains incorrect output.
The assistant reads the staged file content, notices that one of its replacements introduced a subtle error, and unstages that specific operation. It re-stages a corrected version, reviews again, and only then saves. The user never sees the mistake because the assistant caught and fixed it before the changes reached the file.
What This Looks Like in Practice
Staged batch with review:
"Make these 5 changes to the configuration file. Stage them all and review before saving."
The assistant stages all 5 edits, inspects the staged result, confirms everything looks correct, and saves.
Self-correction after partial failure:
"Update these 12 import paths across the codebase."
The assistant stages all 12 updates. Two fail due to unexpected file content. Mouse identifies the failures, the assistant adjusts those two operations, and then saves the complete batch. All 12 changes committed together.
Review and rollback:
"Refactor the error handling in
server.js. Use batch editing so you can see the changes before they're applied."
The assistant stages the refactoring edits, reviews the result, decides that one change is too aggressive, unstages that operation, and saves the remaining edits.
The Trust Equation
Staging means the developer reviews targeted diffs, not full-file replacements. When something goes wrong, the assistant catches it before the file is modified.
For the technical details of how batch editing and staging work under the hood, see Batch Editing and the Dialog Box.
Next Steps
The last best practice takes staging and precision into a domain every developer deals with daily: Updating Tests with Precision.