How does Atlas ensure it finds all deprecated API calls in Crystal?

Atlas combines the `lsp` tool's `findReferences` operation, which leverages the language server's precise AST indexing, with a fallback `grep` search. This dual approach catches both statically linked and dynamic or string-based usages of the deprecated Crystal API, ensuring no callsite is missed.

Can Atlas handle complex Crystal union types during migration?

Yes, Atlas indexes code by AST declarations using tree-sitter, allowing it to understand Crystal's type system, including union types. It can assist in narrowing `Nil` unions or suggesting necessary type adjustments during API migration, just as it helps with `crystal spec` errors.

What if my Crystal project's files drift while Atlas is working?

Atlas uses the `apply_patch` tool, which is designed to prevent misapplications. It seeks the hunk's context and `old_lines` before applying a change. If the expected lines are not found due to file drift, `apply_patch` will fail with "Failed to find expected lines" rather than guessing, protecting your Crystal codebase.

How does Atlas integrate with `shards` for Crystal dependency management?

Atlas operates within your Crystal project, reading your `shard.yml` and understanding dependencies resolved into `lib/` by `shards install`. This awareness allows it to accurately index your codebase and identify calls to deprecated APIs within your project or its dependencies.

How does Atlas ensure code quality and formatting for Crystal changes?

Before presenting any file edit for approval, Atlas runs `crystal tool format` on the generated diff. This ensures that all changes adhere to your project's formatting standards, maintaining consistent style across your Crystal codebase. You approve the formatted diff.

Can I review Atlas's proposed changes before they are applied to my Crystal code?

Absolutely. Atlas drafts a plan in a read-only plan agent and asks for your approval before switching to a build agent. It also computes a unified diff for every file edit and surfaces it for approval before writing, giving you full control over changes to your Crystal project.

Migrate a deprecated API across every callsite in Crystal with Atlas in 2026

Migrating a deprecated API across every callsite in Crystal with Atlas in 2026 involves a systematic, verified approach that leverages your existing toolchain. Atlas uses the `lsp` tool to enumerate all callers, tracks progress with `todowrite`, applies changes safely with `apply_patch`, and verifies each step by running `crystal spec` and `crystal tool format` before committing.

How to find all deprecated API calls in Crystal with Atlas

In 2026, Atlas enumerates every callsite of a deprecated Crystal API using its `lsp` tool, which leverages the language server's `findReferences` operation. This ensures a complete caller set, preventing missed migrations. Atlas then cross-checks with `grep` for dynamic or string-based usages that the language server might miss.

Atlas begins the migration workflow by building its code index using AST declarations from tree-sitter, which is more precise than blind line windows. When you ask Atlas to migrate a deprecated symbol in your Crystal project, it first employs the `lsp` tool to query the language server for all references to that symbol. This operation, `findReferences`, provides a comprehensive list of every location where the deprecated function or module is invoked within your codebase. For example, if you are deprecating a method defined in a `shard.yml` dependency, Atlas will find all its usages. To catch any edge cases, such as dynamic method calls or string-based references that the language server might not track, Atlas performs a secondary `grep` search across your project. This two-pronged approach guarantees that no callsite is overlooked, a critical step in preventing half-measures and ensuring a complete migration. Atlas can build its code index with local Ollama embeddings, keeping your Crystal code off third-party servers.

How Atlas tracks migration progress for Crystal API changes

Atlas ensures no Crystal API callsite is silently skipped during migration by creating one `todowrite` entry for each identified caller. This granular tracking makes partial progress visible and provides a clear roadmap for the entire migration, which is crucial for large Crystal projects in 2026.

Once Atlas has enumerated all calls to the deprecated Crystal API using `lsp` and `grep`, it transitions to tracking the migration work. For every identified callsite, Atlas creates a distinct entry using its `todowrite` tool. This means if your Crystal project has 50 instances of a deprecated method, Atlas will generate 50 individual `todowrite` items. This approach provides unparalleled visibility into the migration process: you can see exactly which files and lines still require attention. As each callsite is successfully migrated and verified, its corresponding `todowrite` entry is marked as complete. This prevents the common pitfall of losing track of progress in a large codebase, especially when dealing with complex union types or dependencies resolved into `lib/` by `shards install`. The `todowrite` system ensures that every single instance of the deprecated API is addressed, leaving no room for incomplete migrations.

Safe Crystal API migration with Atlas apply_patch and crystal spec

Atlas migrates each Crystal API callsite using `apply_patch`, a tool designed for context-anchored changes that fail safely rather than misapplying to drifted files. After each file modification, Atlas runs `crystal spec` to immediately verify the change, ensuring the codebase remains functional in 2026.

The core of the migration process in Crystal with Atlas involves the `apply_patch` tool. For each `todowrite` entry, Atlas drafts a plan in a read-only plan agent, proposing the necessary code changes to replace the deprecated API. This plan is then presented for your approval. Once approved, Atlas switches to a build agent and uses `apply_patch` to implement the change. This tool is highly robust: it seeks the hunk's context and `old_lines` within the target file. If the expected lines are not found due to file drift or other modifications, `apply_patch` throws a "Failed to find expected lines" error, preventing incorrect or partial application of the patch. This is critical for maintaining the integrity of your Crystal codebase, where a compiler will reject a union type you forgot to narrow. Immediately after `apply_patch` modifies a file, Atlas executes `crystal spec` for the affected tests using the `bash` tool. Only if `crystal spec` passes successfully is the `todowrite` entry marked as complete, ensuring that each migration step is fully verified and does not introduce regressions. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, giving you full control.

Ensuring Crystal code quality and final verification with Atlas

