How does Atlas ensure all deprecated Swift API calls are found?

Atlas ensures comprehensive coverage by first using its `lsp` tool's `findReferences` operation, which queries the Swift language server for all precise symbol usages. It then cross-references this with a `grep` search for any string-based or dynamic usages that might not be caught by the language server, guaranteeing every callsite in your Swift codebase is identified.

Can Atlas handle complex Swift refactoring, like generics or async/await migrations?

Yes, Atlas is designed to handle complex Swift refactoring. Its indexing via AST declarations (tree-sitter) and integration with the Swift language server via the `lsp` tool allows it to understand the semantic structure of your code, making it suitable for migrations involving generics, protocol adoptions, or even the adoption of async/await patterns in Swift.

What happens if a Swift file changes while Atlas is working on it?

Atlas's `apply_patch` tool is designed for safety. If a Swift file changes (drifts) after the initial enumeration but before a patch is applied, `apply_patch` will detect that the expected context or old lines no longer match. It will then throw a 'Failed to find expected lines' error, preventing the patch from being misapplied and ensuring the integrity of your Swift source code.

How does Atlas integrate with `XCTest via swift test` for verification?

Atlas integrates directly with `XCTest via swift test` using its `bash` tool. After each individual file modification during a migration, Atlas executes the relevant `swift test` command. The `todowrite` entry for that specific callsite is only marked as complete once the tests pass, providing immediate, automated verification of the changes in your Swift project.

Can Atlas help with updating `Package.swift` dependencies during a migration?

While the primary focus of this workflow is API callsite migration, Atlas's `bash` and `apply_patch` tools can be used to modify `Package.swift` files. For example, if a deprecated module is replaced by a new one, Atlas can draft and apply patches to update your `Package.swift` dependencies and targets, similar to how it handles other Swift source files.

Is Atlas compatible with `swift-format` for maintaining code style?

Yes, Atlas is compatible with `swift-format`. While Atlas focuses on functional code changes, you can integrate `swift-format` into your workflow. For instance, you could configure Atlas to run `atlas bash 'swift-format --in-place '` as part of your post-migration steps or even before committing changes to ensure your Swift code adheres to your team's formatting standards.

How does Atlas handle large Swift codebases with many files?

Atlas handles large Swift codebases efficiently by fanning out work to subagents that can run in the foreground or in parallel background sessions. Its `todowrite` system ensures that every callsite, regardless of codebase size, is tracked. The iterative apply-patch-test cycle, combined with permission-gated tool calls, provides a scalable and safe approach for extensive migrations across many Swift files and modules.

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

In 2026, Atlas provides Swift developers with a robust, terminal-native solution to systematically migrate an entire codebase off a deprecated function or module onto its replacement, ensuring every callsite is updated and verified using the Swift Package Manager and XCTest via swift test. This process leverages Atlas's deep code understanding and precise patching capabilities to manage complex refactoring tasks across large Swift projects.

How does Atlas find deprecated Swift API calls across a codebase?

Atlas precisely identifies every callsite of a deprecated Swift API by leveraging the `lsp` tool's `findReferences` operation, which queries the language server for a complete and accurate set of callers. This method, superior to simple text searches, ensures that in 2026, no usage within your Swift Package Manager project is overlooked, including those in complex Swift modules.

To initiate a migration, Atlas first needs to build an understanding of your Swift codebase. It does this by indexing code using AST declarations via tree-sitter, rather than relying on blind line windows. For finding deprecated API calls, Atlas utilizes its `lsp` tool, specifically the `findReferences` operation. This tool connects to the Swift language server, which provides a definitive list of all references to a given symbol. This is crucial for Swift, where method overloading, generics, and type inference can make simple `grep` searches unreliable. After the initial `lsp` enumeration, Atlas cross-checks with its `grep` tool for any dynamic or string-based usages that might not be caught by the language server, ensuring a truly exhaustive list of every callsite within your `Package.swift` defined modules. Atlas can build its code index with local Ollama embeddings, keeping your proprietary Swift code off third-party servers.

How does Atlas manage and track Swift API migration progress?

