Bypass Permissions in Project Settings Does Nothing

The annoyance

I put "permissions": { "defaultMode": "bypassPermissions" } in the project's .claude/settings.json so every session in that repo would start without the permission prompts. The JSON is valid. The key is the one the docs name. The session still opens in Manual, and nothing throws.

I had the usual suspects lined up. A stale CLI. A managed setting I had forgotten. Then I put the same object in ~/.claude/settings.json and the next terminal session started in bypass permissions. The project file had never been the lever.

This is the 2.1.257 sibling of auto in project settings. Before that version, project and local files could pin bypassPermissions. They cannot now, and the miss is silent, and the session starts in Manual.

What Anthropic actually says

From the official permission modes page, under “Which mode a session starts in”:

“If you set "auto" in .claude/settings.json or .claude/settings.local.json, the value doesn't take effect, and Claude Code then uses the built-in default rather than a defaultMode from ~/.claude/settings.json. If you set "bypassPermissions" in those two files, it doesn't take effect either, and the session starts in Manual mode. The other values apply from any settings file.”

Same page, on where a project file can still set the starting mode:

“Sessions you start in a terminal honor every value except auto and bypassPermissions; sessions the VS Code extension starts don't read project settings for the starting permission mode”

The settings troubleshooting note, under “A value you set is ignored”, is the version line:

“permissions.defaultMode values auto and bypassPermissions don't take effect from project or local settings; set them in user or managed settings instead, or pass --permission-mode for one session. Before v2.1.257, bypassPermissions took effect from any file.”

So two things follow. First, project and local settings are not ignored wholesale — they are ignored for auto and, from v2.1.257, for bypassPermissions. Second, the miss is not a fall-through to a user-level default. The session starts in Manual. User or managed settings still apply. The flag still applies: claude --permission-mode bypassPermissions, and --dangerously-skip-permissions is the documented equivalent. The VS Code extension never reads project settings for the starting permission mode.

The fix

The wrong shape is the one I keep finding in repos, and in .claude/settings.local.json as well. It is valid JSON. It is the documented key. From v2.1.257 it does nothing for bypassPermissions:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

Put the same object in the user file if you want every terminal session on this machine to start in bypass permissions, or put it in managed settings if that is the organisation lever:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

For one session, skip the files:

claude --permission-mode bypassPermissions

claude --dangerously-skip-permissions

If the project file is the right place, pin a value that actually applies there. Plan is the one I use when a repo should start by reading, not writing:

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

Prove it

Start a terminal session from the project with the wrong file in place. Confirm the status bar is Manual. Move the same JSON to ~/.claude/settings.json, or pass the flag once, and start again. If the VS Code conversation still opens in Manual, that is a different list: the extension does not read the project file for this, and bypass permissions there also needs the extension's own allow toggle.

Checklist

1. Confirm the bypassPermissions value sits in .claude/settings.json or .claude/settings.local.json. That is the silent miss from v2.1.257.
2. Move it to ~/.claude/settings.json, or to managed settings, if you want it as a default.
3. Or skip the files and start with claude --permission-mode bypassPermissions.
4. Do not expect a project file to pin this after v2.1.257. It used to. It does not now.
5. If you are in VS Code, stop looking at the project file for the starting mode. That surface has its own list.

Why it fails

I treat project settings as the place that wins. For every other defaultMode they do. For auto they never did, and from v2.1.257 they do not for bypassPermissions either, and they start the session in Manual instead of falling through to a user default. The JSON looks correct. Nothing throws. Same family as auto in project settings and permissions in ~/.claude.json — the file looks finished, and the documented field is a different one.

If you want to run this with other operators rather than on your own, we are doing that in the public Skool community, and that is https://www.skool.com/navaigate.

Sources

• Anthropic — Choose a permission mode
• Anthropic — Settings
• Auto in Project Settings Does Nothing
• Permissions in ~/.claude.json Are Ignored
• NavAIgate Skool community