How does Atlas handle renaming overloaded Solidity functions?

Atlas leverages the `lsp` tool's deep understanding of Solidity's Abstract Syntax Tree (AST). When renaming an overloaded function, `lsp findReferences` can distinguish between different function signatures, ensuring that only the intended overload (or all if specified) is targeted for renaming, maintaining contract integrity.

Can Atlas rename state variables and events in Solidity contracts?

Yes, Atlas can rename any Solidity symbol, including state variables, events, custom errors, structs, enums, and modifiers. The `lsp` tool accurately identifies all declarations and usages of these symbols across your `src/` directory and `soldeer` libraries, ensuring a complete and safe refactor.

What if my Solidity project uses multiple compiler versions?

Atlas operates within your existing Foundry project setup. As long as your language server (e.g., Solidity Language Server) is correctly configured to handle your project's specific compiler versions and `foundry.toml` settings, Atlas's `lsp` tool will function accurately, providing correct references regardless of version complexity.

How does Atlas ensure gas cost stability after a Solidity rename?

While renaming itself typically doesn't alter gas costs, Atlas integrates with your Foundry toolchain. After a rename, Atlas can prompt you to run `forge snapshot`. This command captures the gas usage of your contract functions, allowing you to compare the gas delta before and after the refactor and confirm no unintended performance changes.

Does Atlas require my Solidity code to be pushed to a remote server?

No, Atlas is terminal-native and can build its code index with local Ollama embeddings, keeping your Solidity code entirely off third-party servers. All operations, including `lsp` queries and `grep` searches, are performed locally within your development environment.

What happens if Atlas finds an ambiguous match during a Solidity rename?

If Atlas's `edit` tool finds multiple matches for a string when you intended a single, specific change, it will throw an error (e.g., 'Found multiple matches for oldString'). This prevents unintended alterations to your Solidity code, requiring you to provide more context or explicitly opt into a `replaceAll` operation for that specific file.

Can Atlas help me format my Solidity code after a rename?

Yes, after applying renames, Atlas can automatically run `bash forge fmt` on the modified files or the entire project. This ensures that all changes adhere to your project's formatting standards, maintaining code consistency and readability within your Solidity codebase.

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

Atlas enables Solidity developers in 2026 to rename functions, classes, or constants across an entire repository with precision, leveraging the `lsp` tool for authoritative references, `grep` for comprehensive coverage, and `edit` for controlled application. This process integrates direct with your existing Foundry toolchain, including `forge test` for verification, `soldeer (forge soldeer install)` for dependencies, and `forge fmt` for consistent formatting.

How Atlas renames Solidity symbols safely and accurately

Renaming a Solidity symbol across an entire repository in 2026 requires more than simple text replacement; Atlas leverages its `lsp` tool to precisely identify all true references, ensuring no critical contract logic is missed. This process begins by querying the language server for an authoritative list of call sites and declarations, providing a 100% accurate starting point for refactoring.

Atlas approaches Solidity symbol renaming with a multi-stage strategy designed for accuracy and safety, crucial in an environment where every line of code has potential gas costs and security implications. Unlike naive find-and-replace operations that can corrupt contract logic or introduce subtle bugs, Atlas first uses the `lsp` (Language Server Protocol) tool's `findReferences` operation. This connects directly to your Solidity language server, which understands the Abstract Syntax Tree (AST) of your contracts, storage layout, modifiers, and libraries installed by `forge soldeer`. It provides an authoritative list of every declaration and usage of the target symbol, whether it's a function, a state variable, an event, or a custom error. This AST-based indexing, powered by tree-sitter, ensures that only actual code references are identified, avoiding false positives that a simple text search might yield. The `lsp` tool is fundamental to ensuring the integrity of your Solidity codebase during complex refactoring tasks.

Using `lsp` for precise Solidity symbol references

The `lsp` tool is the cornerstone of accurate Solidity symbol renaming, providing an authoritative list of references directly from the language server. In 2026, Atlas uses `lsp findReferences` to query the AST, ensuring that every call site, declaration, and usage of a function, event, or state variable is correctly identified, preventing critical errors in your `src/` directory.

For Solidity projects, the `lsp` tool is indispensable for refactoring. When you initiate a rename, Atlas first executes `lsp findReferences` on the specific Solidity symbol you wish to change. This command interacts with the language server configured for your Foundry project, which has a deep understanding of Solidity's syntax and semantics. It can distinguish between a function `transfer()` and a comment containing the word "transfer," or a variable named `owner` from a string literal "owner." This precision is vital for Solidity contracts, where an incorrect rename could lead to compilation failures, runtime errors, or even security vulnerabilities. The `lsp` tool ensures that Atlas only targets actual code references within your `.sol` files, including those within `src/` and any installed `soldeer` libraries, providing a robust foundation for the subsequent renaming steps.

Catching non-code references with `grep` in Solidity projects

