How does Atlas understand my Solidity contracts without me telling it what to look for?

Atlas builds its code index by parsing AST declarations using tree-sitter, not just keywords. This means it understands the structure of your Solidity contracts, their functions, modifiers, and storage layouts, allowing it to respond to semantic queries about your codebase without explicit guidance.

Can Atlas help me understand the dependencies installed by `soldeer`?

Yes, Atlas can read the libraries installed by `forge soldeer`. When you run Atlas in your Foundry project, it indexes these dependencies alongside your own `src/` contracts, allowing `codebase_search` and `lsp`'s `goToDefinition` to navigate through external Solidity code just as effectively as your internal files.

How does Atlas ensure I don't accidentally break my Solidity code while exploring?

Atlas employs several safety mechanisms. Its `explore` subagent is permissioned read-only, preventing any modifications. For any proposed changes, Atlas drafts a plan in a read-only agent, asks for approval before switching to a build agent, and computes a unified diff for every file edit, which you must approve before writing. It can also run `forge snapshot` to show gas deltas for Solidity changes.

Can Atlas run `forge test` or `forge fmt` for me?

Yes, Atlas can run `forge test` and `forge fmt`. It will ask for permission before executing `forge test` on your `test/` files. After you approve a code change, Atlas can automatically run `forge fmt` on the diff to ensure your Solidity code adheres to formatting standards, streamlining your development workflow.

What if I need to search for a specific string across many Solidity files?

For wide sweeps like searching for a specific string, you can delegate this task to the `explore` subagent using the `task` tool. The `explore` subagent has permission to use `grep`, allowing it to efficiently search across numerous Solidity files in your `src/` directory or `test/` directory without the ability to modify them.

How does Atlas help me keep track of what I've learned about a new Solidity codebase?

Atlas provides the `todowrite` tool, which allows you to record your findings, observations, and open questions as you explore the codebase. This creates a persistent list that helps you maintain your mental model, ensuring that important insights about Solidity contracts, modifiers, or storage layouts are not lost across sessions.

Onboard to an Unfamiliar Solidity Codebase with Atlas in 2026

Solidity developers in 2026 can build a working mental model of an unfamiliar repository without reading every file by pairing Atlas with their Foundry project, leveraging its semantic search, AST indexing, and direct integration with tools like `forge test`, `soldeer (forge soldeer install)`, and `forge fmt` to quickly understand contracts, storage layouts, and modifiers.

How Atlas Understands Solidity Codebases with Semantic Search

Atlas begins understanding a Solidity codebase by indexing its AST declarations, not blind line windows, allowing it to grasp the meaning of contracts, functions, and variables. This approach, available in 2026, ensures that when you ask about how requests are authenticated, Atlas queries a semantic index built with local Ollama embeddings, keeping your sensitive Solidity code off third-party servers.

When you encounter an unfamiliar Solidity project, Atlas does not rely on simple keyword matching. Instead, it builds a deep understanding of your `src/` directory by indexing code via AST declarations using tree-sitter. This means Atlas comprehends the structure of your Solidity contracts, the parameters of your functions, and the purpose of your modifiers. For instance, if you ask Atlas a plain-language question like "how requests are authenticated," its `codebase_search` tool queries this semantic index. It returns ranked snippets directly relevant to authentication logic within your Solidity files, providing precise context and file paths. This initial step bypasses the need to manually grep through hundreds of files, immediately pointing you to the most relevant parts of the codebase, whether it is a specific `onlyOwner` modifier or a custom access control contract.

Exploring Solidity Project Structure and Dependencies

To quickly grasp the layout of a new Solidity project, Atlas uses the `glob` tool to map top-level directories and identify naming conventions, a crucial step before diving into specific files. In 2026, understanding the `foundry.toml` configuration and the `src/` and `test/` directories is paramount for any Solidity developer, and Atlas streamlines this initial structural overview.

