.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Claude Code asks before it touches your files or runs a command, and the dial that controls how often it asks is the permission mode. There are six modes now, up from the original three, and choosing the right one per task decides how a session feels: smooth and hands-off, or interrupted every forty seconds. I keep plan mode for anything structural and acceptEdits for routine edits, and the reasoning is below.
Everything here reflects the 2.1 line of Claude Code on macOS and Linux (my terminal lives on Ubuntu 24.04). If the CLI itself is new to you, start with the guide on how to use Claude Code and come back; this article is only about permissions.
The six permission modes
The official permission modes documentation keeps a table of what runs without asking in each mode. Condensed, with my notes:
- default, labeled Manual in the interface: only reads run freely. Edits prompt, shell commands prompt, network access prompts. The config value stays
default, though recent builds also acceptmanualas an alias. - acceptEdits: file edits inside your working directory go through without asking, along with everyday filesystem commands like
mkdir,mvandcp. Other shell commands still prompt. This is my daily driver, withgit diffas the review step afterward. - plan: read-only until you approve a written plan. The rest of this article leans on it, so details below.
- auto: a second model, the classifier, reviews each action in the background and waves through the routine ones. On Pro, Max and Team plans this is now the built-in starting mode in the terminal and VS Code.
- dontAsk: anything that would have prompted is denied instead. Made for CI, where nobody is around to answer, so the session never waits for input.
- bypassPermissions: everything runs, no questions asked. This is what the
--dangerously-skip-permissionsflag enables, and it gets a separate article because it deserves one.
Cycle modes with Shift+Tab
Press Shift+Tab during a session to cycle: default, then acceptEdits, then plan, then back around. auto joins the cycle when your account supports it, and bypassPermissions only appears when the session was launched with a flag that enables it. dontAsk never shows up in the cycle at all; the only way in is claude --permission-mode dontAsk. The status bar always names the active mode ("plan mode on", "accept edits on"), so a quick glance settles any doubt about where you are.
What plan mode blocks
Plan mode tells Claude to research and propose before doing. It reads files and greps the codebase, runs exploratory commands, then writes up a plan, but edits to your source stay blocked until you approve that plan. On accounts with auto mode available, the classifier quietly reviews the exploration commands during planning so you aren't prompted for every directory listing; without it, commands outside the built-in read-only set prompt like they would in Manual.
When the plan lands you get a small menu: approve and let it run (in auto mode or with auto-accepted edits, depending on your account), approve but review each edit by hand or send the plan back with notes. Approving exits plan mode and execution starts immediately. Two touches worth knowing: Ctrl+G opens the proposed plan in your text editor so you can rewrite sections directly before agreeing, and accepting a plan names the session automatically, which pays off later in the resume picker. You can also prefix a single prompt with /plan instead of switching the whole session over.
When to use plan mode
My rule: plan mode whenever a wrong first move is expensive to unwind. Multi-file refactors qualify, because the plan exposes the model's mental map of the code before anything moves, and a bad map is far cheaper to correct in prose than in twelve half-edited files. Codebases I don't know yet get the same treatment, since reading the plan doubles as my own orientation. And anything touching a database migration goes through plan mode without exception; I want the rollback story in writing before a single line changes.
Where it's ceremony: one-line fixes, renames, a missing import. A full planning round for something you'd approve in two seconds is pure overhead, and Manual or acceptEdits handles those better. Pure question-answering sessions don't need it either, because reads never prompt in any mode. And when a feature is big enough that even a plan feels thin, the heavier Requirements, Design and Tasks flow in the spec-workflow guide picks up where plan mode stops.
Start Claude Code in plan mode
For a single session, pass the flag:
claude --permission-mode planTo make it stick, set the default in a settings file:
{
"permissions": {
"defaultMode": "plan"
}
}Put that in ~/.claude/settings.json for every session on the machine or in a project's .claude/settings.json so one risky repo always starts read-only, which is exactly what I do for the repo holding our schema migrations. Project values outrank your user file when both set a mode. One quirk from the docs: an auto value is ignored in project-level settings files, so that particular default only takes effect from your user file.
The opusplan model alias
Plan mode pairs well with the opusplan alias, set with /model opusplan or --model opusplan. It splits the work between models: Opus does the thinking while you're in plan mode, then Sonnet takes over for execution once the plan is approved. Planning is where the deeper model earns its cost, since a sharper plan tends to mean fewer correction rounds later, and on subscription plans Opus usage is tracked separately, so spending it only on planning stretches your weekly allowance. The model configuration docs list the other aliases if you want to mix differently.
Allow and deny permission rules
Modes set the baseline; rules carve out exceptions. Both live under permissions in settings.json:
{
"permissions": {
"allow": [
"Bash(npm run test *)",
"Bash(git diff *)"
],
"deny": [
"Read(./.env)",
"Bash(git push *)"
]
}
}The allow list pre-approves commands so they run without prompting even in Manual mode, which is how you make default mode livable: approve your test runner and your linters once, keep prompts for everything else. The deny list blocks outright, and deny wins any collision with an allow entry. Rules merge across scopes (user, project and local settings), so a team can ship a project-level deny on .env reads while you keep personal allows at home.
Two details surprised me here. Deny rules hold in every mode, including bypassPermissions, which makes them the one guardrail that survives everything. And entering auto mode drops blanket allow rules like Bash(*) for the duration, restoring them when you leave, so a lazy wildcard can't hand the classifier a blank check. For logic the patterns can't express, a PreToolUse hook from the Claude Code hooks system can approve or block individual calls with a script.
Plan mode and resumed sessions
Resuming with claude --continue or --resume brings back the conversation and the model, plus the permission mode you were in, with two exceptions: plan and bypassPermissions are never restored. A session you left in plan mode wakes up in your default mode instead. That bit me once; I resumed after lunch, typed "go ahead" and got a Manual-mode edit prompt instead of the plan flow I expected. Harmless in that direction, and deliberate: the two modes that change your risk envelope the most are the two you have to re-select on purpose. The full restore behavior is covered in the article on Claude Code sessions.
Plan mode is one end of the dial. The other end, running with every check switched off, has different trade-offs and a couple of built-in guardrails of its own, and I've written up what --dangerously-skip-permissions does separately.
