how do I find every file that includes a c++ header before changing it

Use grep with an include filter for *.h and *.cpp, which Atlas runs through ripgrep, plus the lsp tool's symbol graph for call sites that a text search misses. Both tools stay allowed in Atlas's plan mode, so you can map the blast radius before any edit.

can I reject a plan an AI agent wrote and make it try again

Yes. Atlas's plan_exit tool asks whether to switch to the build agent and start implementing. Answering No raises Question.RejectedError and keeps you in plan mode refining the plan document, so a plan that missed a GoogleTest fixture gets revised rather than executed.

where does atlas save its plan file

Atlas writes the plan into the allowed plan markdown path under .atlas/plans/, which is the one place plan mode can write. The permission set allows edit only for .atlas/plans/*.md and denies it for "*", so the plan file is the sole writable target during design.

does atlas understand cmake and vcpkg projects

Run atlas in a project with a CMakeLists.txt and let Atlas read your headers, translation units, and build targets. Atlas indexes code by AST declarations using tree-sitter, so classes, functions, and templates are indexed as declarations rather than as blind line windows.

how do I safely refactor c++ across many translation units

Plan the change first in Atlas's plan agent, record the headers, .cpp files, CMake targets, and GoogleTest cases in the plan under .atlas/plans/, then switch to the build agent via plan_exit. Review each unified diff, build with CMake, and run GoogleTest via ctest before committing.

how do I undo a multi-file c++ change an AI agent made

Atlas snapshots file changes as git patches so edits can be diffed and rolled back, which turns a twenty-file refactor into one revert instead of a manual unwind. Atlas also reads git branches, status, and diffs so you can see exactly what changed before deciding.

Plan a Multi-File Change Before Editing in C++ with Atlas (2026)

Atlas plans a multi-file C++ change in a plan agent whose description is literally "Plan mode. Disallows all edit tools." Its permission set denies edit for every path except the plan markdown under .atlas/plans/, so research across your CMakeLists.txt, your headers, and your translation units cannot accidentally turn into an edit. Atlas researches with codebase_search, grep, read, and the lsp tool, writes the design to a plan file, then calls plan_exit to ask whether to switch to the build agent and start implementing.

Key takeaways

Atlas's plan agent denies edit for "*" and allows it only under .atlas/plans/*.md, so C++ research cannot become an accidental edit to a header.
codebase_search, grep, read, and the lsp tool all stay allowed in plan mode, which is everything you need to map a C++ change across headers and translation units.
plan_exit asks whether to switch to the build agent; answering No raises Question.RejectedError and keeps you refining the plan.
Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each change to include/ or src/ is reviewed individually.
Atlas snapshots file changes as git patches, so a multi-file C++ refactor rolls back as a unit when ctest disagrees.
Verify the executed plan with a CMake build, GoogleTest via ctest, and clang-format on every touched header and translation unit.

How do you plan a multi-file C++ change before editing anything?

Atlas plans a multi-file C++ change in a dedicated plan agent whose permissions deny edit for "*" and allow it only under .atlas/plans/*.md. Research across your CMakeLists.txt, headers, and .cpp translation units runs in 4 read-only tools, and no line of C++ moves until you approve.

The job is to design a change that touches many files, and get it reviewed, before a single line is modified. C++ punishes the alternative harder than most languages. Change a signature in include/engine/Renderer.h and every translation unit that includes it recompiles, some of them fail, and the ones that succeed may have silently picked a different overload. Add a member to a class in a public header and you have changed the ABI. Atlas therefore separates design from execution structurally. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, and the plan agent's permission set is what makes that a guarantee rather than an intention.

What can Atlas's plan mode actually do in a C++ repo?

Atlas's plan agent keeps 4 research tools fully allowed in a C++ project: codebase_search, grep, read, and the lsp tool. Every one of them reads. None of them writes. The only writable path in the entire permission set is the plan markdown under .atlas/plans/*.md.

Research in C++ means answering questions that span headers and translation units. Which files include engine/Renderer.h. Which call sites pass a raw pointer that would become a std::unique_ptr under the new design. Which CMake targets in CMakeLists.txt link the library you are about to change, and whether any of them come from vcpkg. Atlas answers those with codebase_search over the semantic index, grep through ripgrep with an include filter for *.h and *.cpp, read on the specific files, and the lsp tool for the symbol graph. Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so a hit is a real class, function, or template declaration rather than a chunk that straddles an include block.

Where does Atlas write the C++ plan and why only there?

Atlas writes the plan into the allowed plan markdown path under .atlas/plans/, which is the one place plan mode can write. The permission set denies edit for "*" and allows it only for .atlas/plans/*.md, so a plan for refactoring 30 C++ translation units cannot leak an edit into any of them.

A single writable path is a strong invariant. A C++ plan is a document, not a patch: it lists the headers to change, the translation units that include them, the CMake targets that must be rebuilt, the GoogleTest cases that need updating, and the order the change should land in so the build stays green between commits. Writing that document to .atlas/plans/ is a write, so plan mode must allow something. Allowing exactly one glob and denying everything else means the design phase has no path to your include/ or src/ directories at all. The plan is reviewable before it is executable, which is the entire point.

How do you switch from planning to editing C++ in Atlas?

Atlas calls the plan_exit tool, which asks: Plan at <path> is complete. Would you like to switch to the build agent and start implementing? There are 2 outcomes. Yes hands off to the build agent. No raises Question.RejectedError and keeps you refining the C++ plan.

The handoff is an explicit question, not an inference. In a C++ refactor that boundary is the moment before anything recompiles, so it deserves a real decision. If the plan says the change touches include/engine/Renderer.h, src/engine/Renderer.cpp, and six call sites, and you notice it forgot the GoogleTest fixture in tests/RendererTest.cpp, you answer No. Question.RejectedError keeps the session in plan mode, and Atlas revises the plan document. Only when the plan matches the real shape of the change do you answer Yes, and only then does the build agent gain the ability to edit your C++ sources. Atlas tools this workflow uses are plan_exit, codebase_search, grep, read, the lsp tool, and question.

How does Atlas review a C++ change once the plan is approved?

Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each change to include/ or src/ is reviewed on its own. Atlas also snapshots file changes as git patches, which means a multi-file C++ refactor across 20 translation units can be rolled back as a unit.

Review after the plan is approved is per-file and per-diff. The build agent implements what the plan describes, and every edit stops for the diff. That is the second gate. The third gate is your toolchain: configure and build through CMakeLists.txt, run GoogleTest via ctest, and run clang-format on the touched headers and translation units so the diff carries no style noise. Because Atlas snapshots file changes as git patches so edits can be diffed and rolled back, a refactor that compiles but fails ctest is a revert rather than a manual unwind of twenty files. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so even in the build agent, nothing runs unannounced.

Why does a C++ refactor need a plan more than other languages?

C++ compiles per translation unit, so a change to 1 header in include/ ripples into every .cpp that includes it and into every CMake target that links the result. Atlas plans first because the cost of discovering that ripple halfway through an edit is a broken build and a dependency you did not know about.

The blast radius of a C++ change is not visible from the file you are editing. A signature change in a public header touches call sites you have not opened, template instantiations that only fail at the point of use, and vcpkg-provided dependencies that pin an older interface. The lsp tool's symbol graph and grep with an include filter for *.h and *.cpp surface that radius before you commit to it, and the plan document records it. GoogleTest via ctest then tells you whether the plan was right. Planning does not slow a C++ refactor down. Discovering the third missed call site during the fourth rebuild does.

Step by step

01Run atlas in a C++ project with a CMakeLists.txt and let Atlas read your headers, translation units, and build targets.
02Switch to the plan agent; its permissions deny edit for "*" and allow it only under .atlas/plans/*.md, so no header or .cpp file can be touched during design.
03Research with codebase_search, grep, read, and the lsp tool, all of which stay allowed in plan mode; scope grep with an include filter for *.h and *.cpp so build artifacts stay out.
04Use the lsp tool's symbol graph to find every translation unit that includes the header you intend to change, and check which CMake targets link it.
05Write the plan into the allowed plan markdown path under .atlas/plans/, listing the headers, the .cpp files, the CMake targets, and the GoogleTest cases the change touches, in landing order.
06Call plan_exit, which 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 holds you in plan mode; answer Yes to hand off to the build agent.
08In the build agent, review the unified diff Atlas surfaces for each file, then build with CMake, run GoogleTest via ctest, and run clang-format on the touched files.

Frequently asked questions

how do I stop an AI agent from editing my c++ code before I approve the plan: Use Atlas's plan agent. Its description is literally "Plan mode. Disallows all edit tools", and its permission set denies edit for every path except the plan markdown under .atlas/plans/*.md. Research across headers and translation units runs, but no .cpp file can be written.
what is plan mode in an AI coding agent: Plan mode is a read-only agent that researches and designs a change without being able to edit. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, using the plan_exit tool to ask whether you want to start implementing.
how do I find every file that includes a c++ header before changing it: Use grep with an include filter for *.h and *.cpp, which Atlas runs through ripgrep, plus the lsp tool's symbol graph for call sites that a text search misses. Both tools stay allowed in Atlas's plan mode, so you can map the blast radius before any edit.
can I reject a plan an AI agent wrote and make it try again: Yes. Atlas's plan_exit tool asks whether to switch to the build agent and start implementing. Answering No raises Question.RejectedError and keeps you in plan mode refining the plan document, so a plan that missed a GoogleTest fixture gets revised rather than executed.
where does atlas save its plan file: Atlas writes the plan into the allowed plan markdown path under .atlas/plans/, which is the one place plan mode can write. The permission set allows edit only for .atlas/plans/*.md and denies it for "*", so the plan file is the sole writable target during design.
does atlas understand cmake and vcpkg projects: Run atlas in a project with a CMakeLists.txt and let Atlas read your headers, translation units, and build targets. Atlas indexes code by AST declarations using tree-sitter, so classes, functions, and templates are indexed as declarations rather than as blind line windows.
how do I safely refactor c++ across many translation units: Plan the change first in Atlas's plan agent, record the headers, .cpp files, CMake targets, and GoogleTest cases in the plan under .atlas/plans/, then switch to the build agent via plan_exit. Review each unified diff, build with CMake, and run GoogleTest via ctest before committing.
how do I undo a multi-file c++ change an AI agent made: Atlas snapshots file changes as git patches so edits can be diffed and rolled back, which turns a twenty-file refactor into one revert instead of a manual unwind. Atlas also reads git branches, status, and diffs so you can see exactly what changed before deciding.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related 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 C++ in 2026

In 2026, C++ developers adopt Atlas, the terminal-native AI coding agent, to enhance productivity. Atlas offers secure, context-aware assistance for modern C++ projects, integrating with CMake and ensuring code quality

Migrate a Deprecated API Across Every C++ Callsite with Atlas (2026)

Move a C++ codebase off a deprecated function without missing a caller in 2026: Atlas enumerates with findReferences, patches with apply_patch, verifies with ctest.

Run the test suite and triage the failures in C++ with Atlas (2026)

Triage a red C++ suite in 2026 with Atlas: run GoogleTest via ctest through bash, read the full saved log past the 2000 line truncation, and group causes in todowrite.

Document a C++ Module with a README using Atlas in 2026

In 2026, Atlas helps C++ developers document modules with accurate READMEs. It uses lsp, grep, and bash to describe what your C++ code actually does today, integrating with CMake, vcpkg, and GoogleTest via ctest.

Refactor a Legacy Module in C++ with Atlas (2026)

How to refactor a legacy C++ module with Atlas in 2026: enumerate callsites with the lsp tool, restructure with apply_patch, and prove behavior with GoogleTest via ctest.

Trace a Runtime Bug From a Stack Trace in C++ With Atlas (2026)

How to trace a C++ runtime bug from a stack trace with Atlas in 2026: read each frame at its offset, grep for the error string, and prove the fix with GoogleTest.

Rename a symbol across the repo in C++ with Atlas (2026)

How Atlas renames a symbol across a C++ repo in 2026: lsp findReferences for the true reference set, grep for strings and docs, and edit that refuses ambiguous matches.

Browse this resource hub