Safe Edit Guide

Prevent file corruption during LLM-assisted editing with our backup-first strategy. This guide covers the complete workflow for safely modifying files using AI Toolbox tools.

📋 Table of Contents

Overview
Why Backup First?
Quick Start
Complete Workflow
Emergency Recovery
Best Practices

Overview

The Safe Edit Guide provides a systematic approach to modifying files when working with AI assistants. By creating backups before making changes and verifying after editing, you can prevent data loss and recover from mistakes quickly.

⚡ Automatic Rollback (v1.5.12+)

Starting with version 1.5.12, four file-editing tools include built-in .bak rollback on write failure:

replace_text_in_file — restores original if atomic write fails
insert_at_line — same automatic restore
append_file — same automatic restore
delete_lines_in_file — same automatic restore

What this means: If a write operation fails (disk full, permissions issue, etc.), the tool automatically copies the .bak backup back to the original file and returns an error. No manual intervention needed for common failure scenarios. The backup is still created before any modification attempt, so it's always available as a safety net even if the write succeeds.

Key Principles

Backup first — Always create a backup before editing
Verify after — Check that edits applied correctly
Clean up later — Remove backups when satisfied with results

Why Backup First?

LLM-assisted file editing can introduce unexpected changes:

Syntax errors from incomplete code generation
Accidental deletions or overwrites
Encoding issues with special characters
Inconsistent formatting across files

Backups provide a safety net that allows you to recover quickly if something goes wrong.

Quick Start

Step 1: Backup Before Editing

This creates src/index.ts.bak with the original content.

Step 2: Make Your Edits

Use AI Toolbox tools to modify files as needed:

save_file for complete file replacement
replace_text_in_file for targeted string replacements
insert_at_line for adding lines at specific positions
delete_lines_in_file for removing line ranges

Step 3: Verify After Editing

This compares your edited file against the backup and reports differences.

Step 4: Clean Up When Satisfied

Complete Workflow

Phase 1: Preparation (Before Editing)

1. Identify Files to Edit

List all files that will be modified during the session:

2. Create Backup of Each File

For each file you plan to edit, create a backup:

Each backup is stored as {filename}.bak in the same directory.

3. Verify Backups Were Created

Phase 2: Editing (While Working)

Use AI Toolbox Tools for File Modifications

Option A: Replace entire file content

Option B: Replace specific text

Option C: Insert lines at specific position

Monitor for Errors During Editing

Watch for these common issues during editing:

Syntax errors in generated code
Missing closing brackets or quotes
Incorrect indentation
Broken imports or references

Phase 3: Verification (After Editing)

Run Verification Checks

For each file you edited, verify the changes:

Manual Verification Steps

Open the edited file in your editor
Check syntax highlighting — red underlines indicate problems
Review the diff between original and edited versions:

Phase 4: Cleanup (After Verification)

Remove Backups When Satisfied

Emergency Recovery

If Something Goes Wrong After Editing

Option 1: Restore from Backup Immediately

If you notice problems right after editing, restore the backup before doing anything else:

This replaces src/index.ts with the content from src/index.ts.bak.

Option 2: Use Git as Backup (If Available)

If you're using version control, revert changes through Git:

Option 3: Manual Recovery Steps

If automated tools aren't available, manually restore from backup:

Locate the backup file (e.g., src/index.ts.bak)
Read the backup content:
Replace current file with backup content:

Best Practices

1. Edit One File at a Time

Always complete and verify changes to one file before moving to the next:

2. Use Small, Targeted Changes

Break large edits into smaller, manageable changes:

3. Verify Before Moving On

Always verify each file before proceeding to the next:

4. Keep Backups Until Session Ends

Don't delete backups until you're certain the session is complete and stable:

📋 Checklist for Safe Editing

Before starting any editing session, follow this checklist:

Identified all files that will be modified
Created backups for each file (*.bak files)
Verified backups exist and are readable
Planned edits in small, incremental steps

🆘 Troubleshooting

Problem: Backup File Not Found

Symptom: node scripts/safe_edit.js verify src/file.ts reports "Backup not found"

Solution: The backup file doesn't exist. Create it first:

Problem: Verification Shows Unexpected Differences

Symptom: File diff shows changes you didn't intend

Solution:

Review the diff carefully to understand what changed
If incorrect, restore from backup immediately:
Try smaller, more targeted edits next time

Problem: Multiple Backups Accumulating

Symptom: Too many .bak files cluttering directories

Solution: Clean up old backups:

The Safe Edit Guide complements these AI Toolbox tools:

Tool	Purpose	Reference
`save_file`	Write file content with atomic operations	TOOLS_REFERENCE.md
`replace_text_in_file`	Replace specific strings in files	TOOLS_REFERENCE.md
`insert_at_line`	Insert content at specific line numbers	TOOLS_REFERENCE.md
`delete_lines_in_file`	Remove line ranges from files	TOOLS_REFERENCE.md
`file_diff`	Compare two files side by side	TOOLS_REFERENCE.md

📝 Notes

This guide assumes you're using AI Toolbox tools for file modifications.
Always test your edits in a non-production environment first when possible.
Keep backups until you're confident the changes are correct and complete.
For large projects, consider using Git for additional version control safety.

🆘 Getting Help

If you encounter issues with the Safe Edit workflow:

Check this guide's troubleshooting section
Review the backup files to understand what changed
Restore from backup if needed
Try smaller, more targeted edits next time

ai-toolbox