Permission Modes: From Manual to Bypass

Why Claude Pauses Before Acting

Every time Claude Code wants to edit a file, run a shell command, or make a network request, it faces a question: should it ask for approval or act immediately? The answer depends on your current permission mode. Permission modes are Claude Code's way of letting you dial in the right balance between oversight and autonomy for each context.

The modes aren't just convenience settings. They define the trust boundary for a session. A mode that prompts for every shell command is right when you're exploring a codebase you don't fully understand. A mode that approves everything immediately is right when Claude is running inside an isolated container as part of a CI pipeline. The same Claude, the same task, different context — different mode.

The Six Modes

Claude Code ships with six permission modes. They form a spectrum from most oversight to least:

The UI label "Manual" corresponds to the config value default. The CLI accepts manual as an alias. This distinction matters when you're writing settings files or passing --permission-mode flags.

Switching Modes

You can change modes at any point during a session without restarting. In the CLI, press Shift+Tab to cycle through available modes. The default cycle is: Manual → acceptEdits → plan. Auto mode joins the cycle when your account meets its requirements. bypassPermissions appears after you start with --permission-mode bypassPermissions or the --dangerously-skip-permissions flag. dontAsk is only available at startup via flag and never appears in the Shift+Tab cycle.

To start a session in a specific mode:

claude --permission-mode acceptEdits
claude --permission-mode plan
claude --permission-mode bypassPermissions

To set a persistent default for all sessions, add defaultMode to your settings file:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Note that defaultMode: "auto" is only respected from ~/.claude/settings.json (user settings). Claude Code ignores it in project or local settings files to prevent a repository from granting itself auto mode.

Accept Edits Mode in Practice

acceptEdits is the mode most developers settle into for day-to-day work. In addition to all reads, it auto-approves file creation and editing, plus common filesystem Bash commands: mkdir, touch, rm, rmdir, mv, cp, and sed. These also work with common process wrappers like timeout and nohup.

The key constraint: auto-approval only applies to paths inside your working directory or configured additionalDirectories. Paths outside that scope still prompt. This means Claude can freely edit your project files but can't silently touch your home directory or system paths.

Use acceptEdits when you want to review changes via git diff or your editor after the fact, rather than approving each edit inline. It's the right mode for most code-writing sessions.

Protected Paths

In every mode except bypassPermissions, writes to a set of protected paths are never auto-approved. These paths represent state you definitely don't want accidentally modified:

• Version control state: .git, .gitconfig, .gitmodules
• Shell configs: .bashrc, .zshrc, .profile, .envrc, and related files
• Package manager configs: .npmrc, .yarnrc, .pnpmfile.cjs
• Claude's own config: .claude directory (except .claude/worktrees)
• IDE configs: .vscode, .idea

In Manual, acceptEdits, and plan mode, writes to protected paths prompt you. In auto mode, they route through the classifier. In dontAsk, they're denied. In bypassPermissions, they execute immediately — which is why bypassPermissions belongs only in isolated environments where this is acceptable.

Layering Permission Rules on Top

Modes set the baseline, but you can layer more specific rules on top using permissions.allow, permissions.ask, and permissions.deny in your settings. These rules apply in addition to the mode, not instead of it. A deny rule blocks an action even in bypassPermissions mode. An allow rule pre-approves a specific tool pattern in any mode.

For autonomous workflows, the most useful pattern is using --allowedTools at startup to pre-approve exactly the tools a scripted run needs:

claude -p "Run the test suite and fix failures" 
  --allowedTools "Bash,Read,Edit"

This combines the precision of dontAsk with the specificity of an explicit tool list, making it ideal for CI invocations where you know exactly what Claude should and shouldn't do.

Choosing the Right Mode for Automation

For autonomous workflows specifically, the choice usually comes down to three options. Use auto mode when you want Claude to work unattended on a long task and trust the general direction — the classifier provides a meaningful safety layer while removing most permission prompts. Use bypassPermissions only inside isolated containers or VMs where there's no risk to your host system or production infrastructure. Use dontAsk in CI pipelines where you've pre-approved exactly the tools the job needs and want any deviation to fail rather than prompt.

The next lesson goes deep on auto mode specifically — how the classifier works, what it blocks by default, and how to tune it for your infrastructure.