How do I set a default permission mode for Claude Code?

{
  "permissions": {
    "defaultMode": "plan"
  }
}

In ~/.claude/settings.json or .claude/settings.json

Answer

Add permissions.defaultMode to a settings.json file. Use ~/.claude/settings.json for a personal default across all projects, or .claude/settings.json to share one with your team. Managed settings win over local, local over project, and project over user, so check which file is actually in effect before debugging a mode that will not stick.

What it does

permissions.defaultMode sets the mode a session starts in, so you do not pass --permission-mode every time.

{
  "permissions": {
    "defaultMode": "plan"
  }
}

The values it accepts:

default — Manual mode, asks before most actions
acceptEdits — file edits and seven

filesystem commands run without asking

plan — Claude explores and proposes, edits stay

blocked until you approve

auto — a classifier reviews actions in your place
bypassPermissions — no checks at all
dontAsk — auto-denies anything not

pre-approved

All six work here. What sets dontAsk apart is that it never appears in the Shift+Tab cycle, so a running session cannot be switched into it.

The key lives in a settings.json file. Which file you choose decides who gets the setting and what overrides it.

When to use it

Pick the file by who should be affected. They are listed strongest first, because that is the order that decides who wins when two of them disagree:

.claude/settings.local.json — this project, only you; gitignored
.claude/settings.json — committed to the repository, shared with the team
~/.claude/settings.json — your default in every project

Two things outrank all three: a --permission-mode flag on the command line, and above that managed settings, the policy file an IT department deploys, which nothing you write can override.

The ordering surprises people: a personal default in your home directory is the weakest of the three, so any project you clone can quietly replace it.

Starting in plan mode is the most common use. Claude explores and proposes before it edits, which suits unfamiliar code.

When not to use it

Do not set bypassPermissions as a default. A per-session flag is a decision you make with the current task in mind; a default applies months later to work you have not thought about yet.

One mode is an exception to everything above. auto is read only from ~/.claude/settings.json and from managed settings — never from the two project files, where the other five modes all work. Set it in your user settings.

The failure mode is quiet and worth knowing: an auto in a project file does not fall through to the ~/.claude/settings.json default underneath it. It suppresses it, and the session starts in the built-in mode instead.

Example

A personal default of plan mode, in ~/.claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

A project default committed for the team, in .claude/settings.json:

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

A command-line flag still overrides the file for that session:

claude --permission-mode plan

Common mistakes

Editing the file that loses. ~/.claude/settings.json is the weakest of the files, so a project you cloned last week can quietly replace the default you set months ago. When a mode will not stick, work down the precedence order above and find the first file that sets one.

Expecting auto to work from a project file. It does not take effect there. This is the one mode with a documented scope restriction.

Assuming permission rules override the same way defaultMode does. They do not. allow, ask and deny all merge across scopes rather than replacing each other, so a deny in any file applies everywhere — a user-level deny blocks a project-level allow, and the reverse holds too. Only the mode itself follows the precedence above.

Committing a mode the team did not agree to. .claude/settings.json is shared. A default that suits your machine becomes everyone's starting point on their next pull.