ARCANALetting an AI agent edit your files requires trust. Arcana's file-edit guard makes that trust explicit: every file modification goes through a confirmation step where you see exactly what changed before it is applied.
The core problem with AI-assisted coding is that agents can make mistakes. They might edit the wrong file, apply a change that breaks the build, or modify code in a way that conflicts with your project's conventions. Without a guard, these mistakes happen silently. You discover them later, when the build fails or a test breaks, and you have to figure out what the agent changed.
The file-edit guard solves this by making every change visible before it happens. You see the diff. You approve the change. The agent cannot proceed without your say-so. This is not about distrusting the agent; it is about maintaining a human in the loop for irreversible actions.
How It Works
When the guard is active, the agent cannot silently modify files. Instead:
- The agent proposes a file edit
- Arcana shows a visual diff: lines removed in red, lines added in green
- You approve or reject the edit
- If approved, the edit is applied and a backup is created
This is not a suggestion system. The agent waits for your approval before writing anything to disk.
Guard Modes
Arcana offers three guard modes:
- Strict. Every file edit requires approval. No exceptions. Use this for production codebases or when you are learning what the agent does.
- Benign auto-allow. Safe edits (adding imports, formatting, whitespace changes) are auto-approved. Destructive edits (deleting files, overwriting logic) still require approval. This is the default.
- Off. No approval prompts. The agent edits freely. Use this only in sandboxed environments.
Rollback
Every approved edit creates a backup. If something goes wrong, you can roll back individual edits. These commands work identically on all platforms:
# See recent sessions
arcana history list
# Show details of a specific session
arcana history show --id
# Resume a previous session
arcana history resume --id Backups are stored in your Arcana home directory under .backups/. On Linux and macOS this is ~/.arcana/.backups/. On Windows it is %USERPROFILE%\.arcana\.backups\.
Visual Diffs
The diff display is designed for readability. It shows:
- File path and line numbers
- Context lines around changes
- Syntax-highlighted additions and deletions
- A summary of total changes (files modified, lines added/removed)
Choosing a Mode
The right guard mode depends on your context:
- Start with strict. When you first use Arcana, strict mode lets you see every change the agent makes. This builds trust and helps you understand the agent's behavior.
- Move to benign auto-allow. Once you trust the agent's judgment on routine changes, auto-allow reduces friction. You still see destructive edits, which are the ones that matter most.
- Consider off for sandboxes. If you are running Arcana in a container, a test environment, or a disposable workspace, off mode lets the agent work at full speed without approval overhead.
You can switch modes at any time with /guard strict, /guard auto, or /guard off in the TUI. The change takes effect immediately.
Integration with Governance
The file-edit guard is part of Arcana's broader governance system. It works alongside permission gates, approval routing, and the signal engine classifier. Together, these systems ensure that automated code changes are visible, intentional, and reversible.
The governance stack is designed so that no single system is responsible for safety. The signal engine classifies the risk. The permission system decides the policy. The file-edit guard provides the user interface. Each layer adds its own check, and the agent must pass all of them before a change reaches disk.