How does Atlas handle renaming a GenServer module in Elixir?

Atlas renames a GenServer module by first using `lsp findReferences` to locate all code usages, including `start_link` calls and supervision tree entries in `lib/my_app/application.ex`. It then uses `grep` for any string references, applies changes with `edit replaceAll`, and verifies with `mix test`.

Can Atlas rename a field in an Elixir struct or a map key?

Yes, Atlas can rename fields in Elixir structs or map keys. For struct fields, `lsp findReferences` will identify direct accesses. For dynamic map keys or string-based references, `grep` is used to catch all occurrences, followed by `edit replaceAll` and `mix test` verification.

What if my Elixir project uses multiple `mix.exs` files or OTP applications?

Atlas is designed to work across `mix` projects and OTP applications. When run in the root of your repository, it can index and operate across the entire codebase, ensuring that renames are applied consistently even if symbols are referenced across different `mix.exs` defined applications.

How does Atlas ensure my Elixir tests still pass after a rename?

After applying the rename, Atlas explicitly runs `ExUnit via mix test` using its `bash` tool. This step is integrated into the workflow to immediately catch any regressions or broken references, ensuring the refactored Elixir codebase remains fully functional and verified by your existing test suite.

Does Atlas integrate with `mix format` for Elixir code style during refactoring?

Yes, Atlas integrates with `mix format`. As part of the verification steps, you can instruct Atlas to run `mix format` via its `bash` tool, typically alongside `mix test`. This ensures that your Elixir code remains consistently formatted according to your project's style guidelines after the rename.

How does Atlas prevent accidental renames of similar-looking Elixir symbols?

Atlas prevents accidental renames through its multi-stage approach. `lsp findReferences` provides precise, AST-based matches for code. For `grep` and `edit`, the `replaceAll` operation is explicit, and all changes are presented as unified diffs for your approval, allowing you to review and reject any unintended matches before they are written to your Elixir files.

Rename a symbol across the repo in Elixir with Atlas in 2026

In 2026, renaming a function, module, or constant across an Elixir codebase with Atlas ensures accuracy by leveraging the `lsp` tool for authoritative references, `grep` for non-code occurrences, and `edit` for precise modifications, all verified by `ExUnit via mix test`. This multi-stage approach prevents the common pitfalls of naive find-and-replace, guaranteeing a complete and correct refactor across your `mix` projects and OTP applications.

How Atlas Renames Elixir Symbols Safely

In 2026, Atlas renames Elixir symbols with a multi-stage approach, combining 3 distinct tools to ensure comprehensive and safe refactoring across your `mix` projects. This process starts with identifying all code references and extends to non-code occurrences, providing a 100% complete rename.

Renaming a symbol in an Elixir codebase, whether it's a function, module, or constant, requires more than a simple text search. Atlas addresses this by orchestrating a workflow that leverages the strengths of several tools. First, it queries the Elixir language server via its `lsp` tool to get an authoritative list of code references. This is crucial for Elixir, where module aliases, macros, and dynamic calls can make static analysis challenging. Next, Atlas uses its `grep` tool to find instances of the old symbol name in comments, documentation, and configuration files like `config/config.exs` or `mix.exs` descriptions, which the language server might not track. Finally, the `edit` tool performs the mechanical replacements, offering strict control and requiring explicit approval for every change, ensuring no unintended modifications occur. This comprehensive strategy is designed to handle the complexities of Elixir's dynamic nature and OTP application structure.

Leveraging Elixir's LSP for Accurate References

Atlas begins by querying the Elixir language server via its `lsp` tool, which provides an authoritative list of 100% accurate references for any given symbol within your `mix` project. This initial step is vital for correctly identifying all call sites and declarations in Elixir code, avoiding the 2026 pitfalls of regex-only searches.

For Elixir code, the `lsp` tool is the cornerstone of accurate symbol renaming. When you ask Atlas to rename a function like `MyModule.old_function/2` or a module `MyOldModule`, Atlas invokes the `findReferences` operation on the Elixir language server. This server, built on robust parsing capabilities, understands Elixir's Abstract Syntax Tree (AST) declarations using tree-sitter. It can correctly identify all usages, including those behind `alias` statements, `import` directives, or within complex macro expansions, which a simple text search would either miss or wrongly match. This ensures that every single code reference, from a `GenServer` callback to a `Plug` pipeline, is precisely located, providing a verified set of targets for the rename operation. Atlas's ability to connect to Model Context Protocol servers means it can expose these powerful language server capabilities directly to the agent, making intelligent refactoring possible.

