Plan mode
Plan mode is a read-only Claude Code state where the agent investigates and proposes a plan before making any file edits or running commands.
Plan mode is a Claude Code state in which the agent is restricted to read-only tools — it can read files, grep, glob, and fetch docs, but it cannot edit, run shell commands that change state, or otherwise modify the system. The agent produces a plan; you approve (or reject) it; then the session continues in normal mode to execute.
Why it matters
The biggest safety and quality win in agentic coding is getting the agent to investigate before it edits. Without plan mode, agents sometimes jump to code changes based on a surface-level reading of the request. Plan mode forces them to look first, commit to a plan, and then execute.
For complex refactors or bug investigations, plan mode is usually worth the extra round trip. Running Claude Code in plan mode in one SpaceSpider pane while another pane does routine work is a common workflow.
How it works
Activating plan mode (typically via keybinding or /plan) sets the agent's available tool use set to read-only operations: read_file, glob, grep, web_fetch, and (depending on config) read-only MCP servers. Write tools (edit, bash with state-changing commands) are blocked at the harness level — the model can try to call them, but the CLI refuses.
The agent typically responds with a structured plan — goals, files to touch, commands to run, risks. When you approve, the session exits plan mode and the agent executes. If you reject or amend, you provide feedback and the agent re-plans.
How it's used
Plan mode earns its keep on:
- Large refactors spanning many files
- Unfamiliar codebases where you want to see what the agent understands
- Bug investigations where premature edits would muddy the picture
- High-stakes changes (auth, payments, data migrations)
It's overkill for trivial edits (rename this variable, add a log line) — for those, just ask directly.
Related terms
- Checkpoint — the rollback-focused companion safety feature
- Sandbox — a broader execution restriction
- Subagent — another way to isolate investigation
- Hook — can enforce or customize plan-mode behavior
- Claude Code — where plan mode lives
FAQ
Is plan mode available outside Claude Code?
Similar read-only or "dry-run" modes exist in other agentic CLIs — Codex CLI has approval modes that achieve a comparable effect. The exact name and ergonomics differ.
Can the agent still call expensive tools in plan mode?
It can call read-only tools, including web fetches. Most teams treat plan mode as "no side effects, any reads welcome." Rate-limit concerns still apply to web tools.
Related terms
- Agentic codingAgentic coding is software development where an LLM-powered agent plans, edits, runs, and verifies code on its own using tools, not just autocomplete.
- AI pair programmingAI pair programming is a collaboration style where an LLM assistant sits alongside you, suggesting code and reviewing changes in real time as you work.
- ANSI escape codesANSI escape codes are control sequences that terminals interpret for colors, cursor movement, and screen clearing — the language of every modern CLI UI.
- Autonomous agentAn autonomous agent is an AI program that perceives, decides, and acts on its own toward a goal — the architecture behind modern coding CLIs.
- CheckpointA checkpoint is a saved snapshot of file state that lets you roll back an AI coding agent's changes to a known-good point.
- Claude CodeClaude Code is Anthropic's official command-line agent that plans, edits, runs, and verifies code across your repo using Claude models and tool use.