Atlas manages the migration of deprecated Swift APIs by creating a `todowrite` entry for each identified callsite, providing a transparent and trackable workflow for developers in 2026. This approach ensures that partial progress is always visible and that no individual Swift file or module update is silently skipped, maintaining project integrity.

Once Atlas has enumerated all callsites of the deprecated Swift API, it doesn't just present a list; it transforms that list into actionable, trackable work items. For each identified callsite, Atlas creates a distinct entry using its `todowrite` tool. This ensures that every single instance of the deprecated API, whether in a `.swift` file or a test case, becomes a visible task. This granular tracking is vital for large Swift projects, allowing developers to see exactly which files have been updated and which still require attention. As each callsite is migrated and verified, its corresponding `todowrite` entry is marked as complete. This systematic approach prevents 'half-measures' and provides a clear audit trail of the migration progress, which is especially useful when dealing with complex Swift Package Manager projects involving multiple targets and dependencies.

How does Atlas safely apply changes for Swift API migrations?

Atlas safely applies changes for Swift API migrations using its `apply_patch` tool, which performs each modification as a context-anchored patch that fails rather than misapplying to a drifted file. This ensures that in 2026, every update to your Swift codebase, from a single `.swift` file to an entire module, is precise and verifiable, preventing unintended side effects.

The core of the migration process in Atlas is the `apply_patch` tool. For each `todowrite` entry, Atlas drafts a plan in a read-only plan agent, proposing the necessary changes to migrate the deprecated Swift API callsite. Before any modification is made, Atlas asks for approval. Once approved, it switches to a build agent and computes a unified diff for every file edit, surfacing it for approval before writing. The `apply_patch` tool is designed for safety: it seeks the hunk's context and old_lines. If the expected lines are not found due to a file drifting since the initial enumeration, it throws a 'Failed to find expected lines' error rather than guessing or forcing a potentially incorrect change. This prevents silent corruption of your Swift source code. After each file is modified, Atlas immediately runs the affected tests using its `bash` tool, executing `XCTest via swift test`. Only once these tests pass is the `todowrite` entry marked as completed, providing immediate feedback on the correctness of the migration for that specific Swift file. Atlas also snapshots file changes as git patches, so edits can be diffed and rolled back if needed.

How does Atlas ensure complete and verified Swift API migration?

Atlas ensures a complete and verified Swift API migration by integrating `XCTest via swift test` after each file modification and performing a final `grep` check for the deprecated symbol. This rigorous approach guarantees that in 2026, every callsite in your Swift Package Manager project is updated, all tests pass, and the old implementation can be safely removed.

The migration workflow with Atlas is designed for thoroughness. After each individual file modification using `apply_patch`, Atlas immediately invokes the `bash` tool to run the relevant tests. For Swift projects, this means executing `XCTest via swift test` to confirm that the changes haven't introduced regressions and that the new API usage is correct. Only upon successful test completion is the `todowrite` entry for that specific callsite marked as done. This iterative testing prevents a cascade of errors and provides confidence at every step. Once all `todowrite` entries are completed, Atlas performs a final verification step: it uses its `grep` tool to search the entire codebase for any remaining instances of the deprecated symbol. This final check confirms zero remaining hits, ensuring that no callsite was missed, including those in comments or string literals. Only then is the old implementation of the deprecated Swift API safely deleted, completing the migration with full confidence in the integrity of your Swift codebase. Atlas also reads git branches, status, and diffs, and can stage and create commits on your behalf, streamlining the entire process.

Step by step