Catching Non-Code Occurrences with Grep

Beyond compiler-visible code, Atlas uses its `grep` tool to find the old symbol name in comments, documentation, and configuration files like `config/config.exs`, ensuring a 360-degree rename. This step is critical for maintaining consistency across all 2026 project assets, not just executable Elixir code.

While the `lsp` tool provides an authoritative list of code references, many occurrences of a symbol exist outside the type system. These include comments within `.ex` files, documentation strings (docstrings) for modules and functions, `README.md` files, and configuration files such as `config/config.exs` or `mix.exs` where a module name might be referenced as a string. For example, a `GenServer` module name might appear in a supervision tree definition in `lib/my_app/application.ex` as an atom, or in a comment explaining its purpose. Atlas's `grep` tool is specifically employed to catch these instances. By running `grep` for the old symbol name, Atlas ensures that every textual mention is identified, preventing stale references that could confuse future developers or break documentation builds. This dual approach of `lsp` for code and `grep` for everything else guarantees a truly comprehensive rename.

Applying Changes with Atlas's Edit Tool

The `edit` tool in Atlas performs the mechanical renaming, offering precise control and safety mechanisms, including a strict `replaceAll` mode for 1-to-1 replacements. Every proposed change is presented as a unified diff for approval, ensuring you have 100% control over the refactoring process in 2026.

Once Atlas has identified all instances of the symbol to be renamed, the `edit` tool takes over to apply the changes. For a global rename, Atlas uses `replaceAll`, which is designed for mechanical, unambiguous substitutions. A key safety feature of `edit` is its refusal of ambiguous single replacements; if it finds multiple matches for `oldString` in a file when not in `replaceAll` mode, it throws an error rather than silently corrupting the file. This prevents unintended matches from being changed. Before any file is written, Atlas computes a unified diff for every edit and surfaces it for your approval. This allows you to review exactly what changes will be made, file by file, ensuring the integrity of your Elixir codebase. Atlas's read-only plan agent drafts the refactoring strategy, and only after your explicit approval does it switch to a build agent to execute the `edit` commands, providing a robust safety net for critical refactoring tasks.

Verifying Elixir Renames with Mix Test and Grep

After applying changes, Atlas uses the `bash` tool to run `ExUnit via mix test`, ensuring the Elixir application remains functional, followed by a final `grep` pass to confirm zero remaining instances of the old symbol. This 2-step verification process is crucial for guaranteeing a successful refactor in 2026.

The final and arguably most critical steps in renaming an Elixir symbol involve rigorous verification. Atlas leverages its `bash` tool to execute your project's test suite, specifically `ExUnit via mix test`. Running `mix test` immediately after the rename confirms that the refactoring has not introduced any regressions and that all existing functionality remains intact. This is a non-negotiable step for any significant change in an Elixir codebase. Additionally, Atlas can run `mix format` to ensure code style consistency. Following the tests, Atlas performs one more `grep` for the old symbol name across the entire repository. The goal here is to prove zero remaining hits, providing absolute confidence that the rename is complete and no lingering references exist. This comprehensive verification loop, combining automated testing with a final textual audit, ensures the highest level of quality and correctness for your Elixir refactoring efforts.

Step by step

01Start Atlas in your Elixir project directory containing `mix.exs`.
02Use the `lsp` tool to find all authoritative code references for the symbol. For example, to rename `MyOldModule.my_old_function/1`, you might start with: `atlas run lsp findReferences MyOldModule.my_old_function`.
03Run the `grep` tool to identify non-code occurrences of the old symbol name in comments, documentation, and configuration files: `atlas run grep MyOldModule.my_old_function`.
04Apply the mechanical renames using the `edit` tool with `replaceAll`. For instance: `atlas run edit replaceAll MyOldModule.my_old_function MyNewModule.my_new_function`.
05Review the unified diffs presented by Atlas for each file edit and approve them to write the changes to disk.
06Execute your Elixir test suite and formatter using the `bash` tool to verify functionality and code style: `atlas run bash "mix format && mix test"`.
07Perform a final `grep` for the old symbol name to confirm zero remaining instances: `atlas run grep MyOldModule.my_old_function`.
08Stage and commit your changes using Atlas's git integration: `atlas run git add . && atlas run git commit -m "Refactor: Rename MyOldModule.my_old_function to MyNewModule.my_new_function"`.