While `lsp` handles code references, Atlas employs `grep` to catch non-code occurrences of a Solidity symbol, such as those in comments, NatSpec documentation, or configuration files. This ensures a comprehensive rename, covering 100% of mentions that the compiler might overlook, like a function name referenced in a `foundry.toml` script or a `test/` file's description.

After gathering precise code references with `lsp`, Atlas then runs `grep` for the old symbol name across the entire repository. This step is crucial for catching occurrences that fall outside the type system's purview but are still important for a complete refactor. This includes comments within your Solidity contracts, NatSpec documentation blocks (e.g., `/// @notice MyOldFunctionName`), markdown files, or even configuration files like `foundry.toml` or scripts in your `test/` directory that might reference the old name. For instance, a `foundry.toml` file might contain a script definition that calls a specific function by name, or a `test/` file might have a descriptive string that includes the function's name. `grep` ensures that these human-readable references are also updated, maintaining consistency and clarity across your entire Solidity project. Atlas's `grep` tool is designed to complement `lsp`, providing a holistic approach to symbol renaming.

Applying renames and ensuring uniqueness with Atlas `edit`

Atlas applies mechanical renames using its `edit` tool, which offers `replaceAll` for unambiguous changes and enforces uniqueness for single occurrences. This prevents accidental corruption in Solidity files, ensuring that if you intend to change only 1 specific instance of a symbol, Atlas will flag multiple matches as an error rather than silently altering unintended code. This precision is critical for maintaining contract integrity.

With a comprehensive list of references from `lsp` and `grep`, Atlas proceeds to apply the mechanical renames using its `edit` tool. The `edit` tool is designed for safe and controlled modifications. For instances where the match is unambiguous per file, `edit` uses `replaceAll` to efficiently update all occurrences. However, a key safety feature for Solidity development is `edit`'s enforcement of uniqueness: if you intend to change a single occurrence of a symbol, but `edit` finds multiple matches for `oldString` in that specific context, it will throw an error. This prevents silent corruption of your Solidity code, forcing you to either add more context to your rename instruction or explicitly opt into `replaceAll` for that specific file. This granular control is paramount in Solidity, where a single misplaced character can have significant security or financial implications. Atlas ensures that every change is intentional and verified, especially when dealing with sensitive contract logic in `src/`.

Verifying Solidity renames with `forge test` and `grep`

After Atlas completes the renaming operations, the final and most critical step is verification using the Solidity toolchain. Atlas prompts you to run `forge test` to confirm that all contract logic remains sound and that 0 regressions have been introduced. Additionally, a final `grep` for the old name proves that no lingering references exist anywhere in the repository, ensuring a clean and complete refactor.

Once Atlas has applied all the renames, the process isn't complete until the changes are thoroughly verified. Atlas integrates directly with your Solidity development workflow by prompting you to run `bash` commands like `forge test`. This executes your entire test suite, ensuring that all contract functionality, modifiers, and interactions with libraries installed by `forge soldeer` are still working as expected. For even greater confidence, Atlas can run `forge snapshot` before and after the rename, allowing you to see the gas delta and confirm that the refactor hasn't inadvertently increased transaction costs. Finally, Atlas performs one more `grep` for the old symbol name across the entire repository. This final `grep` acts as a definitive proof point, confirming that zero instances of the old name remain in any `.sol` file, `foundry.toml`, or documentation, guaranteeing a truly complete and clean refactor. Atlas also offers to run `forge fmt` on the diff to ensure the changes adhere to your project's formatting standards.

Atlas's safety and review process for Solidity refactoring

Atlas prioritizes safety in Solidity refactoring through a multi-layered review process, including permission-gated tool calls and unified diffs. Every Atlas tool call is permission-gated against allow, ask, and deny rules, ensuring you have full control over agent actions. Before any file is written, Atlas computes a unified diff for every edit and surfaces it for your approval, providing 100% transparency and preventing unintended changes to your critical `src/` contracts.

Atlas is built with a strong emphasis on safety and transparency, especially vital for Solidity projects where errors can be costly. Before any tool call, such as `lsp`, `grep`, `edit`, or `bash`, Atlas checks against your defined permission rules (allow, ask, deny), ensuring that you are always in control. The agent first drafts a plan in a read-only 'plan agent' and asks for your approval before switching to a 'build agent' to execute changes. For every file edit, Atlas computes a unified diff, which is then presented to you for explicit approval. This allows you to review every single line change before it's written to disk, providing a critical safety net. Atlas also snapshots file changes as git patches, enabling easy diffing and rollback if needed. Furthermore, Atlas can read git branches, status, and diffs, and can even stage and create commits on your behalf, streamlining the entire refactoring and review workflow within your Foundry project.

Step by step

