How does Atlas understand my dbt project's data lineage?

Atlas reads your model DAG through `ref()` and `source()` calls, along with your `schema.yml` tests and each model's materialization configuration. It uses AST declarations to build a comprehensive, semantic understanding of your dbt project's data lineage.

Can Atlas help me find all `incremental` models in a large dbt project?

Yes, you can use the `task` tool to delegate a `grep` operation to the read-only `explore` subagent. This allows you to efficiently search for `materialized: incremental` within your `models/` directory, quickly identifying all incremental models.

How does Atlas ensure I don't accidentally change production dbt code?

Atlas operates with permission-gated tool calls (allow, ask, deny) and drafts plans in a read-only agent. Any `dbt build` command, for instance, will prompt for approval and never target production without explicit, permissioned consent, ensuring safety.

What dbt-specific tools does Atlas integrate with for development?

Atlas directly integrates with your dbt toolchain, allowing you to run `dbt test` for validation, manage dependencies with `dbt deps (packages.yml)`, and format your SQL files using `sqlfmt` directly through the agent, streamlining your workflow.

How does Atlas help me follow `ref()` calls in an unfamiliar dbt codebase?

After `codebase_search` identifies relevant files, you can use the `lsp` tool's `goToDefinition` operation. This allows you to navigate directly to the definition of models referenced by `ref()` calls, efficiently mapping the data flow and dependencies within your dbt project.

Can Atlas help me document what I learn about a dbt project's logic?

Absolutely. The `todowrite` tool allows you to record your findings, open questions, and insights about the dbt project's logic and structure. This ensures your evolving mental model persists across sessions, aiding in comprehensive onboarding.

Does Atlas support dbt package management with `packages.yml`?

Yes, Atlas recognizes your `packages.yml` file and can execute `dbt deps` to manage your dbt package dependencies. This integrates direct with your existing dbt workflow, ensuring all required packages are installed for your project.

Onboard to an Unfamiliar dbt Codebase with Atlas in 2026

Atlas empowers dbt developers in 2026 to build a working mental model of unfamiliar repositories without reading every file, by leveraging semantic search, AST indexing, and direct interaction with `dbt_project.yml`, `ref()` calls, and `schema.yml` tests. It integrates direct with your dbt toolchain, including `dbt test`, `dbt deps (packages.yml)`, and `sqlfmt`, to provide a comprehensive understanding of data transformations and dependencies.

How Atlas builds a mental model of dbt projects without reading every file

Atlas in 2026 helps dbt developers build a mental model of unfamiliar projects by starting from meaning, not filenames. It uses hybrid semantic and keyword retrieval, indexing code by AST declarations, not blind line windows, to quickly identify relevant `ref()` calls and `schema.yml` tests, often reducing initial exploration time by 50% or more.

To build a working mental model of an unfamiliar dbt repository, Atlas begins by indexing your codebase using AST declarations, which allows it to understand the structure and relationships within your dbt project, rather than just scanning lines of text. When you ask `codebase_search` a plain-language question, such as "how is customer order data joined and transformed?", Atlas queries its semantic index. This process returns ranked snippets with file paths from your `models/` directory and `schema.yml` files, highlighting the most relevant `ref()` and `source()` calls. This intelligent retrieval means you don't need to manually open every file in `models/` or parse complex `dbt_project.yml` configurations to grasp the core logic. Atlas focuses on the actual data transformations and dependencies, providing a targeted entry point into the codebase's meaning.

Exploring dbt project structure and dependencies with Atlas

Understanding a dbt project's layout is crucial, and Atlas facilitates this by allowing you to `glob` top-level directories to see the package structure and naming conventions. This provides a high-level overview in just 1-2 commands, before diving into specific `models/` files, giving you a foundational understanding of the repository's organization.

Once you have an initial understanding from `codebase_search`, Atlas helps you map the dbt project's physical structure. Running `glob` on the top-level directories reveals the overall package layout and naming conventions, which are often critical for understanding a dbt repository's domain separation. After identifying key files, you can `read` the two or three `models/` files that `codebase_search` ranked highest. From there, the `lsp` tool's `goToDefinition` operation becomes invaluable for dbt developers. It allows you to follow `ref()` and `source()` calls directly to their definitions, effectively traversing the dbt model DAG without manually searching for files. This capability is essential for understanding data lineage and dependencies, which are at the heart of any dbt project.

Delegating wide sweeps and ensuring safety in dbt codebases

For broader investigations across a dbt repository, Atlas delegates heavy fan-out to the `explore` subagent, which operates with a deny-by-default permission set. This ensures that while it can `grep` for specific `materialization` strategies or `read` many `schema.yml` files, it cannot modify anything, providing a safe environment for exploration in 2026, even across hundreds of files.

When you need to perform wide sweeps across a dbt codebase, such as identifying all `incremental` models or finding every instance of a specific `schema.yml` test, Atlas's `task` tool can delegate this work to the `explore` subagent. This subagent is explicitly defined with a deny-by-default permission set, allowing only read-only operations like `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`. This strict permissioning means you can safely explore an unfamiliar dbt project without any risk of accidental modifications. For example, you can ask the `explore` subagent to `grep` for `materialized: incremental` across all `models/` files to quickly understand the project's performance optimization strategies. As you gather insights, the `todowrite` tool allows you to record what you learned, capturing open questions about dbt logic or potential areas for refactoring, ensuring your mental model evolves and persists.

Reviewing and approving dbt changes with Atlas's safety features

