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; manual is an alias for it from v2.1.200
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 modes 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 settings file is the only way in.

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. Conversations the VS Code extension starts read only user, managed and --settings values; the two project files do not reach them.

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.

Two modes are exceptions to everything above. auto and, from v2.1.257, bypassPermissions are read from ~/.claude/settings.json, --settings and managed settings, never from the two project files, where the other four modes all work. Set them 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; a bypassPermissions there starts the session in Manual. It is one of five places a mode you set is dropped without saying so.

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, and from v2.1.257 neither does bypassPermissions. These are the two modes with a documented scope restriction; what happens instead differs between them.

Assuming permission rules override the same way defaultMode does. They do not, and the two are easy to confuse because both get called precedence. This page is about *file* precedence, meaning which settings file wins when several set a mode. Rules follow a separate order once loaded: deny → ask → allow, first match wins, regardless of which file each rule came from. So allow, ask and deny merge across scopes rather than replacing each other. A user-level deny blocks a project-level allow, and the reverse holds too. Only the mode itself follows the file 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.