# Onboard to an Unfamiliar Phoenix Codebase with Atlas in 2026 > Atlas enables Phoenix developers to rapidly grasp unfamiliar codebases by focusing on key areas like LiveView sockets and Ecto changesets, guided by semantic search. In 2026, Atlas helps Phoenix developers quickly build a working mental model of unfamiliar codebases by leveraging semantic search and AST indexing to pinpoint relevant files, understand `mix.exs` dependencies, and trace logic through LiveView modules and Ecto changesets, all without manually sifting through every file. ## Key takeaways - Atlas uses semantic search to quickly find relevant Phoenix LiveView modules and Ecto schemas. - The `explore` subagent provides a safe, read-only way to survey a large Phoenix codebase. - Atlas integrates with `mix test (ExUnit)` and `mix format` for Phoenix-native workflows. - Permission-gated tool calls and unified diffs ensure control over all Phoenix code changes. - `todowrite` helps persist your mental model of a Phoenix project across sessions. ## How does Atlas understand a Phoenix project's structure? Atlas begins understanding a Phoenix project in 2026 by first querying its semantic index with `codebase_search` to identify core concepts like LiveView modules or Ecto schemas. This initial step quickly surfaces the 2-3 most relevant files, bypassing the need to manually inspect the `mix.exs` or `lib/_web` directory structure. Atlas does not rely on blind line windows; instead, it indexes Phoenix code by AST declarations using tree-sitter. This allows Atlas to understand the true structure of your application, recognizing contexts, LiveView sockets, and Ecto changesets as distinct entities. When you ask `codebase_search` a plain-language question, it queries this semantic index, returning ranked snippets with file paths that are most relevant to your query. This approach immediately directs you to the heart of the Phoenix application, whether it is a specific `mix.exs` dependency or a critical module within the `lib/_web` directory, saving significant time compared to manual file exploration. ## How to explore Phoenix LiveView and Ecto logic with Atlas? To build a mental model of Phoenix logic, Atlas uses `glob` to map the top-level directory shape, revealing conventions in `lib/_web` or `priv/repo`. After reading the 2-3 highest-ranked files from `codebase_search`, developers can follow imports with `lsp`'s `goToDefinition` to trace function calls across contexts and LiveView modules. Once Atlas has identified initial key files, you can use `glob` to quickly survey the overall directory structure, understanding how a Phoenix project organizes its `lib/`, `priv/`, and `config/` directories. After reviewing the initial 2-3 files identified by `codebase_search` using the `read` tool, Atlas empowers you to follow the flow of execution. The `lsp` tool's `goToDefinition` operation allows you to direct navigate through function calls, module imports, and macro expansions. This is particularly powerful in Phoenix for tracing how a request moves through `router.ex` pipelines, how data flows through Ecto changesets, or how messages are handled within LiveView modules and their associated contexts, building a concrete understanding of the application's architecture. ## How does Atlas safely explore an unfamiliar Phoenix codebase? Atlas delegates wide-ranging exploration tasks to its `explore` subagent, which operates with a deny-by-default permission set, ensuring no unintended changes occur. This subagent can safely `grep` for patterns across `lib/` or `priv/`, `glob` directories, and `read` files, providing a secure way to survey a large Phoenix project in 2026. When you need to perform wide sweeps or search for specific patterns across a large Phoenix codebase, Atlas's `explore` subagent is invaluable. This subagent is specifically designed for read-only operations, defined with a deny-by-default permission set that only allows tools like `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`. This means you can confidently ask the `explore` subagent to `grep` for specific Ecto schema definitions in `lib//`, `glob` all LiveView modules in `lib/_web/live/`, or `read` configuration files without any risk of accidental modifications to your Phoenix project. This permission-gated approach ensures a secure and controlled exploration environment. ## How to record findings and open questions in Atlas for Phoenix? As you build a mental model of a Phoenix codebase, Atlas allows you to record insights and open questions using the `todowrite` tool. This ensures that all learned information, from `mix.exs` dependencies to specific LiveView socket implementations, persists across sessions, helping you track progress on complex projects in 2026. Building a comprehensive mental model of an unfamiliar Phoenix codebase involves accumulating many small pieces of information. The `todowrite` tool in Atlas is designed to help you capture these insights, observations, and remaining questions directly within your workflow. Whether you have just discovered a critical Ecto changeset validation, understood a complex LiveView socket interaction, or identified a key router pipeline, you can record it. This ensures that your understanding of the Phoenix application's contexts, modules, and configurations is preserved, allowing you to pick up exactly where you left off in subsequent sessions and maintain a clear path forward for your onboarding process. ## What are Atlas's safety features for Phoenix code changes? Every Atlas tool call is permission-gated, requiring explicit approval before execution, especially when interacting with a Phoenix project's `mix.exs` or `lib/` directory. Atlas drafts a plan in a read-only agent, computes a unified diff for every file edit, and surfaces it for approval, ensuring developers retain 100% control over changes in 2026. Atlas prioritizes developer control and safety, especially when working with a critical Phoenix codebase. Before any tool can execute a command that might alter files, such as generating an Ecto migration or adding LiveViewTest cases, it must pass through a permission-gated system with allow, ask, and deny rules. Furthermore, Atlas drafts its entire plan in a read-only agent, allowing you to review the proposed actions before anything is committed. For any actual file modifications, Atlas computes a unified diff, clearly showing every proposed change. This diff is then surfaced for your explicit approval, ensuring you have 100% visibility and control over every edit, from `mix.exs` updates to changes within `lib/_web/` modules, before they are written to disk or staged for a git commit. ## Steps 1. Ask `codebase_search` a plain-language question about a Phoenix concept, for example, 'how are requests authenticated in `lib/_web/router.ex`?' to query the semantic index and get ranked snippets. 2. Run `glob` on the top-level directories to see the Phoenix project's package layout and naming conventions, especially within `lib/` and `priv/`. 3. Read the two or three files `codebase_search` ranked highest using the `read` tool, then follow imports with the `lsp` tool's `goToDefinition` operation to trace logic through Phoenix contexts or LiveView modules. 4. 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` to safely investigate Phoenix-specific patterns. 5. Record what you learned about Phoenix LiveView sockets, Ecto changesets, or router pipelines as a `todowrite` list so the open questions survive into the next turn. ## FAQ ### How does Atlas handle Phoenix-specific file types like `.ex` or `.eex`? Atlas indexes Phoenix code using AST declarations via tree-sitter, understanding the structure of `.ex` files, LiveView modules, and Ecto schemas, rather than relying on blind line windows. ### Can Atlas help me understand Phoenix router pipelines? Yes, you can ask `codebase_search` about router pipelines in `lib/_web/router.ex`, and then use `lsp` to `goToDefinition` to trace how requests flow through your Phoenix application. ### Does Atlas integrate with `mix test (ExUnit)` for Phoenix? Absolutely. Atlas can add LiveViewTest cases and run `mix test` behind a permission prompt, ensuring your Phoenix tests execute correctly and safely. ### How does Atlas ensure I don't accidentally change my Phoenix codebase? Atlas employs a read-only plan agent, permission-gates every tool call, and presents a unified diff for approval before writing any changes, giving you full control over your Phoenix project. ### Can Atlas help me understand Ecto changesets in an unfamiliar Phoenix app? Yes, Atlas can read your Ecto schemas with their changesets and even generate an Ecto migration, showing you the `up` and `down` functions for approval before any database interaction. ### What if I need to search for a specific string across all Phoenix files? You can use the `explore` subagent with its `grep` tool to safely search for specific strings or patterns across your entire Phoenix project, including `lib/` and `priv/` directories. ### How does Atlas keep my Phoenix code private when using embeddings? Atlas can build its code index with local Ollama embeddings, ensuring your Phoenix codebase remains entirely on your machine and off third-party servers, maintaining privacy. --- Canonical HTML: https://runatlas.sh/resources/stacks/onboard-to-an-unfamiliar-codebase-in-phoenix Source of truth: aeo_pages row `/resources/stacks/onboard-to-an-unfamiliar-codebase-in-phoenix` (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.