how do I use AI to plan a refactor across multiple Swift files without it editing anything

Switch Atlas to the plan agent. Its permission set denies edit for "*" and allows writes only under .atlas/plans/*.md, so Atlas can read every file under Sources/ and Tests/ and design the change, but cannot modify a single .swift file until you call plan_exit and answer Yes.

does Atlas plan mode work with Swift Package Manager

Yes. Run atlas in a package with a Package.swift and Atlas reads your targets, protocols, and Swift Package Manager dependencies. Plan mode then researches across those targets with codebase_search, grep, read, and the lsp tool without touching them.

what is plan_exit in Atlas

plan_exit is the Atlas tool that ends plan mode. It asks Plan at is complete. Would you like to switch to the build agent and start implementing? Answer Yes to hand off to the build agent, or No, which raises Question.RejectedError and keeps you in plan mode refining the plan.

where does Atlas save the plan file

Atlas writes the plan to a markdown file under .atlas/plans/*.md. That path is the only place plan mode is permitted to write, which is why a plan for a nine file Swift change can be produced without any file under Sources/ changing.

can I stop an Atlas plan handoff after answering the plan_exit question

Answer No to plan_exit and Atlas raises Question.RejectedError, leaving you in plan mode. If you answered Yes and the build agent starts editing, every file edit is surfaced as a unified diff for approval before writing, and Atlas snapshots file changes as git patches so edits can be diffed and rolled back.

how do I check the Swift changes after Atlas implements the plan

Run XCTest via swift test to confirm behavior across the targets the plan touched, and run swift-format so the diff shows real changes rather than formatting churn. Atlas can also read git status and diffs and stage a commit for the whole plan.

why is Atlas plan mode better than telling the model not to edit yet

A prompt is a suggestion. Atlas plan mode is a permission rule: every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and plan mode denies edit for "*" except .atlas/plans/*.md. The agent cannot edit your Swift sources even if it decides it should.

can Atlas index a private Swift package without sending code to a third party

Yes. Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers, so codebase_search over a closed-source Swift package's AST declarations runs against a locally built index.

Plan a multi-file change before editing in Swift with Atlas (2026)

To plan a multi-file change before editing in Swift, run Atlas in a package with a Package.swift and switch to the plan agent. Atlas ships 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, so you can read every Swift target, protocol, and Swift Package Manager dependency, design the change, and write it to .atlas/plans/*.md without a single .swift file being modified. When the plan is ready, the plan_exit tool asks whether to switch to the build agent and start implementing.

How do I stop an AI agent from editing my Swift package while I am still designing the change?

Atlas plan mode stops the agent structurally, not by instruction. The plan agent's permission set denies edit for "*" and allows it only under .atlas/plans/*.md, so in 2026 every .swift file under Sources/ and Tests/ is off limits until you explicitly hand off to the build agent.

In a Swift package the files you least want touched mid-design are Package.swift, the target sources under Sources/YourTarget/, and the XCTest cases under Tests/YourTargetTests/. Atlas plan mode makes that guarantee mechanical: every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and in plan mode the edit tools are denied for every path except the plan markdown. A prompt that says "do not edit yet" is a suggestion. A deny rule on "*" is a wall. The practical effect is that you can ask Atlas to trace a protocol conformance across six Swift files and it physically cannot start rewriting them halfway through the answer.

What can Atlas actually do in plan mode on a Swift Package Manager project?

Atlas plan mode keeps 5 research tools live on a Swift Package Manager project: codebase_search, grep, read, the lsp tool, and question. All of them stay allowed in plan mode, so a Swift developer loses editing and loses nothing else.

codebase_search is the one that matters most in Swift, because Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so a query about retry behavior returns the actual func or the actual protocol declaration rather than an arbitrary 40 line slab of a file. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, which means a Swift symbol name like URLSessionTransport gets keyword weight while a plain-English description of the behavior still gets semantic weight. The lsp tool gives you the symbol graph across targets, which in Swift Package Manager projects is where the surprises live: a protocol declared in one target and conformed to in three others. grep and read cover the rest, including Package.swift itself and any .swift-format config.

Where does Atlas write the Swift change plan?

Atlas writes the plan to a markdown file under .atlas/plans/*.md, which in 2026 is the single path plan mode is permitted to write. Nothing under Sources/ or Tests/ can be created or modified while the plan agent is active.

The plan file is where the multi-file Swift design lands: which targets in Package.swift gain a dependency, which protocol gets a new requirement, which conforming types under Sources/ must be updated, and which XCTest cases under Tests/ need to change. Writing it into .atlas/plans/*.md rather than a chat message has two effects. First, the plan survives the session, so you can hand it to a teammate or re-open it tomorrow. Second, because plan mode's only writable path is that markdown file, the plan is the boundary: research and design cannot accidentally turn into an edit. If the plan says nine .swift files change, you will see all nine listed before any of them do.

How does plan_exit hand a Swift plan off to the build agent?

The plan_exit tool asks 1 direct question: Plan at <path> is complete. Would you like to switch to the build agent and start implementing? Answering Yes moves a Swift developer from read-only planning into edits. Answering No raises Question.RejectedError and keeps you refining the plan.

That handoff is the moment a Swift package stops being read-only. Before plan_exit, Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent. After you answer Yes, the build agent starts applying the plan, and Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each change to Sources/YourTarget/Transport.swift or to Package.swift is reviewed as a diff, not accepted blind. If you answer No, plan_exit raises Question.RejectedError and you stay in plan mode, which is the right answer when the plan missed a conformance or forgot the XCTest cases that cover it.

What does the review and rollback story look like for a multi-file Swift edit?

Atlas gives a Swift developer three review layers in 2026: a unified diff per file before it is written, a git patch snapshot of each change so edits can be diffed and rolled back, and XCTest via swift test as the behavioral check after the build agent lands the plan.

Once plan_exit hands off, each edit to a .swift file arrives as a unified diff for approval before writing. Atlas snapshots file changes as git patches so edits can be diffed and rolled back, which is what you want when a change to a protocol in Sources/Core/ turns out to break a conformance in a second target. Atlas also reads git branches, status, and diffs, and can stage and create commits on your behalf, so a plan that touched nine .swift files becomes one reviewable commit rather than nine mystery saves. Run XCTest via swift test to prove behavior, and run swift-format to keep the diff free of formatting noise that would drown the real change.

How do I set Atlas up on a Swift package before planning?

Setup takes 3 steps in 2026: run atlas in a package with a Package.swift, let Atlas read your targets, protocols, and dependencies, then have Atlas add XCTest cases or adopt async/await and review the diff. Plan mode sits on top of that same setup.

The Package.swift manifest is the entry point, because it declares the targets and the Swift Package Manager dependencies that define what a multi-file change even means in a Swift project. Once Atlas has read the manifest and the sources, switching to the plan agent gives you the read-only research loop: codebase_search over AST declarations, the lsp tool for the symbol graph, grep for exact strings, read for whole files. Nothing is written outside .atlas/plans/*.md. If your package uses local Ollama embeddings, note that Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers, which matters when the Swift package is a closed-source client SDK.

Step by step

01Run atlas in a Swift package that has a Package.swift at its root so Atlas can read the targets and Swift Package Manager dependencies.
02Switch to the plan agent; its permissions deny edit for "*" and allow it only under .atlas/plans/*.md, so no .swift file under Sources/ or Tests/ can be modified.
03Research the change with codebase_search, grep, read, and the lsp tool; all four stay allowed in plan mode, and codebase_search returns AST declarations rather than blind line windows.
04Use the lsp tool to enumerate every conformance and callsite of the protocols and types your change touches, across every target in Package.swift.
05Write the plan into the allowed plan markdown path under .atlas/plans/*.md, listing each .swift file that will change and each XCTest case that must be updated.
06Call plan_exit; it 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; answering No raises Question.RejectedError and keeps you refining the plan.
08Review each unified diff the build agent produces before it is written, then run XCTest via swift test to prove behavior and swift-format to normalize the diff.

Frequently asked questions

how do I use AI to plan a refactor across multiple Swift files without it editing anything: Switch Atlas to the plan agent. Its permission set denies edit for "*" and allows writes only under .atlas/plans/*.md, so Atlas can read every file under Sources/ and Tests/ and design the change, but cannot modify a single .swift file until you call plan_exit and answer Yes.
does Atlas plan mode work with Swift Package Manager: Yes. Run atlas in a package with a Package.swift and Atlas reads your targets, protocols, and Swift Package Manager dependencies. Plan mode then researches across those targets with codebase_search, grep, read, and the lsp tool without touching them.
what is plan_exit in Atlas: plan_exit is the Atlas tool that ends plan mode. It asks Plan at <path> is complete. Would you like to switch to the build agent and start implementing? Answer Yes to hand off to the build agent, or No, which raises Question.RejectedError and keeps you in plan mode refining the plan.
where does Atlas save the plan file: Atlas writes the plan to a markdown file under .atlas/plans/*.md. That path is the only place plan mode is permitted to write, which is why a plan for a nine file Swift change can be produced without any file under Sources/ changing.
can I stop an Atlas plan handoff after answering the plan_exit question: Answer No to plan_exit and Atlas raises Question.RejectedError, leaving you in plan mode. If you answered Yes and the build agent starts editing, every file edit is surfaced as a unified diff for approval before writing, and Atlas snapshots file changes as git patches so edits can be diffed and rolled back.
how do I check the Swift changes after Atlas implements the plan: Run XCTest via swift test to confirm behavior across the targets the plan touched, and run swift-format so the diff shows real changes rather than formatting churn. Atlas can also read git status and diffs and stage a commit for the whole plan.
why is Atlas plan mode better than telling the model not to edit yet: A prompt is a suggestion. Atlas plan mode is a permission rule: every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and plan mode denies edit for "*" except .atlas/plans/*.md. The agent cannot edit your Swift sources even if it decides it should.
can Atlas index a private Swift package without sending code to a third party: Yes. Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers, so codebase_search over a closed-source Swift package's AST declarations runs against a locally built index.

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 Swift in 2026

Atlas for Swift in 2026 empowers developers with a terminal-native AI coding agent. Index code by AST, ensure privacy with local embeddings, and review changes with unified diffs.

Onboard to an Unfamiliar Swift Codebase with Atlas (2026)

Learn an unfamiliar Swift package in 2026 without reading every file. Atlas queries the semantic index, maps Sources with glob, and delegates sweeps to a read-only explore subagent.

Add a Regression Test for a Bug Fix in Swift with Atlas (2026)

Add a regression test for a bug fix in Swift with Atlas in 2026. Write a failing XCTest case, run swift test to prove it red, apply the fix, then re-run.

Migrate a Deprecated API Across Every Callsite in Swift with Atlas in 2026

In 2026, Atlas helps Swift developers migrate deprecated APIs across their entire codebase, ensuring no callsite is missed. Leverage Atlas with Swift Package Manager and XCTest via swift test for a complete, verified

Self-review your working diff before committing in Swift with Atlas in 2026

In 2026, Swift developers use Atlas to self-review uncommitted diffs, catching mistakes before CI or code review. Leverage `swift test` and `swift-format` with Atlas's terminal-native AI agent.

Automate GitHub Issue and Pull Request Triage in Swift with Atlas in 2026

Swift developers in 2026 can automate GitHub issue and pull request triage using Atlas, integrating with the Swift Package Manager toolchain for safe, trusted responses.

Run the Test Suite and Triage the Failures in Swift with Atlas (2026)

How to triage a red Swift suite with Atlas in 2026: run XCTest via swift test through bash, read the saved full log, group by root cause, and track fixes in todowrite.

Browse this resource hub