Atlas ensures the highest code quality for Crystal migrations by running `crystal tool format` on every diff before approval, maintaining consistent style across the codebase. In 2026, the final verification step involves a comprehensive `grep` for the deprecated symbol, confirming zero remaining hits.

Beyond functional correctness, Atlas prioritizes code quality throughout the Crystal API migration. Before presenting any file edit for your approval, Atlas automatically runs `crystal tool format` on the generated diff. This ensures that all changes adhere to your project's established formatting standards, preventing style inconsistencies from creeping into the codebase during the migration. You can review the formatted diff and approve it, knowing that your Crystal code remains clean and consistent. Once all `todowrite` entries are completed and all individual changes have passed `crystal spec`, Atlas performs a final, comprehensive verification. It uses the `grep` tool to search the entire codebase for any remaining instances of the deprecated symbol. The goal is to confirm zero hits, providing absolute certainty that the old implementation has been entirely removed. Only after this final `grep` confirms a clean slate is the deprecated implementation itself deleted, completing the migration. Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf, streamlining the entire process.

Step by step

01Run Atlas in your Crystal project with a `shard.yml` to allow it to index your code and dependencies resolved into `lib/` by `shards install`.
02Ask Atlas to use the `lsp` tool's `findReferences` operation on the deprecated Crystal symbol, and cross-check with `grep` for dynamic or string-based usages.
03Let Atlas create one `todowrite` entry per identified callsite of the deprecated Crystal API, making partial progress visible.
04Approve Atlas's proposed changes for each callsite using `apply_patch`, ensuring context-anchored patches are applied safely.
05After each file modification, allow Atlas to run `crystal spec` via the `bash` tool to verify affected tests, marking the `todowrite` entry complete only upon success.
06Review and approve the unified diffs, letting Atlas run `crystal tool format` on them before writing to maintain Crystal code style.
07Finish by asking Atlas to `grep` the entire codebase for the deprecated Crystal symbol, confirming zero remaining hits.
08Delete the old deprecated Crystal API implementation from your project.

Frequently asked questions

How does Atlas ensure it finds all deprecated API calls in Crystal?: Atlas combines the `lsp` tool's `findReferences` operation, which leverages the language server's precise AST indexing, with a fallback `grep` search. This dual approach catches both statically linked and dynamic or string-based usages of the deprecated Crystal API, ensuring no callsite is missed.
Can Atlas handle complex Crystal union types during migration?: Yes, Atlas indexes code by AST declarations using tree-sitter, allowing it to understand Crystal's type system, including union types. It can assist in narrowing `Nil` unions or suggesting necessary type adjustments during API migration, just as it helps with `crystal spec` errors.
What if my Crystal project's files drift while Atlas is working?: Atlas uses the `apply_patch` tool, which is designed to prevent misapplications. It seeks the hunk's context and `old_lines` before applying a change. If the expected lines are not found due to file drift, `apply_patch` will fail with "Failed to find expected lines" rather than guessing, protecting your Crystal codebase.
How does Atlas integrate with `shards` for Crystal dependency management?: Atlas operates within your Crystal project, reading your `shard.yml` and understanding dependencies resolved into `lib/` by `shards install`. This awareness allows it to accurately index your codebase and identify calls to deprecated APIs within your project or its dependencies.
How does Atlas ensure code quality and formatting for Crystal changes?: Before presenting any file edit for approval, Atlas runs `crystal tool format` on the generated diff. This ensures that all changes adhere to your project's formatting standards, maintaining consistent style across your Crystal codebase. You approve the formatted diff.
Can I review Atlas's proposed changes before they are applied to my Crystal code?: Absolutely. Atlas drafts a plan in a read-only plan agent and asks for your approval before switching to a build agent. It also computes a unified diff for every file edit and surfaces it for approval before writing, giving you full control over changes to your Crystal project.
How does Atlas verify that a Crystal API migration step is successful?: After `apply_patch` modifies a file, Atlas immediately runs `crystal spec` for the affected tests using the `bash` tool. Only if `crystal spec` passes successfully is the `todowrite` entry for that callsite marked as complete, ensuring functional correctness in your Crystal codebase.

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 Crystal: A Terminal-Native AI Coding Agent for shard.yml Projects in 2026

Atlas is a terminal-native AI coding agent for Crystal in 2026. It reads shard.yml and union types, narrows Nil unions, runs crystal spec behind a prompt, and formats the diff.

Diagnose a hanging or long-running command in Crystal with Atlas in 2026

In 2026, Crystal developers use Atlas to diagnose hanging or slow `crystal spec` tests or `shards` commands. Learn how Atlas identifies blocked input and helps you get unstuck.

Review a Pull Request in Crystal with Atlas in 2026

In 2026, review Crystal pull requests with Atlas, the terminal-native AI coding agent. Leverage `crystal spec`, `shards`, and `crystal tool format` for deep, context-aware code analysis.

Rename a Symbol Across the Repo in Crystal with Atlas in 2026

In 2026, Crystal developers use Atlas to accurately rename functions, classes, and constants across their entire codebase, leveraging `crystal spec` and `shards` for verification.

Run the test suite and triage the failures in Crystal with Atlas in 2026

In 2026, Crystal developers use Atlas to efficiently run `crystal spec`, analyze extensive test output, and prioritize distinct root causes for failures, streamlining the debugging workflow.

Trace a runtime bug from a stack trace in Crystal with Atlas in 2026

Pinpoint Crystal runtime bugs from production stack traces in 2026 using Atlas, the terminal-native AI agent. Leverage `crystal spec` and `shards` for rapid, debugger-free fixes.

Debug a Single Failing Test in Crystal with Atlas in 2026

In 2026, Crystal developers use Atlas to efficiently debug single failing tests. Atlas leverages `crystal spec`, `shards`, and `crystal tool format` to pinpoint and fix issues.

Browse this resource hub