Atlas onboards you to an unfamiliar Scala codebase by starting from meaning rather than filenames. You ask codebase_search a plain-language question, it queries the semantic index and returns ranked snippets with file paths, glob maps the directory shape of the sbt modules, and read pulls only the files that actually matter. Heavy fan-out is delegated to the explore subagent through the task tool, which is permissioned read-only so it cannot change anything while it looks around. What you learn is recorded as a todowrite list so the open questions survive into the next turn.
How do I understand a new Scala codebase without reading every file?
Atlas starts from meaning, not filenames. Ask codebase_search a plain-language question such as how requests are authenticated, and the semantic index returns ranked snippets with file paths across every sbt module, so you read the 2 or 3 files that matter instead of all 400.
The instinct on a new Scala repo is to open build.sbt, then the top-level package, then follow imports until you are lost. That approach scales badly against a codebase built on traits, implicits, and typeclass derivation, where the code that runs is frequently not the code that is written. Atlas searches with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so the question returns the implementation regardless of what the trait happens to be called. The first files you open are the right ones.
What does glob tell you about an sbt project's structure?
Atlas runs glob on the top-level directories to see the sbt module layout and naming conventions before opening anything. A Scala repo with 6 sbt subprojects, each with its own src/main/scala tree, reveals its architecture in the directory shape long before any file is read.
Directory structure in a Scala project is unusually informative. The presence of a core module with no dependencies, a separate persistence module, and a thin http module tells you the layering. The presence of a single sprawling src/main/scala tells you something else. Atlas maps that with glob first, which costs almost nothing and makes every subsequent read more meaningful, because a file's package path now situates it in the build. build.sbt then confirms which modules depend on which.
How does Atlas follow Scala traits and implicits to the real implementation?
Atlas reads the 2 or 3 files codebase_search ranked highest, then follows imports with the lsp tool's goToDefinition operation. In Scala, where a trait declares and a concrete class or an implicit instance implements, goToDefinition is what gets you from the declaration to the code that actually runs.
Scala hides the implementation more than most languages. A method call resolves through a trait, an implicit conversion, or a typeclass instance summoned from an unrelated companion object, and none of that is visible from the callsite text. The lsp tool's goToDefinition operation asks the Scala language server, which knows the answer. Following one call chain from the http module to the concrete service in the core module teaches you more about the codebase than an hour of scrolling.
What is the Atlas explore subagent and why is it read-only?
The explore subagent is where Atlas delegates wide sweeps of a Scala repo through the task tool. It is defined with a deny-by-default permission set that allows only 6 tools, grep, glob, read, bash, webfetch, and websearch, so it cannot change anything in your sbt project while it looks around.
Onboarding involves a lot of speculative searching, and speculative searching is exactly when you least want an agent writing to disk. The explore subagent cannot: no edit, no write, no apply_patch. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so several questions about the Scala codebase can be investigated at once while your main session stays focused. Every Atlas tool call, in the subagent or out of it, is permission-gated against allow, ask, and deny rules before it runs.
How do you keep what you learned about a Scala repo from evaporating?
Atlas records what you learned as a todowrite list, so the open questions about the Scala codebase survive into the next turn. 3 unanswered questions about how the sbt modules wire together become 3 todowrite entries, not 3 things you will have forgotten by tomorrow morning.
Onboarding produces two outputs: understanding, and a list of things you still do not understand. The second one is the one that gets lost. Atlas writes it down. An entry might be to work out how the implicit ExecutionContext is provided in the http module, or which sbt subproject owns the database migrations. The list persists in the session, and the next question you ask picks up from it rather than from a blank page.
How do you verify your mental model of a Scala codebase is right?
Atlas runs ScalaTest via sbt test through the bash tool so you can watch the behavior you just read about actually execute. Scoping the run to the 1 sbt module you are studying keeps the output readable, and a mental model never checked against a green sbt test run is a hypothesis, not knowledge.
Start atlas in a project with a build.sbt and it reads your traits, implicits, and sbt modules. Running the ScalaTest suite for the one module you are studying, rather than the whole build, keeps the feedback fast and the output readable. When you are ready to make a first change, Atlas can refactor to typeclasses or add ScalaTest cases, scalafmt keeps the file consistent, and Atlas computes a unified diff for every file edit and surfaces it for approval before writing.
Step by step
- 01Run atlas in a project with a build.sbt and let Atlas read your traits, implicits, and sbt modules.
- 02Ask codebase_search a plain-language question, for example how requests are authenticated; it queries the semantic index and returns ranked snippets with file paths.
- 03Run glob on the top-level directories to see the sbt module layout and naming conventions before opening anything.
- 04Read the two or three files codebase_search ranked highest, then follow imports with the lsp tool's goToDefinition operation to get from a Scala trait to its concrete implementation.
- 05Delegate wide sweeps to the explore subagent through the task tool: it is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch.
- 06Record what you learned, and what you still do not know, as a todowrite list so the open questions survive into the next turn.
- 07Run ScalaTest via sbt test for the one module you are studying, through the bash tool, to watch the behavior you just read about execute.
- 08When you make a first change, run scalafmt over the touched Scala files and review the unified diff Atlas surfaces before approving the write.
Frequently asked questions
- how to onboard to a large Scala codebase quickly
- Ask codebase_search a plain-language question and read the two or three files it ranks highest. Run glob to see the sbt module layout, follow imports with the lsp tool's goToDefinition operation, and record open questions in a todowrite list.
- how do I find the real implementation behind a Scala trait
- Use the lsp tool's goToDefinition operation. In Scala the code that runs is often reached through a trait, an implicit conversion, or a typeclass instance, none of which is visible from the callsite text. The language server knows where the implementation lives.
- can an AI agent explore my repo without being able to change it
- Yes. Atlas delegates wide sweeps to the explore subagent through the task tool, and the explore subagent has a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch. It has no edit or write access.
- does Atlas understand sbt multi-module projects
- Yes. Start atlas in a project with a build.sbt and it reads your traits, implicits, and sbt modules. Running glob on the top-level directories maps the module layout, and build.sbt confirms which subprojects depend on which.
- how do I remember what I learned about an unfamiliar codebase
- Record it as a todowrite list. Atlas keeps both what you learned and the questions you still cannot answer, such as which sbt subproject owns the database migrations, so they survive into the next turn instead of evaporating.
- does Atlas work with sbt, ScalaTest, and scalafmt
- Yes. Atlas runs ScalaTest via sbt test through the bash tool, which is a real shell, and can run scalafmt over the files it touches. It can refactor to typeclasses or add ScalaTest cases, showing you the diff before it writes.
- can Atlas investigate several questions about a codebase at once
- Yes. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so multiple questions about a Scala repo can be investigated concurrently while your main session stays focused.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated 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.
Atlas for Scala in 2026
Atlas is a terminal-native AI coding agent for Scala in 2026. Run it in a project with a build.sbt, let it read your traits and implicits, and approve every diff.
Locate where a behavior is implemented in Scala with Atlas (2026)
Find the Scala file and symbol behind a behavior in 2026 with Atlas: codebase_search for meaning, grep through ripgrep for exact text, and the lsp tool for symbols.
Run the Test Suite and Triage the Failures in Scala with Atlas (2026)
Atlas runs ScalaTest via sbt test with a generous timeout, retains the full log when output truncates at 2000 lines, and turns red output into a todowrite list.
Diagnose a hanging or long-running command in Scala with Atlas (2026)
Is your sbt build slow or blocked on stdin? Atlas races every command against a timeout and tells you which. A 2026 guide for Scala teams using sbt and scalafmt.
Plan a Multi-File Change Before Editing in Scala With Atlas (2026)
How to plan a multi-file Scala change before editing with Atlas in 2026: the plan agent denies edit for every path except .atlas/plans/*.md until you approve.
Automate GitHub issue and pull request triage in Scala with Atlas in 2026
Automate GitHub issue and pull request triage for Scala projects in 2026 using Atlas. Learn how Scala developers can integrate Atlas with sbt and scalafmt for safe, AI-driven workflow automation.
Debug a Single Failing Test in Scala with Atlas (2026)
How Atlas debugs one failing Scala test in 2026: run it isolated with sbt, walk the call path with the lsp tool, and fix the code, not the assertion.