Atlas empowers Crystal developers in 2026 to rename functions, classes, or constants across their entire repository with precision, integrating directly with `crystal spec`, `shards`, and `crystal tool format` to ensure correctness and maintain code quality. It addresses the challenge of refactoring by going beyond simple text replacement, ensuring all references are updated accurately.
How Atlas Ensures Accurate Renames in Crystal Codebases
Renaming a symbol in a Crystal project in 2026 requires more than a simple text search; Atlas performs a 2-stage lookup to ensure accuracy. It first queries the language server for precise references, then uses `grep` to find 100% of other mentions like comments or documentation.
Atlas employs a hybrid approach to ensure every instance of a Crystal symbol is correctly identified and renamed. It begins by utilizing the `lsp` tool's `findReferences` operation, which queries the language server to obtain an authoritative list of all callsites and declarations within the type system. This ensures that functions, classes, and constants are accurately tracked across your Crystal project, including complex scenarios like union types or module-scoped constants. Following this, Atlas runs `grep` for the old symbol name. This step is crucial for catching occurrences outside the compiler's view, such as string literals, comments, documentation blocks, or even configuration files like `shard.yml`. The mechanical renaming is then performed using the `edit` tool with `replaceAll`, which is designed to handle these changes efficiently. Importantly, `edit` refuses ambiguous single replacements, preventing unintended matches from corrupting your Crystal codebase.
Verifying Crystal Renames with `crystal spec` and `shards`
After Atlas performs a symbol rename in a Crystal project, it integrates directly with your existing toolchain to verify the changes. Atlas runs `crystal spec` to confirm all 0 tests pass and ensures `shards` dependencies remain consistent, preventing regressions.
Maintaining the integrity of your Crystal project is paramount during a refactor. Atlas leverages the `bash` tool to execute your project's test suite by running `crystal spec`. This immediate feedback loop confirms that the renamed symbol has not introduced any regressions or broken existing functionality. If `crystal spec` reports any compiler errors or test failures, Atlas can iterate on potential fixes, guiding you through the debugging process. Furthermore, Atlas operates within the context of your project's `shard.yml` and `lib/` directories. While `shards` itself is not directly invoked for renaming, Atlas's `grep` capabilities can identify if the old symbol name appears in dependency configurations or generated files, allowing for comprehensive verification that your project's dependencies remain correctly resolved after the rename.
Atlas's Safety and Review Process for Crystal Refactoring
Atlas provides multiple layers of safety for refactoring Crystal code, ensuring you maintain full control over every change. Before any modification, Atlas drafts a read-only plan, then presents a unified diff for your approval, preventing 100% of unintended edits.
The safety mechanisms built into Atlas are designed to give Crystal developers confidence during complex refactoring tasks like symbol renames. Every Atlas tool call is permission-gated, allowing you to set `allow`, `ask`, or `deny` rules before any action is taken. Before making any changes, Atlas drafts a comprehensive plan in a read-only plan agent, which you must approve before it switches to a build agent to execute the modifications. For every file edit, Atlas computes a unified diff and surfaces it for your explicit approval, ensuring transparency and preventing silent corruption. Atlas also snapshots file changes as git patches, providing a robust rollback mechanism if any edits need to be reverted. This meticulous review process ensures that all changes to your Crystal codebase are intentional and verified by you.
Concrete Steps to Rename a Crystal Symbol with Atlas
Renaming a Crystal symbol with Atlas involves a clear, step-by-step process that leverages its intelligent agents and your familiar toolchain. This workflow ensures 100% accuracy, from initial symbol identification to final verification with `crystal spec`.
The process of renaming a function, class, or constant in a Crystal project with Atlas is streamlined and highly accurate. You begin by running Atlas within your project, ensuring it has indexed your code and understands its structure, including your `shard.yml` and `spec/` directories. You then instruct Atlas to perform the rename. Atlas first uses its `lsp` tool to query the language server for all authoritative references. Concurrently, it employs `grep` to find any non-code occurrences. Atlas then presents a unified diff of all proposed changes, which you review and approve. After approval, Atlas automatically runs `crystal spec` to validate the changes and `crystal tool format` to maintain code style. This iterative process ensures that the rename is complete, correct, and adheres to your project's standards, culminating in a final `grep` check to confirm zero remaining instances of the old symbol.
Step by step
- 01Run Atlas in your Crystal project, ensuring it has indexed your `shard.yml` and code structure.
- 02Ask Atlas to rename your symbol (e.g., 'Rename `MyOldFunction` to `MyNewFunction`'). Atlas will use `lsp` `findReferences` to get the true reference set from the Crystal language server.
- 03Atlas will then use `grep` for the old symbol name to catch occurrences in comments, strings, documentation, and configuration files like `shard.yml`.
- 04Review Atlas's proposed changes, presented as a unified diff. Atlas uses the `edit` tool with `replaceAll` for mechanical changes, ensuring unambiguous matches per file.
- 05Approve the changes. Atlas will then run `bash -c "crystal spec"` to execute your tests and `bash -c "crystal tool format"` on the diff to ensure code style.
- 06If `crystal spec` reports failures or `crystal tool format` identifies issues, Atlas will iterate, suggesting and applying fixes until the Crystal codebase is stable.
- 07Once tests pass and formatting is correct, Atlas will `grep` one final time for the old symbol name to prove zero remaining hits in your Crystal project.
- 08Approve the final commit, which Atlas can stage and create on your behalf, completing the Crystal symbol rename.
Frequently asked questions
- How does Atlas handle renaming a Crystal class used in a union type?
- Atlas leverages the `lsp` tool's `findReferences` to accurately identify all usages of a Crystal class, including its presence within union types, ensuring every reference is updated correctly across your codebase.
- Can Atlas rename a constant defined in a Crystal module?
- Yes, Atlas can rename constants within Crystal modules. It uses `lsp` to find all declarations and references, then the `edit` tool to apply the changes across your codebase, maintaining consistency.
- What if `grep` finds the old name in a Crystal string literal that shouldn't change?
- Atlas's `edit` tool refuses ambiguous single replacements. If `grep` finds a string literal that shouldn't change, you can provide more context to `edit` or explicitly approve/deny specific changes during the diff review process.
- How does Atlas ensure my Crystal tests still pass after a rename?
- After applying changes, Atlas uses the `bash` tool to execute `crystal spec`. It will report any failures and can help iterate on fixes until all your Crystal tests pass, ensuring code integrity.
- Does Atlas integrate with `shards` for Crystal dependency updates during a rename?
- While Atlas primarily focuses on code changes, it operates within your Crystal project's context. If a rename impacts `shard.yml` or `lib/` paths, Atlas's `grep` will find these, and you can verify `shards install` still functions correctly.
- Can Atlas format the renamed Crystal code automatically?
- Yes, Atlas can run `crystal tool format` on the generated diff before you approve it, ensuring your renamed Crystal code adheres to your project's formatting standards and best practices.
- What if I need to roll back a rename Atlas performed in my Crystal project?
- Atlas snapshots file changes as git patches. This allows you to easily diff and roll back any edits made during the rename process, providing a robust safety net for your Crystal codebase.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Rename a Symbol Across the Repo with Atlas in 2026
How to rename a symbol across a repo with Atlas in 2026: findReferences gets the true reference set, grep catches strings and docs, and edit refuses ambiguous matches.
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.
Add a Regression Test for a Crystal Bug Fix with Atlas in 2026
In 2026, Crystal developers use Atlas to add regression tests for bug fixes, ensuring code quality. Learn how Atlas leverages `crystal spec` and `shards` to lock in fixes with red-green testing.
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.
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.
Run Atlas Headless in CI in Crystal with Atlas in 2026
Learn how to integrate Atlas into your Crystal CI pipelines in 2026, running headless to automate code tasks, execute `crystal spec`, and format code with `crystal tool format`.
Migrate a deprecated API across every callsite in Crystal with Atlas in 2026
In 2026, use Atlas to systematically migrate deprecated Crystal APIs across your entire codebase. Leverage `crystal spec`, `shards`, and `crystal tool format` for a safe, verified transition, ensuring no callsite is
Extract a Shared Helper from Duplicated Code in Crystal with Atlas in 2026
Refactor your Crystal codebase in 2026 by extracting duplicated logic into a shared helper using Atlas. Leverage semantic search, automated code generation, and `crystal spec` integration for safe, type-checked