You design a change that touches many files with Atlas by switching to the plan agent, whose description is literally Plan mode. Disallows all edit tools. The plan agent's permission set denies edit for every path except the plan markdown, so research with codebase_search, grep, read, and the lsp tool cannot accidentally turn into an edit. When the plan is ready, the plan_exit tool asks whether to switch to the build agent and start implementing, and you answer Yes or No.
How do I plan a multi-file change before Atlas edits anything?
Atlas plans a multi-file change in the plan agent, whose description reads Plan mode. Disallows all edit tools. The plan agent's permission set denies edit for "*" and allows it only under .atlas/plans/*.md, so all 4 research tools stay available while writing to source stays impossible.
The Atlas plan agent turns a policy into a permission rule. Rather than instructing a model to think before it edits and hoping, Atlas configures the plan agent so that edit is denied for every path in the repository, with exactly one exception: the plan markdown under .atlas/plans/*.md. Research proceeds normally. codebase_search, grep, read, and the lsp tool all stay allowed in plan mode, so the agent can build a complete picture of the blast radius. What it cannot do is start implementing, because the tool that would implement is denied. Design and execution are separated by the permission system, not by a prompt.
What can the Atlas plan agent actually do in plan mode?
The Atlas plan agent can read and search but cannot edit. Plan mode keeps 4 tools allowed, codebase_search, grep, read, and the lsp tool, while its permission set denies edit for every path except .atlas/plans/*.md, so research and design cannot accidentally turn into an edit.
Plan mode in Atlas is not a degraded mode, it is a fully equipped research mode with one capability removed. codebase_search queries the semantic index, and because Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, the plan agent can locate every subsystem a change will touch by describing behavior. grep confirms exact text. read opens the candidates. The lsp tool's operations walk the symbol graph so the plan can enumerate real callsites rather than guessed ones. The only write the plan agent is permitted is the plan document itself, which is the one place plan mode can write.
Where does the Atlas plan get written?
The Atlas plan agent writes the plan into the allowed markdown path under .atlas/plans/*.md, the only location its permission set permits it to edit. Every other path in the repository is denied, so in a 2026 Atlas session the plan document is the single artifact plan mode produces before handoff to the build agent.
Writing the plan to a real file rather than leaving it in a chat transcript is what makes the multi-file change reviewable. The plan markdown under .atlas/plans/*.md is a normal file in the repository: you can read it, you can diff it, you can comment on it, and you can ask the plan agent to revise it. Because the plan agent's permission set denies edit for "*" and allows only that path, there is no ambiguity about what plan mode has and has not touched. A reviewer can look at the working tree and see exactly one changed file.
What does the Atlas plan_exit tool do?
The Atlas plan_exit tool ends plan mode by asking 1 question: Plan at <path> is complete. Would you like to switch to the build agent and start implementing? Answering Yes hands off to the build agent. Answering No raises Question.RejectedError and keeps you refining the plan.
plan_exit is the gate between designing a multi-file change and making it. Atlas does not silently promote itself from planning to building. plan_exit surfaces an explicit question tool prompt naming the plan path, and the transition happens only on an affirmative answer. Answering No is not a dead end: plan_exit raises Question.RejectedError, plan mode stays in force, and you continue refining the plan with more codebase_search, grep, read, and lsp research. This is the human review point for the entire workflow, and it happens before a single line of source is modified.
What happens after Atlas switches to the build agent?
After you answer Yes to plan_exit, Atlas switches from the plan agent to the build agent and begins implementing the plan. Edit permissions are no longer denied, but review does not disappear: Atlas computes 1 unified diff per file edit and surfaces it for approval before writing.
The handoff from the Atlas plan agent to the build agent changes what is permitted, not whether you get to look. Once the build agent is active, the multi-file change proceeds against the plan document that you already reviewed, so the sequence of edits is not a surprise. Each individual edit is still a permission-gated tool call, because every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and each file change arrives as a unified diff. Atlas also snapshots file changes as git patches so edits can be diffed and rolled back if the plan turns out to be wrong in practice.
Why plan a multi-file change instead of just editing?
Planning a multi-file change in Atlas costs 1 extra step, plan_exit, and buys a reviewable design before any source is touched. Atlas drafts the plan in a read-only plan agent and asks before switching to a build agent, so the blast radius across many files is known in advance rather than discovered during the edit.
A change confined to one file can be reviewed at the diff. A change that spans many files cannot, because by the time the diffs arrive, the design decisions are already baked in and the reviewer is reduced to approving mechanics. The Atlas plan agent moves the decision earlier. Research happens with the same tools, codebase_search, grep, read, and the lsp tool, but the output is a written plan under .atlas/plans/*.md instead of a working tree full of edits. You review the plan, answer the plan_exit question, and only then does Atlas start writing code.
Step by step
- 01Switch to the Atlas plan agent. Its description is Plan mode. Disallows all edit tools, and its permission set denies edit for "*" and allows it only under .atlas/plans/*.md.
- 02Research the change with codebase_search to find every subsystem the change touches by describing behavior rather than guessing filenames. codebase_search stays allowed in plan mode.
- 03Confirm exact occurrences with grep and open the candidates with read. Both remain allowed in plan mode.
- 04Enumerate real callsites with the lsp tool so the plan lists the actual blast radius rather than an assumed one. The lsp tool is allowed in plan mode.
- 05Write the plan into the allowed plan markdown path, which is the one place plan mode can write.
- 06Call plan_exit. Atlas asks: Plan at <path> is complete. Would you like to switch to the build agent and start implementing?
- 07Answer Yes to hand off to the build agent and start implementing. Answering No raises Question.RejectedError and keeps you refining the plan.
- 08Review each edit the build agent proposes. Atlas computes a unified diff for every file edit and surfaces it for approval before writing.
Frequently asked questions
- how do I make an AI coding agent plan before it edits my code
- Use the Atlas plan agent. Its permission set denies edit for "*" and allows it only under .atlas/plans/*.md, so the agent researches with codebase_search, grep, read, and the lsp tool but physically cannot write to source until you approve the handoff.
- what is plan mode in Atlas
- Plan mode is the Atlas plan agent, described as Plan mode. Disallows all edit tools. Atlas drafts a plan in this read-only agent and asks, via the plan_exit tool, before switching to a build agent and implementing.
- how does Atlas switch from planning to implementing
- The plan_exit tool asks: Plan at <path> is complete. Would you like to switch to the build agent and start implementing? Answering Yes hands off to the build agent. Answering No raises Question.RejectedError and plan mode continues.
- where does Atlas save the plan file
- Atlas writes the plan into the allowed plan markdown path under .atlas/plans/*.md. That path is the only location the plan agent's permission set allows it to edit, so the plan document is the only file plan mode produces.
- can I reject an AI agent's plan and make it try again
- Yes. Answer No when plan_exit asks whether to switch to the build agent. Atlas raises Question.RejectedError, stays in the plan agent, and you keep refining the plan with codebase_search, grep, read, and the lsp tool.
- how do I review a change that spans many files before it happens
- Plan it in Atlas first. The plan agent researches with codebase_search and the lsp tool, writes the design to .atlas/plans/*.md, and calls plan_exit. You review the plan document, not a pile of diffs after the fact.
- does Atlas still show me diffs after I approve the plan
- Yes. Once the build agent takes over, Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and every tool call is still permission-gated against allow, ask, and deny rules.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Plan a Multi-File Change Before Editing in Erlang with Atlas in 2026
In 2026, Erlang developers use Atlas to plan and review complex multi-file changes, ensuring design approval before modifying a single line of code or running rebar3. Securely design Erlang system updates.
Plan a multi-file change before editing in PHP with Atlas (2026)
Design a multi-file PHP change before any edit lands. Atlas's plan agent denies edit outside .atlas/plans/*.md, and plan_exit gates the handoff to the build agent.
Plan a Multi-File Change Before Editing in Unreal Engine with Atlas in 2026
Design and review complex multi-file changes for Unreal Engine projects with Atlas in 2026. Plan C++ refactors, manage Build.cs dependencies, and ensure Epic style compliance.
Plan a Multi-File Elixir Change Before Editing with Atlas (2026)
Plan a multi-file Elixir change before editing with Atlas in 2026. Plan mode denies all edit tools, so you research contexts and GenServers and design the change first.
Plan a Multi-File Change in Fortran with Atlas Before Editing in 2026
Design and review complex Fortran code changes across multiple files using Atlas in 2026. Plan safely with fpm, fprettify, and gfortran integration before modifying a single line.
Plan a Multi-File Change Before Editing in Assembly with Atlas in 2026
Design and review complex, multi-file Assembly changes with Atlas in 2026. Plan x86-64 or ARM64 modifications, get feedback, and ensure correctness before touching a single instruction.
Plan a Multi-File Change Before Editing in C# with Atlas (2026)
Design a C# refactor across many files in 2026 before touching one line. Atlas plan mode denies every edit tool, writes a plan, then hands off with plan_exit.
Plan a Multi-File Change Before Editing in Gin with Atlas in 2026
Design complex, multi-file changes for your Gin application with Atlas's plan agent in 2026. Research, plan, and get review before modifying a single line of Go code, ensuring safety and precision.