After an initial semantic search, understanding the physical layout of a Solidity project is the next critical step. Atlas's `glob` tool allows you to quickly survey the top-level directories, revealing the project's package layout and naming conventions. This helps you identify key directories like `src/` for contracts, `test/` for tests, and the presence of a `foundry.toml` configuration file. Once you have a high-level map, you can use the `read` tool to pull the two or three files `codebase_search` ranked highest. For example, you might read a core contract in `src/MyContract.sol` or a critical interface. From there, Atlas's `lsp` tool can follow imports with its `goToDefinition` operation, allowing you to navigate through the contract dependencies and understand how different Solidity files interact, much like you would in your IDE, but directly within your terminal.

Delegating Deep Dives with the Atlas Explore Subagent

For wide sweeps and detailed investigations into a Solidity codebase, Atlas delegates work to its `explore` subagent, which operates with a deny-by-default permission set. This ensures that in 2026, while the subagent can use tools like `grep`, `glob`, and `read` to look around, it cannot inadvertently modify any Solidity files or configuration, providing a safe environment for extensive exploration.

When you need to perform a more extensive investigation or understand a complex subsystem within a Solidity project, you can delegate this heavy fan-out work to the `explore` subagent using the `task` tool. This subagent is specifically designed for read-only operations, with a deny-by-default permission set that only allows safe tools such as `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`. This means the `explore` subagent can search for specific Solidity patterns across many files, list all `.sol` files in a directory, read contract code, or even fetch external documentation, all without the ability to write or modify any part of your Foundry project. This read-only guarantee is crucial for maintaining the integrity of your codebase while you are still building your mental model, especially when dealing with the security-sensitive nature of Solidity contracts.

Ensuring Safety and Review in Solidity Codebase Modifications

Atlas prioritizes safety and explicit approval for any changes to a Solidity codebase, ensuring every tool call is permission-gated against allow, ask, and deny rules. In 2026, before any edits are written, Atlas computes a unified diff and can even run `forge snapshot` to show gas deltas, providing full transparency and control over your smart contract modifications.

The security implications of Solidity development mean that any code modification must be carefully reviewed. Atlas is built with this in mind. Every tool call is permission-gated, requiring explicit approval based on allow, ask, or deny rules. When Atlas drafts a plan, it does so in a read-only plan agent and asks for your approval before switching to a build agent that can make changes. Before writing any file, Atlas computes a unified diff for every proposed edit and surfaces it for your approval. For Solidity projects, this extends to critical development practices: Atlas can write a fuzz test in your `test/` directory, but it will ask for permission before running `forge test`. Crucially, it can also run `forge snapshot` so you can see the gas delta of any proposed changes before approving them. After approval, Atlas can even run `forge fmt` on the diff to ensure your Solidity code adheres to formatting standards, providing a comprehensive and secure review process.

Recording and Persisting Learnings in Solidity Onboarding

To ensure that insights gained during the onboarding process are not lost, Atlas allows you to record what you learned as a `todowrite` list, preserving open questions and key findings. This feature, vital for any complex Solidity project in 2026, helps maintain continuity across multiple turns and ensures that your evolving mental model is documented.

Building a mental model of a large Solidity codebase is an iterative process, and it is easy to lose track of important discoveries or remaining questions. Atlas addresses this with the `todowrite` tool. As you explore contracts, understand storage layouts, or identify critical modifiers, you can use `todowrite` to record your findings, observations, and any open questions. This creates a persistent list that survives across different Atlas sessions and turns. For example, you might note, "`MyContract.sol` uses `ERC20Permit` for gasless approvals, need to investigate signature verification in `_permit()`" or "Confirm `soldeer` dependencies are up-to-date." This ensures that your evolving understanding of the Solidity project is documented, allowing you to pick up exactly where you left off and systematically address remaining unknowns.

Step by step