Frequently asked questions

How does Atlas handle renaming a GenServer module in Elixir?: Atlas renames a GenServer module by first using `lsp findReferences` to locate all code usages, including `start_link` calls and supervision tree entries in `lib/my_app/application.ex`. It then uses `grep` for any string references, applies changes with `edit replaceAll`, and verifies with `mix test`.
Can Atlas rename a field in an Elixir struct or a map key?: Yes, Atlas can rename fields in Elixir structs or map keys. For struct fields, `lsp findReferences` will identify direct accesses. For dynamic map keys or string-based references, `grep` is used to catch all occurrences, followed by `edit replaceAll` and `mix test` verification.
What if my Elixir project uses multiple `mix.exs` files or OTP applications?: Atlas is designed to work across `mix` projects and OTP applications. When run in the root of your repository, it can index and operate across the entire codebase, ensuring that renames are applied consistently even if symbols are referenced across different `mix.exs` defined applications.
How does Atlas ensure my Elixir tests still pass after a rename?: After applying the rename, Atlas explicitly runs `ExUnit via mix test` using its `bash` tool. This step is integrated into the workflow to immediately catch any regressions or broken references, ensuring the refactored Elixir codebase remains fully functional and verified by your existing test suite.
Does Atlas integrate with `mix format` for Elixir code style during refactoring?: Yes, Atlas integrates with `mix format`. As part of the verification steps, you can instruct Atlas to run `mix format` via its `bash` tool, typically alongside `mix test`. This ensures that your Elixir code remains consistently formatted according to your project's style guidelines after the rename.
How does Atlas prevent accidental renames of similar-looking Elixir symbols?: Atlas prevents accidental renames through its multi-stage approach. `lsp findReferences` provides precise, AST-based matches for code. For `grep` and `edit`, the `replaceAll` operation is explicit, and all changes are presented as unified diffs for your approval, allowing you to review and reject any unintended matches before they are written to your Elixir files.

Try Atlas in your terminal

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

Install Atlas

Related 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 Elixir in 2026

Adopt Atlas, the terminal-native AI coding agent, for Elixir development in 2026. Enhance productivity with deep code understanding, safety features, and direct integration into mix projects and OTP applications.

Audit an Elixir Repo with Parallel Subagents in 2026 using Atlas

Sweep your Elixir repository for specific problems without blowing your context window. Atlas uses parallel subagents, ExUnit, Mix, and Hex to audit large Elixir codebases efficiently.

Locate Where a Behavior Is Implemented in Elixir With Atlas (2026)

How to locate where a behavior is implemented in an Elixir codebase with Atlas in 2026: codebase_search for meaning, grep for text, and the lsp tool for symbols.

Trace a Runtime Bug From a Stack Trace in Elixir with Atlas (2026)

Trace an Elixir runtime bug from a stack trace in 2026 with Atlas: read each frame at its offset, grep for the error message, findReferences the callers, fix, add ExUnit.

Refactor a legacy module in Elixir with Atlas in 2026

Refactor Elixir modules safely in 2026 with Atlas, the terminal-native AI coding agent. Pin behavior with ExUnit via mix test, map callsites with LSP, and apply changes with atomic patches.

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

Triage a red ExUnit suite in Elixir with Atlas in 2026. Run mix test through bash, read the retained log past the 2000-line truncation, and group causes with grep.

Upgrade a Dependency and Fix Breakage in Elixir with Atlas in 2026

In 2026, Elixir developers use Atlas to direct upgrade dependencies, resolving compile and test failures caused by major version bumps. Leverage Atlas's AI to navigate `mix.exs` changes and fix code.

Browse this resource hub