Atlas ensures every proposed change to your dbt project, from adding `not_null` tests to converting a table model to `incremental`, is thoroughly reviewed. It computes a unified diff for every file edit and surfaces it for approval, preventing unintended modifications to your `models/` or `schema.yml` files in 2026, offering 100% transparency.

Atlas prioritizes safety and transparency throughout your dbt development workflow. Before any changes are applied, Atlas drafts a plan in a read-only plan agent, allowing you to understand its intentions without risk. When it switches to a build agent to propose actual modifications, every tool call is permission-gated against allow, ask, and deny rules. This means that operations like running `dbt build` against your dev target, adding `not_null` and `unique` tests to new columns in `schema.yml`, or formatting SQL with `sqlfmt` will always prompt for your approval. Atlas computes a unified diff for every file edit, surfacing it for your review before writing, ensuring you have complete control over changes to your `dbt_project.yml`, `models/`, or `schema.yml` files. Furthermore, Atlas snapshots file changes as git patches, so edits can be easily diffed and rolled back, providing robust version control and peace of mind.

Step by step

01Run `atlas` in your dbt project directory, ensuring `dbt_project.yml` and a `models/` directory are present.
02Ask `codebase_search` a plain-language question about data flow, such as "how is customer order data transformed using `ref()` calls?" to get ranked snippets.
03Run `glob` on top-level directories to understand the dbt package layout and naming conventions before opening any files.
04Use `read` on the two or three `models/` files `codebase_search` ranked highest, then follow `ref()` and `source()` calls with `lsp`'s `goToDefinition`.
05Delegate a wide sweep to the `explore` subagent via `task` to `grep` for all `materialized: incremental` models or specific `schema.yml` tests.
06Record your findings and any open questions about dbt logic using `todowrite` to persist your mental model across sessions.
07Review Atlas's proposed changes, such as adding `not_null` tests or applying `sqlfmt`, via the unified diff before approving any file writes.

Frequently asked questions

How does Atlas understand my dbt project's data lineage?: Atlas reads your model DAG through `ref()` and `source()` calls, along with your `schema.yml` tests and each model's materialization configuration. It uses AST declarations to build a comprehensive, semantic understanding of your dbt project's data lineage.
Can Atlas help me find all `incremental` models in a large dbt project?: Yes, you can use the `task` tool to delegate a `grep` operation to the read-only `explore` subagent. This allows you to efficiently search for `materialized: incremental` within your `models/` directory, quickly identifying all incremental models.
How does Atlas ensure I don't accidentally change production dbt code?: Atlas operates with permission-gated tool calls (allow, ask, deny) and drafts plans in a read-only agent. Any `dbt build` command, for instance, will prompt for approval and never target production without explicit, permissioned consent, ensuring safety.
What dbt-specific tools does Atlas integrate with for development?: Atlas directly integrates with your dbt toolchain, allowing you to run `dbt test` for validation, manage dependencies with `dbt deps (packages.yml)`, and format your SQL files using `sqlfmt` directly through the agent, streamlining your workflow.
How does Atlas help me follow `ref()` calls in an unfamiliar dbt codebase?: After `codebase_search` identifies relevant files, you can use the `lsp` tool's `goToDefinition` operation. This allows you to navigate directly to the definition of models referenced by `ref()` calls, efficiently mapping the data flow and dependencies within your dbt project.
Can Atlas help me document what I learn about a dbt project's logic?: Absolutely. The `todowrite` tool allows you to record your findings, open questions, and insights about the dbt project's logic and structure. This ensures your evolving mental model persists across sessions, aiding in comprehensive onboarding.
Does Atlas support dbt package management with `packages.yml`?: Yes, Atlas recognizes your `packages.yml` file and can execute `dbt deps` to manage your dbt package dependencies. This integrates direct with your existing dbt workflow, ensuring all required packages are installed for your project.

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.

Atlas for dbt: Terminal-Native AI Coding in 2026

Atlas is a terminal-native AI coding agent for dbt. Read the ref() DAG, convert a table model to incremental, run dbt build against dev, and add tests in 2026.

Trace a runtime bug from a stack trace in dbt with Atlas in 2026

Pinpoint and fix dbt runtime bugs from production stack traces using Atlas, the terminal-native AI coding agent. Leverage `dbt test`, `sqlfmt`, and `dbt deps` for rapid resolution.

Automate GitHub Issue and Pull Request Triage in dbt with Atlas in 2026

Streamline dbt project maintenance in 2026. Atlas automates GitHub issue and pull request triage, integrating with `dbt test`, `sqlfmt`, and `dbt deps (packages.yml)` for safe, trusted, and efficient dbt development

Document a dbt Module with a README in 2026 using Atlas

Atlas helps dbt developers in 2026 generate accurate READMEs for modules by reading live code, ensuring documentation reflects current behavior. It leverages dbt's own toolchain, including dbt test for verification and

Debug a single failing test in dbt with Atlas in 2026

Pinpoint and fix failing dbt tests efficiently with Atlas in 2026. Leverage Atlas's AI to run `dbt test` in isolation, trace `ref()` calls, and apply precise code fixes.

Locate where a behavior is implemented in dbt with Atlas in 2026

Discover how Atlas helps dbt developers in 2026 pinpoint exact file and symbol locations for specific behaviors, leveraging semantic search, grep, and LSP tools across your dbt project.

Diagnose a Hanging or Long-Running dbt Command with Atlas in 2026

Diagnose hanging dbt commands in 2026 with Atlas. Quickly determine if your `dbt build` or `dbt test` is genuinely slow or silently blocked on input, and get it unstuck.

Browse this resource hub