01Run Atlas in your Foundry project, ensuring it can read your `foundry.toml`, `src/` directory, and `soldeer` installed libraries.
02Ask Atlas's `codebase_search` tool a plain-language question about a core concept, such as "how requests are authenticated in `src/`", to get ranked Solidity snippets and file paths.
03Use the `glob` tool to inspect top-level directories and understand the project's structure, like the layout of `src/` and `test/`.
04Read the top two or three Solidity files identified by `codebase_search` using the `read` tool, then follow contract imports and function definitions with the `lsp` tool's `goToDefinition` operation.
05Delegate wide sweeps or complex investigations to the `explore` subagent via the `task` tool, allowing it to `grep` for specific Solidity patterns or `read` multiple files without making changes.
06Record your findings, open questions, and insights about the Solidity codebase using the `todowrite` tool to build a persistent mental model.
07If proposing a change, like adding a reentrancy guard, review the unified diff Atlas presents and approve it. Optionally, have Atlas run `forge snapshot` to see the gas delta before final approval.
08After approving changes, let Atlas run `forge fmt` on the modified Solidity files to ensure consistent code style.

Frequently asked questions

How does Atlas understand my Solidity contracts without me telling it what to look for?: Atlas builds its code index by parsing AST declarations using tree-sitter, not just keywords. This means it understands the structure of your Solidity contracts, their functions, modifiers, and storage layouts, allowing it to respond to semantic queries about your codebase without explicit guidance.
Can Atlas help me understand the dependencies installed by `soldeer`?: Yes, Atlas can read the libraries installed by `forge soldeer`. When you run Atlas in your Foundry project, it indexes these dependencies alongside your own `src/` contracts, allowing `codebase_search` and `lsp`'s `goToDefinition` to navigate through external Solidity code just as effectively as your internal files.
How does Atlas ensure I don't accidentally break my Solidity code while exploring?: Atlas employs several safety mechanisms. Its `explore` subagent is permissioned read-only, preventing any modifications. For any proposed changes, Atlas drafts a plan in a read-only agent, asks for approval before switching to a build agent, and computes a unified diff for every file edit, which you must approve before writing. It can also run `forge snapshot` to show gas deltas for Solidity changes.
Can Atlas run `forge test` or `forge fmt` for me?: Yes, Atlas can run `forge test` and `forge fmt`. It will ask for permission before executing `forge test` on your `test/` files. After you approve a code change, Atlas can automatically run `forge fmt` on the diff to ensure your Solidity code adheres to formatting standards, streamlining your development workflow.
What if I need to search for a specific string across many Solidity files?: For wide sweeps like searching for a specific string, you can delegate this task to the `explore` subagent using the `task` tool. The `explore` subagent has permission to use `grep`, allowing it to efficiently search across numerous Solidity files in your `src/` directory or `test/` directory without the ability to modify them.
How does Atlas help me keep track of what I've learned about a new Solidity codebase?: Atlas provides the `todowrite` tool, which allows you to record your findings, observations, and open questions as you explore the codebase. This creates a persistent list that helps you maintain your mental model, ensuring that important insights about Solidity contracts, modifiers, or storage layouts are not lost across sessions.

Try Atlas in your terminal

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

Install Atlas

Related guides

Onboard to an Unfamiliar Codebase with Atlas in 2026

How to onboard to an unfamiliar codebase with Atlas in 2026: use codebase_search, glob, read, lsp, task, and todowrite to build a mental model fast.

Add a Regression Test for a Solidity Bug Fix with Atlas in 2026

Lock in Solidity bug fixes with Atlas by adding regression tests. Learn how Atlas uses `forge test` to confirm failures and passes, ensuring robust smart contract development in 2026.

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.

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

Rename Solidity functions, classes, or constants across your entire repository with Atlas. Leverage precise LSP references and `forge test` verification for safe, accurate refactoring in 2026.

Trace a Runtime Bug from a Solidity Stack Trace with Atlas in 2026

Pinpoint and fix Solidity runtime bugs from production stack traces using Atlas. Leverage Foundry's `forge test` and `soldeer` for a secure, gas-efficient workflow.

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.

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.

Browse this resource hub