Cross-File Refactors and Repeated Edits

The Problem

Real-world refactoring rarely involves a single file. Renaming a function means updating the export in its source file and every import statement that references it across the codebase. Changing an API response shape means updating the handler, the tests, and every consumer. Adding a configuration key means updating the schema, the default values, and every reference.

With built-in tools, each file edit is a separate, sequential operation. The agent makes one string replacement, then the next, then the next. If any single replacement fails (wrong whitespace, ambiguous match, unexpected file content), the codebase is left in a partially updated state. Some files have the new name while others still reference the old one.

There is no atomicity, no rollback, and no way to review the full set of changes before they hit your files.

What Goes Wrong Without Atomicity

Partial updates. A developer asks their assistant to rename an exported function across 7 files. The agent makes it through 5 files before a string replacement fails on file 6 due to an extra trailing space. Now the codebase has the new function name in 5 files and the old name in 2. The developer must identify which files were updated and which weren't, then manually fix the remaining ones.

Sequential drift. Each file edit happens in isolation. The agent reads file 1, makes its change, reads file 2, makes its change. If the change in file 1 was wrong (say, it matched an incorrect import line), the agent has already moved on. There's no mechanism to review the full batch before committing.

Repeated patterns. A developer asks the agent to add a logging statement to 12 handler functions across 6 files. Each insertion is a separate operation, and the agent must re-derive the insertion point for each one. If the pattern varies slightly between files, some insertions succeed while others land in the wrong location, and the developer has no way to review them as a group.

How Mouse Handles Cross-File Edits

Mouse's batch editing supports multi-file operations in a single atomic call. Each operation in the batch can specify its own file path, and all operations are staged together.

• Atomicity. All changes succeed or the entire batch rolls back.
• Single-pass review. The agent can inspect the staged changes across all files before committing. If any change looks wrong, it can be adjusted or unstaged without affecting the others.
• Original-state line numbers. Every operation references the original file, so the agent can make further edits based on the user's original prompt and prior line references; no recalculation needed, even when multiple edits target the same file.

What This Looks Like in Practice

Renaming across files:

"Rename calculateTax to computeTax in the source file and update every import that references it. Stage all changes so I can review before saving."

The agent uses batch editing to stage the export rename and all import updates in a single operation. Each file edit specifies its own path. The agent reviews the full set of staged changes, verifies every import was caught, and commits them in one pass by calling save_changes for each file.

Coordinated insertions:

"Add logger.info('Handler invoked', { requestId }) as the first line of every async handler function in the src/handlers/ directory."

The agent identifies each handler function across the directory, stages an insert operation for each one, and reviews the batch before committing. If one insertion lands in the wrong position, the agent adjusts that single operation without re-staging the others.

Repeated pattern application:

"Add the aria-label attribute to every <button> element in the 8 component files under src/components/ui/. Use the button's existing text content as the label value."

Each file gets a targeted replacement, and all replacements are staged together for review. The diff across all 8 files shows exactly and only the attribute additions.

Prompting for Cross-File Work

The key phrase is "stage all changes"; this tells your assistant to use batch editing with review:

"Make these changes across all affected files. Stage everything so I can see the full diff before committing."

"Update the import paths in every file that references the old module name. Do it atomically. I don't want a partial rename."

Your assistant handles the multi-file coordination. You review the complete batch, and nothing hits your files until you're satisfied.

Next Steps

Cross-file edits become especially powerful when combined with staged review and self-correction. The next page covers the workflow that makes this all safe: Staged Changes, Review, and Self-Correction.