011. Initialize Atlas in your Swift Package Manager project by running `atlas` in the directory containing `Package.swift`.
022. Enumerate every callsite of the deprecated Swift symbol using `atlas lsp findReferences <symbol_name>` and cross-check with `atlas grep <deprecated_string>` for dynamic usages.
033. Create a `todowrite` entry for each identified callsite to track progress, ensuring no Swift file or module is silently skipped.
044. Migrate each Swift callsite using `atlas apply_patch <file_path> <old_lines> <new_lines>`, ensuring the patch context matches the current file state.
055. After each file modification, run affected tests with `atlas bash 'swift test --filter <test_suite>'` (or `XCTest via swift test`) and mark the `todowrite` entry complete only if tests pass.
066. Finish by running `atlas grep <deprecated_symbol_name>` to confirm zero remaining hits in your Swift codebase, then delete the old implementation.
077. Review the unified diffs presented by Atlas for each file edit and approve changes before they are written to your Swift source files.
088. Use `atlas git commit -m 'Migrate deprecated Swift API'` to stage and commit the changes made across your Swift project.

Frequently asked questions

How does Atlas ensure all deprecated Swift API calls are found?: Atlas ensures comprehensive coverage by first using its `lsp` tool's `findReferences` operation, which queries the Swift language server for all precise symbol usages. It then cross-references this with a `grep` search for any string-based or dynamic usages that might not be caught by the language server, guaranteeing every callsite in your Swift codebase is identified.
Can Atlas handle complex Swift refactoring, like generics or async/await migrations?: Yes, Atlas is designed to handle complex Swift refactoring. Its indexing via AST declarations (tree-sitter) and integration with the Swift language server via the `lsp` tool allows it to understand the semantic structure of your code, making it suitable for migrations involving generics, protocol adoptions, or even the adoption of async/await patterns in Swift.
What happens if a Swift file changes while Atlas is working on it?: Atlas's `apply_patch` tool is designed for safety. If a Swift file changes (drifts) after the initial enumeration but before a patch is applied, `apply_patch` will detect that the expected context or old lines no longer match. It will then throw a 'Failed to find expected lines' error, preventing the patch from being misapplied and ensuring the integrity of your Swift source code.
How does Atlas integrate with `XCTest via swift test` for verification?: Atlas integrates directly with `XCTest via swift test` using its `bash` tool. After each individual file modification during a migration, Atlas executes the relevant `swift test` command. The `todowrite` entry for that specific callsite is only marked as complete once the tests pass, providing immediate, automated verification of the changes in your Swift project.
Can Atlas help with updating `Package.swift` dependencies during a migration?: While the primary focus of this workflow is API callsite migration, Atlas's `bash` and `apply_patch` tools can be used to modify `Package.swift` files. For example, if a deprecated module is replaced by a new one, Atlas can draft and apply patches to update your `Package.swift` dependencies and targets, similar to how it handles other Swift source files.
Is Atlas compatible with `swift-format` for maintaining code style?: Yes, Atlas is compatible with `swift-format`. While Atlas focuses on functional code changes, you can integrate `swift-format` into your workflow. For instance, you could configure Atlas to run `atlas bash 'swift-format --in-place <file_path>'` as part of your post-migration steps or even before committing changes to ensure your Swift code adheres to your team's formatting standards.
How does Atlas handle large Swift codebases with many files?: Atlas handles large Swift codebases efficiently by fanning out work to subagents that can run in the foreground or in parallel background sessions. Its `todowrite` system ensures that every callsite, regardless of codebase size, is tracked. The iterative apply-patch-test cycle, combined with permission-gated tool calls, provides a scalable and safe approach for extensive migrations across many Swift files and modules.

Try Atlas in your terminal

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

Install Atlas

Related guides

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

How to migrate a deprecated API across every callsite with Atlas in 2026: the lsp tool's findReferences enumerates callers, todowrite tracks them, apply_patch migrates each one.

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.

Audit a Swift Repo with Parallel Subagents in Atlas in 2026

Sweep large Swift repositories for code issues in 2026 using Atlas's parallel subagents. Leverage Swift Package Manager, XCTest, and swift-format without blowing your context window.

Write Unit Tests for Untested Swift Code with Atlas in 2026

In 2026, Atlas helps Swift developers write XCTest unit tests for untested code, matching existing repository conventions and integrating with Swift Package Manager.

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.

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.

Research a third-party API before integrating it in Swift with Atlas (2026)

Research a third-party API before integrating it in Swift in 2026: Atlas uses websearch and webfetch to pull current docs, then writes against real signatures.

Browse this resource hub