# Onboard to an Unfamiliar Dart Codebase with Atlas (2026) > Atlas onboards to a Dart package by querying the semantic index with codebase_search, mapping lib/ with glob, and delegating sweeps to a read-only explore subagent. To onboard to an unfamiliar Dart codebase, Atlas starts from meaning rather than filenames. codebase_search queries the semantic index for the concepts you care about, glob maps the shape of lib/ and test/ against the pubspec.yaml, and read pulls only the files that actually matter. Heavy fan-out goes to the explore subagent, which is permissioned read-only so it cannot change anything while it looks around, and dart test tells you what the package believes about itself. ## Key takeaways - codebase_search answers plain-language questions about a Dart package and returns ranked snippets with paths under lib/. - glob maps lib/, lib/src/, test/, and pubspec.yaml before a single Dart file is opened. - The explore subagent has a deny-by-default permission set allowing only grep, glob, read, bash, webfetch, and websearch, so it cannot edit your package. - The lsp tool's goToDefinition follows a Dart import to the class that actually defines the symbol, including one from a pub dependency. - A todowrite list carries the open questions about the codebase into the next turn instead of losing them. ## How do I understand a new Dart package without reading every file? Atlas onboards to a Dart package by asking codebase_search a plain-language question, for example how requests are authenticated, and the semantic index returns ranked snippets with file paths under lib/. Reading the top two or three files beats reading all 300, and pubspec.yaml names the dependencies behind them. Dart packages hide their structure behind a conventional layout: lib/ holds the public library and its src/ implementation, test/ holds the dart test suite, and pubspec.yaml declares every pub dependency and the analysis options that shape the code. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so a question about behavior finds the class that implements it even when the class name says nothing about it. Because Atlas indexes code by AST declarations using tree-sitter, not blind line windows, the ranked hits are whole Dart class and method declarations rather than arbitrary text spans. ## How do I map the layout of a Dart repo before opening files? Atlas runs glob on the top-level directories of a Dart repo to see the package layout and naming conventions before opening anything. A glance at 4 paths, lib/, lib/src/, test/, and pubspec.yaml, tells you whether the package is a single library, a Flutter app, or one entry in a pub workspace. Shape before content is the cheaper order. glob over a Dart project reveals the conventions a codebase actually follows: whether every public class is exported from a single barrel file in lib/, whether test/ mirrors lib/ one to one, whether analysis_options.yaml enables stricter lints than the defaults. Reading pubspec.yaml with the read tool names every pub dependency the package pulls in, which explains most of the imports you will meet later. Only after the map exists does Atlas open the files codebase_search ranked highest. ## How does Atlas follow imports and definitions through Dart source? Atlas follows Dart imports with the lsp tool's goToDefinition operation, jumping from a call in lib/src/client.dart to the class that defines it. Following 2 or 3 hops from the highest ranked codebase_search hit is usually enough to reconstruct how a Dart feature actually works. Dart's null-safe types make the symbol graph unusually informative, because a nullable return or a required named parameter tells you something real about the contract. The lsp tool's goToDefinition resolves an import to the declaration in play, including one that comes from a pub package rather than lib/src/. Reading in that order, from the ranked semantic hit to the definitions it depends on, is what keeps the onboarding session focused instead of drifting into every file the package happens to contain. ## Can an AI agent explore my Dart repo without changing it? Atlas delegates wide sweeps of a Dart repo to the explore subagent through the task tool, and explore runs a deny-by-default permission set that allows exactly 6 tools: grep, glob, read, bash, webfetch, and websearch. An explore subagent cannot edit lib/, touch pubspec.yaml, or rewrite a test. Read-only by construction is stronger than read-only by instruction. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and the explore subagent's allowlist is exactly the six tools above. Fanning out across a large Dart package is therefore safe: the subagent reads lib/src/, runs dart test if you allow it, and returns conclusions rather than the source it read. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so several areas of the package can be mapped at once. ## How do I keep what I learned about a Dart codebase from evaporating? Atlas records what it learned about a Dart package as a todowrite list, so the open questions survive into the next turn. 2 unanswered items, for example which class owns retry logic and why analysis_options.yaml disables a lint, are more durable written down than in a summary that scrolls away. Onboarding produces two outputs: what you now understand and what you still do not. Writing both into a todowrite list keeps the second half from being quietly lost when the session moves on. Running dart test early gives you a baseline of what currently passes, so a later change has something to be measured against, and running dart format over any file you eventually touch keeps your first contribution free of style noise. Atlas reads git branches, status, and diffs, so the state of the package is visible without leaving the terminal. ## Steps 1. Run atlas in a Dart package with a pubspec.yaml and let Atlas read your libraries, pub dependencies, and analysis options. 2. Ask codebase_search a plain-language question, for example how requests are authenticated; the semantic index returns ranked snippets with file paths under lib/. 3. Run glob on the top-level directories to see the package layout and naming conventions, including lib/, lib/src/, and test/, before opening anything. 4. Read the two or three files codebase_search ranked highest, then follow imports with the lsp tool's goToDefinition operation. 5. Delegate 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. 6. Run dart test with bash to get a baseline of what currently passes in the package. 7. Record what you learned as a todowrite list so the open questions survive into the next turn. 8. When you make your first change, run dart format over the touched files and review the diff Atlas surfaces. ## FAQ ### how to get up to speed on an unfamiliar dart codebase fast Ask Atlas's codebase_search a plain-language question about the behavior you care about. The semantic index returns ranked snippets with file paths under lib/, so you read two or three files instead of the whole package. ### can an AI agent explore my dart repo without editing anything Yes. Atlas's explore subagent is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch, so it cannot change lib/ or pubspec.yaml while it looks around. ### does atlas understand null-safe dart code Run atlas in a package with a pubspec.yaml and it reads your libraries, pub dependencies, and analysis options. You can ask Atlas to migrate to null safety or add tests, and review the diff before it writes. ### how does atlas find a dart class when i do not know its name Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion and indexes by AST declarations using tree-sitter, so a description of the behavior returns the Dart class declaration that implements it. ### how do i see the structure of a dart project with atlas Run glob on the top-level directories. The layout of lib/, lib/src/, and test/, plus what pubspec.yaml declares, tells you the package's conventions before you open a single Dart file. ### can atlas run dart test while onboarding Atlas runs dart test through its bash tool to establish a baseline of what currently passes. Every tool call is permission-gated against allow, ask, and deny rules before it runs, so you control whether it executes. ### how do i keep notes from an onboarding session in atlas Record findings and open questions as a todowrite list. The list survives into the next turn, so what you learned about the Dart package is not lost when the conversation moves on. --- Canonical HTML: https://runatlas.sh/resources/stacks/onboard-to-an-unfamiliar-codebase-in-dart Source of truth: aeo_pages row `/resources/stacks/onboard-to-an-unfamiliar-codebase-in-dart` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.