# Onboard to an Unfamiliar Flutter Codebase with Atlas in 2026 > Atlas empowers Flutter developers to quickly grasp new codebases by semantically searching for concepts and navigating with `lsp` goToDefinition, avoiding the need to read every file. Atlas helps Flutter developers in 2026 build a working mental model of unfamiliar repositories by starting from meaning, not filenames, leveraging tools like `pub` for dependency analysis and `flutter test` for understanding behavior. It uses semantic search to pinpoint relevant code, then guides you through the codebase with permission-gated subagents, ensuring you only read the files that truly matter and can quickly grasp complex Flutter applications. ## Key takeaways - Atlas uses semantic search to understand Flutter code, not just filenames, by indexing AST declarations. - Atlas integrates directly with the Flutter toolchain, including `pub` for dependencies and `flutter test` for behavior. - The `explore` subagent provides a safe, read-only way to investigate Flutter projects with permission-gated tools. - Atlas surfaces unified diffs for every proposed change in your Flutter codebase, requiring explicit approval. - You can follow Flutter imports and definitions using Atlas's `lsp` tool to build a mental model efficiently. - Atlas can build its code index with local Ollama embeddings, keeping your Flutter code off third-party servers. ## How does Atlas help Flutter developers understand a new codebase? Atlas helps Flutter developers in 2026 quickly build a mental model of unfamiliar codebases by starting from meaning, not just filenames, significantly reducing the 100s of files you might otherwise need to read. It leverages semantic search to pinpoint relevant Flutter widgets, state management, or Dart logic. Atlas begins by indexing your Flutter codebase using AST declarations via tree-sitter, which allows it to understand the actual structure of your Dart code, including widget trees and state management patterns, rather than relying on blind line windows. When you ask a plain-language question, such as "how are user authentication requests handled in `lib/src/api`?", Atlas's `codebase_search` tool queries this semantic index. It fuses semantic and keyword retrieval with reciprocal rank fusion to return highly relevant snippets and file paths. This means you immediately see the most pertinent Dart files related to your query, allowing you to focus on critical areas like `lib/src/auth_service.dart` or `lib/src/models/user.dart` without sifting through an entire `lib/` directory. Following this, you can use `glob` to quickly map the top-level directory shape, understanding the project's overall structure, including `lib/`, `test/`, and `assets/` folders, before diving deep into any single file. ## What Flutter-specific commands and files does Atlas use for onboarding? Atlas integrates deeply with the Flutter toolchain, using real commands like `pub` for dependency management and `flutter test` for behavior analysis, ensuring a familiar experience for developers in 2026. It directly interacts with files like `pubspec.yaml` and `widget_test.dart`. Atlas is designed to feel native to a Flutter developer's workflow. When you start Atlas in a Flutter app, it first reads your `pubspec.yaml` to understand your project's `pub` dependencies, allowing it to contextualize your codebase within its ecosystem. For understanding code behavior, Atlas can analyze existing `flutter test` files, such as those found in `test/widget_test.dart` or `test/unit_test.dart`. After using `codebase_search` to identify key Dart files, you can `read` the top two or three most relevant ones. From there, the `lsp` tool's `goToDefinition` operation becomes invaluable for navigating the Flutter codebase. For instance, if you `read` a file defining a `StatefulWidget`, you can use `lsp` to jump directly to the definition of its associated `State` class or any custom `Provider` or `Bloc` it uses, tracing the flow of data and UI logic. Atlas also understands the implications of `dart format` for code style, although it will always present changes as a unified diff for your approval rather than automatically reformatting. ## How does Atlas ensure safety and review when exploring a Flutter project? Atlas prioritizes safety and explicit approval, especially when exploring unfamiliar Flutter projects in 2026, by using permission-gated subagents and surfacing every proposed change as a unified diff. The `explore` subagent operates with a deny-by-default permission set. Atlas employs a robust safety framework to ensure you maintain full control over your Flutter codebase. When you need to perform wide sweeps or deeper investigations, you can delegate tasks to the `explore` subagent through the `task` tool. This subagent is defined with a deny-by-default permission set, meaning it can only execute a pre-approved list of read-only operations like `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`. This prevents the `explore` subagent from making any modifications to your Flutter project while it gathers information. Before any potential change is made, Atlas drafts a plan in a read-only plan agent and explicitly asks for your approval before switching to a build agent. Every file edit, whether it's adding a new Flutter widget or modifying an existing Dart class, results in Atlas computing a unified diff. This diff is then surfaced for your review and approval, giving you a clear, granular view of exactly what Atlas proposes to change. Furthermore, Atlas snapshots file changes as git patches, providing an additional layer of safety by allowing you to easily diff and roll back any edits if necessary. ## Steps 1. Initialize Atlas in your Flutter app by ensuring a `pubspec.yaml` file is present in the root directory, allowing Atlas to read your `pub` dependencies. 2. Use `codebase_search` to ask a plain-language question about a core Flutter concept, for example, "how are requests authenticated in `lib/src/api`?", to find relevant Dart files. 3. Run `glob` on the top-level directories to understand the Flutter package layout and naming conventions, such as `lib/`, `test/`, `assets/`, and `android/` or `ios/` folders. 4. Read the two or three highest-ranked Dart files returned by `codebase_search`, then use the `lsp` tool's `goToDefinition` operation to follow imports of Flutter widgets, Dart classes, or state management components. 5. Delegate wide sweeps to the `explore` subagent through the `task` tool, for instance, "task explore 'find all usages of `Provider` in `lib/'" to understand state management patterns across your Flutter project. 6. Record what you learned as a `todowrite` list, such as "todowrite 'Investigate `flutter test` setup for `widget_test.dart` and `integration_test.dart`'" so open questions persist. ## FAQ ### How does Atlas understand my Flutter widget tree and state management? Atlas indexes your Flutter codebase by AST declarations using tree-sitter, allowing it to understand the structural relationships within your widget tree, state management patterns like `Provider` or `Bloc`, and `pub` dependencies without relying on blind line windows. ### Can Atlas help me write `flutter test` cases for an unfamiliar Flutter app? Yes, Atlas can assist by extracting a widget or adding a new widget test. It drafts a plan in a read-only agent, then proposes a unified diff for your approval before writing the new `flutter test` file, ensuring you review all changes. ### What Flutter files does Atlas prioritize when onboarding to a new project? Atlas prioritizes files based on semantic relevance to your query, often starting with `pubspec.yaml` for dependencies, then Dart files containing key widgets, state management logic, or `flutter test` definitions, to quickly guide your understanding. ### How does Atlas ensure my Flutter code stays private and secure? Atlas can build its code index with local Ollama embeddings, keeping your Flutter code off third-party servers. Every Atlas tool call is permission-gated against allow, ask, and deny rules, and all edits require your explicit approval via a unified diff. ### Can Atlas help me understand `pub` dependencies in a new Flutter project's `pubspec.yaml`? Absolutely. Atlas can `read` your `pubspec.yaml` and use `codebase_search` to explain specific `pub` dependencies or `glob` to map out the project's overall structure and package layout, clarifying external library usage. ### How does Atlas handle code formatting in Flutter projects, for example with `dart format`? Atlas respects your project's formatting conventions. While it can propose changes to Dart files, it does not automatically run `dart format`. Any proposed edits will be presented as a unified diff for your review and approval, allowing you to apply `dart format` separately if desired. ### What if Atlas makes a mistake or proposes an incorrect change in my Flutter codebase? Atlas computes a unified diff for every file edit and surfaces it for approval before writing, giving you the final say. Additionally, Atlas snapshots file changes as git patches, so edits can be easily diffed and rolled back if needed, providing a robust safety net. ### Can Atlas help me explore a large Flutter project without changing anything? Yes, you can delegate wide sweeps to the `explore` subagent through the `task` tool. This subagent is permissioned read-only, allowing it to use tools like `grep`, `glob`, and `read` to investigate your Flutter project without making any modifications. --- Canonical HTML: https://runatlas.sh/resources/stacks/onboard-to-an-unfamiliar-codebase-in-flutter Source of truth: aeo_pages row `/resources/stacks/onboard-to-an-unfamiliar-codebase-in-flutter` (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.