Atlas plans a multi-file Dart change with a dedicated plan agent whose description is literally Plan mode. Disallows all edit tools. Its permission set denies edit for every path except the plan markdown, so research across your `lib/` directory and `pubspec.yaml` cannot accidentally turn into an edit. You research with codebase_search, grep, read, and the lsp tool, write the design into `.atlas/plans/*.md`, then call plan_exit, which asks whether to switch to the build agent and start implementing. Only after you answer Yes does anything under `lib/` change, and only then do you run `dart test` and `dart format`.
How do I plan a multi-file Dart change without touching the code?
Switch to Atlas's plan agent. Its permission set denies edit for "*" and allows it only under .atlas/plans/*.md, so a design pass across a Dart package's lib/ directory and pubspec.yaml literally cannot write to a .dart file. In 2026 the description reads: Plan mode. Disallows all edit tools.
Planning a change that touches many Dart files is a research task, not an editing task, and Atlas enforces that distinction with permissions rather than with instructions. The plan agent's permission set denies edit for `*` and allows edit only under `.atlas/plans/*.md`. That single rule means the agent could not modify `lib/src/repository.dart` even if it decided to. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so the deny is checked at the tool boundary rather than trusted to the model's judgment. For a Dart developer this is what makes a design pass safe to run without watching it: a plan for migrating a package's null-safety annotations across 40 files under `lib/` cannot half-apply itself while you are reading the plan.
What can Atlas still do in Dart plan mode?
In Atlas plan mode, research stays fully allowed: codebase_search, grep, read, and the lsp tool all continue to work against a Dart package. Only the edit tools are denied. That is the point, because a plan for a 40-file change in lib/ is only as good as the research behind it.
Atlas's plan agent is not a crippled agent, it is a read-only one. codebase_search queries the semantic index, and because Atlas indexes code by AST declarations using tree-sitter, a hit in a Dart file is a whole class or method rather than a blind line window. Grep runs the exact-token pass over `lib/` and `test/`. Atlas's read tool opens `pubspec.yaml` to check the package's dependency constraints and `analysis_options.yaml` to see which lints the project enforces. The lsp tool exposes the symbol graph, so a plan can enumerate the real callers of a class before proposing to change its constructor. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so both the conceptual question and the literal identifier are covered during planning.
Where does Atlas write the plan for a Dart change?
Atlas writes the plan into the allowed plan markdown path, .atlas/plans/*.md, which in 2026 is the only place plan mode can write. Everything else in a Dart package, including lib/, test/, pubspec.yaml, and analysis_options.yaml, is denied to the edit tool while the plan agent is active.
The plan markdown is the deliverable of Atlas plan mode. For a multi-file Dart change it holds the ordered list of files under `lib/` that will be touched, the new public API shape, the migration order that keeps `dart test` green at each step, and the open questions that research did not settle. Because `.atlas/plans/*.md` is the only writable path, the plan file cannot leak into your package source, and the package source cannot be pre-emptively edited under cover of writing a plan. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so even the plan markdown arrives as a diff you approve. Atlas reads git branches, status, and diffs, which means the plan can be written with awareness of what is already uncommitted in the Dart working tree.
How do I switch from planning to editing Dart code in Atlas?
Call Atlas's plan_exit tool. It asks: Plan at <path> is complete. Would you like to switch to the build agent and start implementing? There are 2 answers. Yes hands the Dart change off to the build agent. No raises Question.RejectedError and keeps you refining the plan.
plan_exit is the gate between design and implementation, and it is a real question, not a formality. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, so the moment your Dart package becomes editable is a moment you explicitly authorized. If you answer No, plan_exit raises Question.RejectedError and the plan agent stays active, still unable to touch `lib/`, so you can keep researching with codebase_search and the lsp tool and revise `.atlas/plans/*.md`. If you answer Yes, the build agent takes over with the plan as its brief. From that point Atlas computes a unified diff for every Dart file edit and surfaces it for approval before writing, and Atlas snapshots file changes as git patches so any edit under `lib/` can be diffed and rolled back.
How do I verify a planned Dart change after the build agent runs?
After Atlas's build agent implements the plan, run dart test through Atlas's bash tool and run dart format over every touched file under lib/. In a 2026 Dart package, pub resolves the dependencies declared in pubspec.yaml, and analysis_options.yaml governs the lints your plan promised to respect.
The verification loop for a multi-file Dart change is the same rhythm the plan should have specified: implement one step, run `dart test`, then move to the next. Atlas's build agent surfaces a unified diff for each Dart file before writing, so a change to `lib/src/models/user.dart` is reviewed on its own rather than buried in a 40-file blob. Run `dart format` before you commit so the reviewer sees behavior changes rather than whitespace. If a step turns out to be wrong, Atlas snapshots file changes as git patches, so the edit is diffed and rolled back rather than hand-reverted, and you can return to the plan agent to revise `.atlas/plans/*.md`. Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf once `dart test` is green.
Step by step
- 01Run atlas in the Dart package with a pubspec.yaml so it can see the package root, lib/, test/, and analysis_options.yaml.
- 02Switch to Atlas's plan agent. Its permissions deny edit for "*" and allow it only under .atlas/plans/*.md, so no .dart file can be modified while you design.
- 03Research the change with codebase_search, grep, read, and the lsp tool. All of them stay allowed in plan mode, so you can enumerate every caller of the class you intend to change.
- 04Read pubspec.yaml for the package's dependency constraints and analysis_options.yaml for the lints the plan must respect.
- 05Write the plan into the allowed plan markdown path under .atlas/plans/, listing the files under lib/ in the order that keeps dart test green at each step.
- 06Call plan_exit. It asks: Plan at <path> is complete. Would you like to switch to the build agent and start implementing?
- 07Answer No to keep refining, which raises Question.RejectedError and leaves the plan agent active and unable to edit Dart source. Answer Yes to hand off to the build agent.
- 08Once the build agent runs, review the unified diff Atlas surfaces for each .dart file before it writes.
- 09Run dart test through Atlas's bash tool after each step, then run dart format over the touched files and let pub resolve any dependency the plan added.
Frequently asked questions
- how do I stop an ai agent from editing my dart code while planning
- Use Atlas's plan agent. Its permission set denies edit for "*" and allows it only under .atlas/plans/*.md, so nothing under lib/ or test/ can be written while you design. The deny is checked at the tool boundary, not left to the model.
- what is plan mode in atlas
- Plan mode is an Atlas agent whose description reads: Plan mode. Disallows all edit tools. It keeps codebase_search, grep, read, and the lsp tool available for research while denying every edit path except the plan markdown.
- what does plan_exit do in atlas
- plan_exit 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 keeps the plan agent active.
- can I still search my dart code in atlas plan mode
- Yes. codebase_search, grep, read, and the lsp tool all stay allowed in plan mode, so you can enumerate callers across lib/ and check pubspec.yaml and analysis_options.yaml before proposing a change.
- where does atlas save the plan file
- Atlas writes the plan into the allowed plan markdown path under .atlas/plans/*.md, which is the only location the plan agent's permission set allows the edit tool to touch.
- how do I plan a null safety migration across a dart package
- Research the callers with the lsp tool and codebase_search in plan mode, write an ordered file list into .atlas/plans/*.md that keeps dart test green at each step, then call plan_exit and answer Yes to hand off to the build agent.
- what happens if I reject the plan_exit prompt
- Answering No to plan_exit raises Question.RejectedError and keeps you in the plan agent, still unable to edit any .dart file. You can then keep researching and revise the plan markdown before asking again.
- how do I verify a multi file dart change after atlas implements it
- Review the unified diff Atlas surfaces for each .dart file before it writes, run dart test through the bash tool after each step, and run dart format over the touched files before committing.
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 with Atlas in 2026
How to plan a multi-file change with Atlas in 2026: the plan agent denies all edit tools, you research with codebase_search and lsp, then plan_exit hands off.
Atlas for Dart in 2026
Adopt Atlas, the terminal-native AI coding agent, for Dart development in 2026. Enhance productivity with intelligent code search, refactoring, and robust safety features across your Dart projects.
Audit a Dart Repo with Parallel Subagents in 2026 using Atlas
Sweep your Dart repository for specific problems without overwhelming your main session. Atlas uses parallel subagents to audit Dart code, managing pub packages and null-safe libraries efficiently.
Review a Pull Request in Dart with Atlas in 2026
In 2026, Atlas helps Dart developers review pull requests by providing deep context, running `dart test`, and checking `pub` dependencies to catch subtle bugs.
Document a Dart Module with a README in 2026 using Atlas
In 2026, Atlas helps Dart developers generate accurate README documentation directly from source code. It uses pub and dart test to ensure docs reflect current module behavior, not outdated plans.
Research a Third-Party API Before Integrating It in Dart with Atlas (2026)
Atlas researches a third-party API for a Dart integration with websearch and webfetch behind permission prompts, then writes null-safe code verified by dart test.
Diagnose a Hanging or Long-Running Dart Command with Atlas in 2026
In 2026, use Atlas to diagnose why your Dart builds or scripts are hanging. Learn to distinguish genuinely slow `pub` or `dart test` commands from those blocked on interactive input, and get them unstuck.
Locate Where a Behavior Is Implemented in Dart with Atlas (2026)
Find the exact Dart file and symbol behind a behavior with Atlas in 2026, using codebase_search for meaning, grep for text, and the lsp tool for the symbol graph.