Understand permission modes in Claude Code

Link copied

Attach video time

Every time Claude Code wants to edit a file, it goes through a permissions process. The idea is that something needs to approve any changes that are made.

The only question here is who does the approving. Does the AI do it for you, or do you do it? So there are four permission modes available that do their best to answer this question.

Toggling between permission modes

If we go ahead and press Shift+Tab, you'll notice that the little line under your prompt changes. This is called the mode indicator, and it tells you what mode is currently active.

If you keep pressing Shift+Tab, you'll cycle through all of the different modes:

⏸ manual mode on
⏵⏵ accept edits on
⏸ plan mode on
⏵⏵ auto mode on

This includes manual mode, accept edits, plan mode, and auto mode. Let's walk through each one of these.

Manual

Manual mode actually used to be called default mode, and it was the mode that came with Claude Code when it initially shipped. In this mode, you need to approve every action that Claude wants to do.

This means every time it tries to edit a file or run a command, it will stop and ask for your approval before the action is carried out. You'll need to approve absolutely everything.

Claude Code will still be able to read all of your code freely, because without that, nothing here really works. But it will stop on every edit and every command it wants to carry out until you tell it "yes."

Since the first version of Claude Code was published, the AI models have gotten tremendously better, and you're now able to pretty much trust their edits. However, if you are just getting started with Claude Code (which you likely are), you'll probably want to start out with manual mode enabled. This gives you a chance to see how the AI thinks and works, and to review all code edits as they happen right in your terminal.

If you don't trust the AI, this should relieve some of your concern, because you're actually reviewing absolutely everything in this mode -- there's no guessing about what the AI is doing. And if you don't like one of its suggestions, you can say "no," push back, and tell it what to change.

Accept edits

In accept edits mode, all file edits are pre-approved. This means that Claude Code will change files any files in your project that it wants without asking you. This is the first step beyond manual mode, and you can move to it once you get a feel for how Claude Code works.

Note that if it tries to run any external commands, such as npm install, git push, or anything else, it will still stop and ask for your approval.

So the "can I edit this file?" prompt disappears. But your review moves out of the terminal and into git diff.

To be honest, this is a really good mode too, because even if you don't fully trust the code that the AI is writing, you'll get a chance to review it before anything is even committed. So you can actually talk to it and push back, and tell it how to change or morph the code into the format or style that you want.

Auto

The next mode in the cycle is plan mode, but let's skip over that and talk about auto mode first.

It can be hard to distinguish what the difference is between accept edits mode and auto mode, but there is one big difference. Both of these modes let Claude Code edit files in your project without asking you, but the difference comes down to how they run commands.

Remember that with accept edits mode, you approve all the commands. But in auto mode, every command goes through a sort of classifier before it runs. This lets normal work through, such as pushing code to a branch within a repo that you're already in, or any sort of read-only request like git log. But it tries to block anything that may hurt you, such as git push --force, or specific curl or bash commands, or anything that could throw a wrench into your workflow, like discarding uncommitted changes.

Auto mode is now the mode Claude Code starts in by default, so just be aware of this when you start.

Plan

The final mode to talk about is plan mode, and this is sort of a Frankenstein mode, because it really isn't about more approval or less approval. It's more about "let's create a plan to do something before we actually do it".

Claude Code will dispatch explorer sub-agents that read your codebase, and then it'll write up a plan of what it intends to do. So while you are in this mode, no files will actually be edited or changed. This gives you time to read and go over the plan, make changes to it, or approve or deny it. And after you approve it, it'll toggle back to one of the other modes to carry out the actual work where edits will be made.

If you are running Claude Code out of the box without any skills or plugins, this is absolutely the mode I would recommend starting with, especially if you are writing features or functionality of any substance. This is because the AI will typically do a much better job if it comes up with a plan first before it edits anything -- just like us humans in real life do as well. You’ll be spending more time up-front creating the plan, but far less time with changing edits that shouldn’t have happened in the first place.

Also, because all of coding is moving upstream toward the solution architecture level because of advancements with AI, you should absolutely try to be more and more comfortable creating plans and defining the architecture, than spending time writing, reviewing or editing code at this point.

Which mode and when?

To reiterate when to use each mode...

Manual to learn how the AI edits code, or within highly restrictive environments where everything needs your manual approval.

Accept edits when you want Claude Code to code things up for you, but want additional control over when it executes external commands.

Auto when you want to execute a plan or carry out quick tasks or bugfixes that are easy to apply, with additional autonomy given to the agents to run external commands.

Plan for features or asks of any substance, which is essentially everything besides minor changes or simple bugfixes. Do your best to spend most of your time in this mode.

Bypass permissions

There is one more mode we haven't talked about yet, called bypass permissions. It's a mode that gives way more power and autonomy to the AI.

This is a mode where absolutely no one approves anything. Every edit, command, and lookup is carried out by the AI without a single prompt.

You can get access to this mode by exiting out of Claude Code, and restarting it with the --dangerously-skip-permissions flag. And after starting it with this command, you will see a "bypass permissions mode" status indicator to tell you that this mode is now active.

Bypass permissions mode was primarily designed to be used within containers and throwaway environments, and really wasn’t ever meant to be run on your own machine.

That said, I've had some real success running this bypass permissions mode when coupled with a custom AI harness -- but it's definitely beyond the scope of this course, and you need to be extremely careful when running this mode.

My advice is to ignore this mode on your machine and stick with one of the other modes, so nothing destructive winds up happening to your machine. But if you'd like to learn more about running AI harnesses coupled with bypass permissions mode so you can code things up 10x faster, be on the lookout for my related course on this topic.