Overview
Approval modes control when the AI must request permission before executing tools. They balance safety, control, and automation to match your workflow and trust level.The Four Modes
Plan
Read-only analysis modeAI can analyze and reason but cannot modify files or run commands.
Default
Balanced mode (recommended)Prompts for approval before file edits and shell commands.
Auto Edit
Automated editingAuto-approves file edits but still prompts for shell commands.
YOLO
Full automationAuto-approves all actions. Use with caution!
Plan Mode
Best for: Code review, architecture planning, learning about a codebaseWhat’s Allowed
- Allowed
- Blocked
- Read files
- Search code (glob, grep, ripgrep)
- List directories
- Analyze code structure
- Browse file tree
- Fetch documentation
- Reason and explain
Use Cases
Plan mode is perfect for read-only analysis where you want insights without any risk of changes.
Default Mode
Best for: Day-to-day development, learning while building, supervised automationApproval Flow
Your Decision
- Allow - Execute this one time
- Reject - Skip this tool call
- Allow All Edits - Auto-approve all future file edits
- Always Allow [command/tool] - Remember approval for this specific tool
What Requires Approval
| Tool | Requires Approval | Reason |
|---|---|---|
edit | Yes | Modifies files |
write_file | Yes | Creates/overwrites files |
bash | Yes | Executes commands |
mcp_tool | Yes (first use) | External tool |
read | No | Read-only |
glob | No | Search only |
grep | No | Search only |
ls | No | List only |
web_fetch | No | Read-only |
Example Session
Auto Edit Mode
Best for: Refactoring, code generation, automated documentationWhat’s Auto-Approved
- Auto-Approved
- Still Prompts
- File edits (
edit) - File creation (
write_file) - File reads (
read) - Code search (
glob,grep) - Directory listing (
ls) - Documentation fetching
Use Cases
Safety Features
Even in auto-edit mode:- You can press
Ctrl+Cto cancel mid-stream - Changes are applied incrementally (visible in real-time)
- Git integration shows diffs automatically
- Shell commands still require explicit approval
YOLO Mode
Best for: Trusted environments, CI/CD, automation scripts, rapid prototypingWhat’s Auto-Approved
Everything. No prompts, no confirmations.- File operations (read, write, edit, delete)
- Shell commands
- MCP tools
- System operations
- Network requests
- All other tools
Use Cases
- CI/CD
- Automation
- Rapid Prototyping
Safety Considerations
Cancellation
Even in YOLO mode, you can:- Press
Ctrl+Cto abort immediately - Use
--max-turnsto limit iterations - Set timeouts to prevent runaway processes
Switching Modes Mid-Session
Interactive Mode
- Pending approvals are auto-resolved based on new mode
- In-flight operations continue with original mode
- Future operations use the new mode
Headless Mode
Mode is set at startup and cannot be changed:Configuration
Settings File
Environment Variable
Per-Tool Configuration
You can customize approval behavior per tool:Advanced Features
Persistent Approvals
When you choose “Always Allow”, approvals are saved:Conditional Approval
Configure approval based on context:Approval Hooks
Run custom logic before approval:Comparison Table
| Feature | Plan | Default | Auto Edit | YOLO |
|---|---|---|---|---|
| Read files | ✓ | ✓ | ✓ | ✓ |
| Search code | ✓ | ✓ | ✓ | ✓ |
| Edit files | ✗ | Prompt | ✓ | ✓ |
| Shell commands | ✗ | Prompt | Prompt | ✓ |
| MCP tools | ✗ | Prompt | Prompt | ✓ |
| Delete files | ✗ | Prompt | Prompt | ✓ |
| Safety level | Highest | High | Medium | Lowest |
| Automation | ✗ | Limited | Good | Full |
| Best for | Review | Development | Refactor | CI/CD |
Best Practices
Start with Default
Start with Default
Begin with
default mode to understand what the AI wants to do. Graduate to higher automation as you build trust.Use Plan for Reviews
Use Plan for Reviews
When reviewing code or learning, use
plan mode to explore safely without accidental changes.Auto-Edit for Bulk Changes
Auto-Edit for Bulk Changes
Switch to
auto-edit for large refactorings where you’d approve every edit anyway.YOLO in Containers
YOLO in Containers
Use
yolo mode in Docker containers or VMs where mistakes are isolated and easily reversed.Git is Your Safety Net
Git is Your Safety Net
Always commit your work before switching to auto-edit or yolo modes. You can revert if needed.
Test in Plan First
Test in Plan First
For complex prompts, run in
plan mode first to verify the AI understands correctly before allowing execution.Troubleshooting
Tools are denied in headless mode
Tools are denied in headless mode
Problem: In headless mode with
default, tools requiring approval fail.Solution: Use --approval-mode yolo or --approval-mode auto-edit for headless automation.Too many approval prompts
Too many approval prompts
Problem: Constantly approving the same operations.Solution:
- Choose “Always Allow” for trusted operations
- Switch to
auto-editfor file operations - Add commands to
alwaysAllowin settings
AI isn't making necessary changes
AI isn't making necessary changes
Problem: In
plan mode, AI can’t complete the task.Solution: Switch to default or higher. Plan mode is read-only by design.Can't revert approval mode
Can't revert approval mode
Problem: Stuck in YOLO mode.Solution:
- In interactive:
/approval-mode default - In headless: Restart with
--approval-mode default - Check settings file for persistent configuration
Next Steps
Interactive Mode
Use approval modes in the interactive UI
Headless Mode
Automate with YOLO mode
Session Commands
Learn the /approval-mode command
Configuration
Configure approval settings
