PricingSign inDownload

Blog / claude code

Make Claude Code start in plan mode in one project

Set plan mode as the default for one project, check what it lets through, find the saved plans, and leave it for one session when you need to.

On this page
  1. How do I start one session in plan mode?
  2. How do I make plan mode the default for a project?
  3. What does plan mode still let through?
  4. Where do the plans go?
  5. How do I leave plan mode when I've read the plan?
  6. What about the other modes?
  7. When the plan needs someone else's yes
  8. Frequently asked questions
  9. How do I make Claude Code always start in plan mode?
  10. Can Claude Code run commands in plan mode?
  11. Where does Claude Code save plans?
  12. How do I get out of plan mode for one session?
  13. Try it with your team

Some repositories deserve a pause before any edit: the billing service, the database migrations, the code a client is about to audit. In those, you want Claude Code to read, think and write a plan, and change nothing until you say so. You can press Shift+Tab into plan mode at the start of every session, but the one time you forget is the time it matters.

The fix is a project setting, so every session in that repository starts in plan mode, for you and for everyone who clones it. We ran every command below with Claude Code 2.1.318 and git 2.43.

How do I start one session in plan mode?#

Pass the mode when you start:

bash
claude --permission-mode plan

The same flag works for a one-shot run with -p, which is how we tested everything in this post. We made a tiny repository with a bug in it:

bash
git init -q demo && cd demo
printf 'def add(a, b):\n    return a - b\n' > calc.py
git add . && git commit -qm init
claude -p --permission-mode plan "Fix the bug in calc.py."

Claude Code found the bug, wrote the fix and the check it would run, and stopped:

`calc.py` isn't fixed yet. Plan mode is on, so I haven't edited it.
The bug: `add(a, b)` in `calc.py` returns `a - b` instead of `a + b`.
The fix: change line 2 from `return a - b` to `return a + b`.

git status afterwards was empty. Nothing changed on disk.

How do I make plan mode the default for a project?#

Put it in the project's shared settings file, .claude/settings.json, and commit it:

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

From then on, a plain claude in that folder starts in plan mode. If the file already has a permissions block with allow or deny rules, add defaultMode next to them rather than starting a second block.

Use .claude/settings.local.json instead if the choice is only yours. That file is meant to stay out of git, so your teammates keep their own default. A team that wants every session in a sensitive repository to plan first should use the shared file, so the rule travels with the code.

What does plan mode still let through?#

Reading. With the project default set, we asked for a command that only reads, then one that writes:

bash
claude -p "Run git log --oneline and tell me the output"
claude -p "Run the shell command: touch made.txt"
ls

The first ran and answered with the commit. The second didn't run; Claude Code wrote a plan to run it and stopped, and ls showed only calc.py. That is the behaviour you want: the agent can look around the project, read files and run commands that only report, so its plan is based on the real code. It can't edit files or run commands that change things.

Two things to keep in mind. Plan mode decides what the agent may do, not what it believes it may do, so check it on your own setup with a harmless write like the touch above after you change settings. And a permission mode is not a security boundary for secrets: if a file must never be read, add a deny rule for it as well. Our post on keeping Claude Code away from .env files has those rules.

Where do the plans go?#

Claude Code saves each plan as a Markdown file in your home folder:

bash
ls ~/.claude/plans
head -5 ~/.claude/plans/fix-the-bug-in-elegant-quill.md
# Fix bug in calc.py

## Context
`calc.py` contains a single function, `add(a, b)`, which returns `a - b` instead of `a + b`.

The file name comes from the request plus two random words, and the path is printed at the end of the plan. That makes a plan easy to keep: paste it into a pull request description, send it to whoever owns the code, or hand it to a second session to carry out.

How do I leave plan mode when I've read the plan?#

In an interactive session, approve the plan when Claude Code asks, or press Shift+Tab to change mode. For one session, start with another mode on the command line; the flag wins over the project default. We started a session in accept edits mode in the same repository:

bash
claude -p --permission-mode acceptEdits "Fix the bug in calc.py. Don't run anything."
git diff --stat
 calc.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

The project default was still plan; only that session ran with edits allowed. Remove defaultMode from the file, or set it to another mode, when the repository no longer needs the pause.

If you approve a plan and Claude Code then asks about every edit anyway, that is a separate behaviour: after a plan it returns to the mode you were in before. Claude Code asks about every edit after the plan explains it and the setting that changes it.

What about the other modes?#

claude --help in 2.1.318 lists six: acceptEdits, auto, bypassPermissions, manual, dontAsk and plan. For a cautious repository the useful pair is plan to look and decide, and the normal asking mode to carry it out one step at a time. Leave bypassPermissions for throwaway sandboxes, never for a repository with real data in reach.

When the plan needs someone else's yes#

Plan mode works well when the person who reads the plan is the person at the keyboard. In a team, the person who should approve a change to billing is often not the one running the agent, and the plan sits in a terminal they can't see. Joxo puts the agent's question in front of the right person, on their phone or desktop, and the answer goes back into the session, whichever agent each of you uses. See approving agent actions from your phone.

Frequently asked questions#

How do I make Claude Code always start in plan mode?#

Add "defaultMode": "plan" inside the permissions block of .claude/settings.json in the project and commit the file. Every session started in that folder then begins in plan mode. Put it in .claude/settings.local.json instead if only you want it.

Can Claude Code run commands in plan mode?#

It can run commands that only read, such as git log or listing files, so the plan is based on the real project. In our test it refused to run a command that creates a file and wrote a plan for it instead. Check your own setup with a harmless write after changing settings.

Where does Claude Code save plans?#

In ~/.claude/plans, one Markdown file per plan. The path is printed at the end of the plan, so you can copy the file into a pull request or give it to another session.

How do I get out of plan mode for one session?#

Start the session with another mode, for example claude --permission-mode acceptEdits. The flag overrides the project default for that session only. In an interactive session you can also approve the plan or press Shift+Tab.