Plan Mode

Plan before you act: in plan mode CrabCode goes read-only and the model produces a plan instead of touching files.

What it is

Plan mode is a read-only permission mode in CrabCode. Once enabled, the model can still read code, run grep, check git status — but any tool that writes, deletes, or runs a shell command that changes the world is denied. The model can only produce a plan describing what it would do; you decide whether to actually do it.

When to use it:

Unfamiliar codebase — let the model explore and write a plan first
Large refactors or cross-file changes — see the route before walking it
High-risk changes (DB migrations, mass deletes, CI tweaks) where you want a safety net

Plan mode and thinking mode are two orthogonal axes: plan governs what the model can touch; thinking governs how deep it reasons. They stack (deep thinking + plan mode is fine).

How to enter

Three ways:

1. Slash command in-session (most common)

shell

/plan
/plan

Switches the current session into plan mode. Run it again to switch back.

2. Shift+Tab cycle

In the TUI, pressing Shift+Tab cycles through permission modes (default / acceptEdits / plan / ...). The status bar shows which one you are in.

3. Lock at startup

bash

crabcode --permission-mode plan
crabcode --permission-mode plan

Forces the entire session into plan mode. Pairs nicely with --print for non-interactive audits:

bash

crabcode --print --permission-mode plan "Audit the security posture of this PR"
crabcode --print --permission-mode plan "Audit the security posture of this PR"

Other valid modes: default / acceptEdits / bypassPermissions / dontAsk. See cli-reference.

What the model can do in plan mode

Read any file you have authorised (Read / Grep / Glob)
Run read-only shell commands (git status, ls, cat — but git commit, rm, npm install are blocked)
Investigate, list trees, draw dependency graphs
Write a plan file to the session-level plan path (use /plan open to edit it in your external editor)

What the model cannot do in plan mode

Write, modify, or delete any file
Run any command that mutates state
Spawn subagents with write permission
Silently flip back to a non-plan mode (you must /plan or Shift+Tab explicitly)

After exiting plan mode

Exiting does not automatically execute the plan — the plan is just an artefact. You choose which steps to follow. Common flow:

Read the plan → /plan to exit plan mode
Copy the parts of the plan you agree with into the next message
Let the model carry those out for real

Local plan vs. remote ultraplan

CrabCode also has a remote deep-planning entry point: /ultraplan. Differences:

Axis	Local plan	Remote ultraplan
Where it runs	Your terminal	A remote session on acosmi.com
How to invoke	`/plan` or `--permission-mode plan`	`/ultraplan <task description>`
Best for	Small-to-medium plans, watch-and-tweak	Long-running, multi-agent exploration, hours-long planning
What you do	Stay at the terminal	Keep working locally, get notified when it finishes
Output	A plan; you decide whether to execute locally	A proposal; choose "execute in remote session" or "teleport back and execute locally"

For full /ultraplan flow see crabcode-on-the-web.

Limits & gotchas

Plan mode does not block reads to sensitive paths: the model can still read any authorised file in the working dir. Use iam / sandboxing to gate paths at the permission layer — don't rely on plan mode for that.
Subagent propagation: spawned teammates inherit plan mode, so they won't quietly write files behind your back.
Plan mode ≠ dry-run: the model does not "fake-execute and roll back" — it simply does not run write actions. Whether the plan actually works has to be validated at real-execution time.
Not every tool is blocked: MCP / custom tools that don't declare write-side-effect metadata may still be callable. When you wire up custom tools, mark their permission metadata correctly.