01Initialize Atlas in your Foundry project, ensuring it can read your `foundry.toml`, `src/` contracts, and `soldeer` installed libraries.
02Ask Atlas to rename your Solidity symbol (e.g., a function `MyOldFunctionName` or a state variable `oldOwner`). Atlas will first use `lsp findReferences` to get an authoritative list of code references from the language server.
03Atlas will then run `grep` for the old symbol name to identify occurrences in comments, NatSpec documentation, and configuration files like `foundry.toml` or `test/` descriptions.
04Review Atlas's proposed plan, which includes the `lsp` and `grep` findings. Approve the plan to proceed to the build phase.
05Atlas will apply the renames using its `edit` tool, utilizing `replaceAll` for unambiguous matches and enforcing uniqueness for single-occurrence changes. Review and approve each unified diff presented by Atlas before it writes to your `.sol` files.
06After renames, Atlas will prompt you to run `bash forge test` to verify that all Solidity contract logic remains correct and no regressions were introduced.
07Atlas will perform a final `bash grep MyOldFunctionName` to confirm that zero instances of the old symbol name remain anywhere in your repository.
08Optionally, Atlas can run `bash forge snapshot` to compare gas costs before and after the rename, and `bash forge fmt` to ensure the diff adheres to formatting standards, then stage and commit the changes.

Frequently asked questions

How does Atlas handle renaming overloaded Solidity functions?: Atlas leverages the `lsp` tool's deep understanding of Solidity's Abstract Syntax Tree (AST). When renaming an overloaded function, `lsp findReferences` can distinguish between different function signatures, ensuring that only the intended overload (or all if specified) is targeted for renaming, maintaining contract integrity.
Can Atlas rename state variables and events in Solidity contracts?: Yes, Atlas can rename any Solidity symbol, including state variables, events, custom errors, structs, enums, and modifiers. The `lsp` tool accurately identifies all declarations and usages of these symbols across your `src/` directory and `soldeer` libraries, ensuring a complete and safe refactor.
What if my Solidity project uses multiple compiler versions?: Atlas operates within your existing Foundry project setup. As long as your language server (e.g., Solidity Language Server) is correctly configured to handle your project's specific compiler versions and `foundry.toml` settings, Atlas's `lsp` tool will function accurately, providing correct references regardless of version complexity.
How does Atlas ensure gas cost stability after a Solidity rename?: While renaming itself typically doesn't alter gas costs, Atlas integrates with your Foundry toolchain. After a rename, Atlas can prompt you to run `forge snapshot`. This command captures the gas usage of your contract functions, allowing you to compare the gas delta before and after the refactor and confirm no unintended performance changes.
Does Atlas require my Solidity code to be pushed to a remote server?: No, Atlas is terminal-native and can build its code index with local Ollama embeddings, keeping your Solidity code entirely off third-party servers. All operations, including `lsp` queries and `grep` searches, are performed locally within your development environment.
What happens if Atlas finds an ambiguous match during a Solidity rename?: If Atlas's `edit` tool finds multiple matches for a string when you intended a single, specific change, it will throw an error (e.g., 'Found multiple matches for oldString'). This prevents unintended alterations to your Solidity code, requiring you to provide more context or explicitly opt into a `replaceAll` operation for that specific file.
Can Atlas help me format my Solidity code after a rename?: Yes, after applying renames, Atlas can automatically run `bash forge fmt` on the modified files or the entire project. This ensures that all changes adhere to your project's formatting standards, maintaining code consistency and readability within your Solidity codebase.

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.

Document a module with a README in Solidity with Atlas in 2026

In 2026, Atlas helps Solidity developers generate accurate READMEs for smart contracts. It uses `forge test`, `soldeer`, and `forge fmt` to reflect current code behavior.

Research a Third-Party API for Solidity Integration with Atlas in 2026

Streamline Solidity API integrations in 2026 with Atlas. Research external APIs, fetch documentation, and verify against Foundry's `forge test` and `forge fmt` standards.

Diagnose a Hanging or Long-Running Command in Solidity with Atlas in 2026

Solidity developers in 2026 can use Atlas to diagnose whether a `forge test` or `forge soldeer install` command is genuinely slow or silently blocked on input, and get it unstuck.

Write Unit Tests for Untested Solidity Code with Atlas in 2026

Add robust unit tests to your Solidity contracts using Atlas. Leverage `forge test`, `soldeer`, and `forge fmt` to ensure code quality and security in 2026.

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

Automate GitHub issue and pull request triage for Solidity projects using Atlas. Safely respond to PRs and issues in 2026, ensuring trusted users and proper context handling with Foundry.

Debug a single failing test in Solidity with Atlas in 2026

In 2026, Atlas helps Solidity developers debug single failing forge test cases within Foundry projects. Pinpoint issues, trace call graphs, and fix smart contract code with AI-driven precision and safety.

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

Catch your own Solidity mistakes before they reach review or CI. Atlas helps you self-review uncommitted diffs in Foundry projects, integrating with forge test and forge fmt.

Browse this resource hub