Execution Modes

​

Overview

type ExecutionMode = 'plan' | 'build' | 'yolo'

const EXECUTION_MODE_CYCLE: ExecutionMode[] = ['plan', 'build', 'yolo']

​

Plan Mode

// CLI flag: --permission-mode plan

​

What Plan Mode Does

• Read files: AI can read any file in your worktree
• Run read-only commands: git status, ls, cat, etc.
• Propose plans: AI creates detailed implementation plans
• Cannot modify: No file edits, no destructive commands

​

When to Use Plan Mode

​

Plan Mode Workflow

1. Send a message describing what you want to accomplish
2. AI explores the codebase (reads files, checks git status, etc.)
3. AI writes a plan to a file (usually .ai/todo.md or similar)
4. Plan appears in chat with an Approve button
5. Click Approve to switch to build mode and execute
6. Or stay in plan mode and refine the plan further

​

Exit Plan Mode Tool

// AI calls: ExitPlanMode tool
export function isExitPlanMode(toolCall: ToolCall): boolean {
  return toolCall.name === 'ExitPlanMode'
}

• Approve: Switch to build mode and run the plan
• Reject: Stay in plan mode for more discussion

​

Build Mode

// CLI flag: --permission-mode acceptEdits

​

What Build Mode Does

• Auto-approve file edits: AI can create, edit, and delete files without prompts
• Requires approval for commands: git commit, npm install, etc. need confirmation
• Safer than yolo: Prevents accidental destructive commands
• Faster than plan: Implements without waiting for approval on every edit

​

When to Use Build Mode

​

Build Mode Permissions

• Read - Read any file
• Edit - Edit files
• Write - Create new files
• Bash (read-only commands) - ls, cat, git log, etc.

• Bash (destructive commands) - rm, git commit, npm install, etc.
• Web tools - WebFetch, WebSearch (unless enabled in settings)

​

Model Override (Build Mode)

interface AppPreferences {
  build_model: string | null         // null = use session model
  build_backend: string | null       // null = use session backend
  build_thinking_level: string | null // null = use session thinking
}

​

Yolo Mode

// CLI flag: --permission-mode bypassPermissions

​

What Yolo Mode Does

• Auto-approve everything: All tools run without prompts
• Maximum speed: No interruptions, no confirmations
• Maximum risk: AI can accidentally delete files, commit unwanted changes, etc.
• Best for trusted workflows: When you’re confident in what the AI will do

​

When to Use Yolo Mode

​

Safety Tips for Yolo Mode

1. Review changes after: Check git diff before pushing
2. Use in isolated worktrees: Don’t yolo on main branch
3. Start with plan mode: Let AI write a plan, then approve with yolo
4. Set model overrides: Use a cheaper model for yolo to reduce cost

​

Model Override (Yolo Mode)

interface AppPreferences {
  yolo_model: string | null         // null = use session model
  yolo_backend: string | null       // null = use session backend
  yolo_thinking_level: string | null // null = use session thinking
}

​

Execution Mode Indicators

• Plan: Blue border, read-only badge
• Build: Yellow border, “Auto-edit” badge
• Yolo: Red border, “Full auto” badge

interface ChatMessage {
  execution_mode?: ExecutionMode
}

​

Mode Cycling (Shift+Tab)

Plan → Build → Yolo → Plan → ...

export const EXECUTION_MODE_CYCLE: ExecutionMode[] = ['plan', 'build', 'yolo']

​

Execution Mode Persistence

interface Session {
  last_run_execution_mode?: ExecutionMode
}

​

Permission Denials

interface PermissionDenial {
  tool_name: string            // e.g., "Bash"
  tool_use_id: string
  tool_input: unknown          // Command or parameters
  rpc_id?: number              // Codex JSON-RPC ID
}

interface Session {
  pending_permission_denials?: PermissionDenial[]
}

• Approve: Run this command
• Deny: Skip this command
• Approve All: Approve this pattern for the session

​

Session-Scoped Approved Tools

// Chat store state
approvedTools: Record<string, string[]>

// When user clicks "Approve All", the tool pattern is added:
chatStore.addApprovedTool(sessionId, 'Bash:git commit')

// Future commands matching this pattern auto-approve

​

Web Tools in Plan Mode

interface AppPreferences {
  allow_web_tools_in_plan_mode: boolean  // Default: true
}

​

Best Practices

​

Recommended Workflow

1. Start in Plan Mode
   • Describe your goal
   • Let AI explore and plan
   • Review the proposed plan
2. Approve to Build Mode
   • Click “Approve” on the plan
   • AI implements automatically
   • Commands still require approval
3. Use Yolo for Cleanup
   • After main work, switch to yolo
   • Let AI run linters, formatters, tests
   • Review changes before pushing

​

When to Skip Plan Mode

• Quick fixes: Typo corrections, simple bugs
• Repetitive tasks: Formatting, renaming across files
• Trusted prompts: You know exactly what will happen

​

When to Use Plan Mode

• Complex changes: Multi-file refactors, new features
• Unfamiliar code: Exploring new projects or libraries
• High risk: Changes that could break production
• Learning: Understanding how something works

​

Comparison Table

​

Related