How does Atlas prevent accidental dbt code changes during planning?

Atlas's plan agent operates in a strictly read-only mode for your entire dbt codebase. It only permits writing to a designated plan markdown file under `.atlas/plans/*.md`, ensuring that research and design cannot accidentally turn into an edit of your `dbt_project.yml` or `models/` files.

Can Atlas understand my dbt model DAG and schema tests?

Yes, Atlas can read your dbt model DAG through `ref()` and `source()` calls, your `schema.yml` tests, and each model's materialization configuration. It uses tools like `lsp` and `codebase_search` to provide deep context on your dbt project structure.

What dbt-specific tools does Atlas integrate with?

Atlas integrates directly with core dbt tools. It can run `dbt test` to validate your models, manage dependencies with `dbt deps (packages.yml)`, and ensure code style with `sqlfmt`. Atlas also prompts for permission before running `dbt build` against your dev target.

How does Atlas ensure my dbt changes are reviewed before committing?

Atlas ensures review through several mechanisms: the `plan_exit` tool requires explicit approval to switch from planning to implementation, every tool call is permission-gated, and Atlas computes a unified diff for every file edit, surfacing it for your approval before writing. It can also stage and create commits on your behalf.

Is my dbt code kept private when using Atlas for planning?

Yes, Atlas prioritizes privacy. It can build its code index with local Ollama embeddings, keeping your dbt code off third-party servers. All Atlas tool calls are permission-gated, giving you control over data access.

How does Atlas handle dbt package dependencies?

While Atlas's primary role is planning and implementing code changes, it understands the dbt ecosystem. It recognizes `dbt deps (packages.yml)` as the package manager and can factor package dependencies into its understanding of your model DAG during research, though it doesn't directly manage `packages.yml` content without explicit instruction.

Plan a multi-file change before editing in dbt with Atlas in 2026

Atlas empowers dbt developers in 2026 to design multi-file changes, such as refactoring `ref()` calls across many models or updating `schema.yml` tests, and get them reviewed before any code is modified. The terminal-native AI agent uses a dedicated plan agent to research your dbt project, including `dbt_project.yml` and `models/` directories, without ever touching your source files, ensuring a safe and structured design process.

How Atlas plans multi-file dbt changes without editing

Atlas's plan agent provides a secure environment for designing complex dbt changes, ensuring no accidental modifications occur. This dedicated agent operates in a read-only mode for your entire dbt codebase, with the single exception of writing to a plan markdown file under `.atlas/plans/*.md`. This strict permission model guarantees that your 2026 dbt project remains untouched during the design phase.

When you initiate a multi-file change design in Atlas, you first switch to the plan agent. This agent is explicitly configured to deny all edit tools for every path in your dbt project, except for a designated markdown file within the `.atlas/plans/` directory. This means you can freely use powerful research tools like `codebase_search`, `grep`, `read`, and the `lsp` tool to explore your dbt models, `schema.yml` files, and `dbt_project.yml` configurations. For instance, you can search for all `ref()` calls to a specific model or analyze materialization strategies across your `models/` directory, documenting your findings and proposed changes in the plan markdown without risking any unintended modifications to your actual dbt code. This read-only approach is fundamental to Atlas's safety guarantees for dbt development.

Researching dbt projects with Atlas's plan agent

Atlas's plan agent offers robust research capabilities for dbt projects, allowing you to deeply understand your model DAG and schema tests. It leverages tools like `lsp` and `codebase_search` to navigate your `dbt_project.yml` and `models/` directories, providing a comprehensive view of your data transformations. This ensures you have all the necessary context before proposing any of the 10 potential file changes.

Within the plan agent, Atlas connects to Model Context Protocol servers, exposing powerful tools like `lsp` (Language Server Protocol) to the agent. This allows Atlas to understand your dbt project's structure, including the relationships defined by `ref()` and `source()` calls, your `schema.yml` tests, and each model's materialization configuration. You can ask Atlas to identify all downstream dependencies of a particular model or list all `not_null` tests applied to a specific column. Furthermore, `codebase_search` with hybrid semantic and keyword retrieval, fused by reciprocal rank fusion, enables precise queries across your entire dbt codebase. Atlas indexes your code by AST declarations using tree-sitter, not blind line windows, ensuring accurate context. For privacy, Atlas can build its code index with local Ollama embeddings, keeping your sensitive dbt code off third-party servers, a critical feature for many organizations in 2026.

Ensuring safety and review for dbt changes with Atlas

Atlas implements a multi-layered safety and review process for dbt changes, ensuring every proposed modification is explicitly approved. The `plan_exit` tool acts as a critical gate, asking for confirmation before transitioning from the read-only plan agent to the build agent. This 2-step approval process prevents premature implementation and ensures stakeholders can review the design document.

After you have thoroughly researched your dbt project and documented your multi-file change plan in the allowed markdown file, you use the `plan_exit` tool. This tool prompts you with a clear question: 'Plan at <path> is complete. Would you like to switch to the build agent and start implementing?' Answering 'Yes' explicitly hands off control to the build agent, which then has the necessary permissions to modify your dbt files. Crucially, every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, providing granular control. When the build agent proposes actual file edits, Atlas computes a unified diff for every change and surfaces it for your approval before writing. This includes changes to `dbt_project.yml`, `models/`, or `schema.yml`. Atlas also reads `git branches`, `status`, and `diffs`, and can stage and create commits on your behalf, ensuring a fully auditable and reviewable workflow for your dbt transformations. For example, Atlas will prompt for permission before running `dbt build` against your dev target, never against production.

Iterating and refining dbt change plans with Atlas

Refining a multi-file dbt change plan is straightforward with Atlas, allowing for iterative improvements before any code is touched. If you decide a plan needs more work, simply answer 'No' when prompted by the `plan_exit` tool. This keeps you in the read-only plan agent, enabling further research and refinement of your design document, ensuring a robust plan for your 2026 dbt project.

The `plan_exit` tool is designed to facilitate an iterative planning process. If, after reviewing your drafted plan, you determine that more research or design work is needed, answering 'No' to the 'Would you like to switch to the build agent and start implementing?' question will raise a `Question.RejectedError`. This action keeps you within the plan agent, allowing you to continue refining your plan markdown. You can leverage `codebase_search` to re-evaluate `ref()` dependencies, use `grep` to find specific patterns in your `models/` directory, or consult `lsp` for schema details. This flexibility ensures that your multi-file dbt change plan is thoroughly vetted and complete before you commit to any implementation, preventing costly rework later in the development cycle. Atlas snapshots file changes as git patches, so even during the build phase, edits can be diffed and rolled back if needed.

From dbt plan to implementation with Atlas

Once your multi-file dbt change plan is approved, Atlas direct transitions to the build agent to begin implementation. This agent can then perform concrete dbt-specific tasks, such as converting an expensive table model to incremental, adding `not_null` and `unique` tests to new columns in `schema.yml`, and formatting SQL with `sqlfmt`. This structured hand-off ensures a smooth workflow for your 2026 dbt development.

After you approve the plan and switch to the build agent, Atlas is ready to implement the changes outlined in your plan. The build agent has the necessary permissions to modify your dbt project files. For example, if your plan involved converting an expensive table model to an incremental one, Atlas can modify the model's SQL to include a proper `is_incremental()` filter and define a `unique_key`. It can then proceed to add `not_null` and `unique` tests to the new columns in the corresponding `schema.yml` file. Following these structural changes, Atlas will automatically format the SQL with `sqlfmt` to maintain code consistency. Throughout this implementation phase, Atlas computes a unified diff for every file edit and surfaces it for your approval before writing, ensuring you maintain full control over every modification to your dbt codebase. Atlas can also run `dbt build` against your dev target, always behind a permission prompt, never against production.

Step by step

01Run Atlas in your dbt project, ensuring `dbt_project.yml` and `models/` directories are present.
02Switch to the plan agent by typing a command like `atlas plan` to enter read-only design mode.
03Research your dbt codebase using Atlas tools like `codebase_search`, `grep`, `read`, and `lsp` to understand `ref()` calls, `source()` dependencies, and `schema.yml` tests.
04Write your multi-file dbt change plan into the allowed markdown file, detailing proposed modifications to models, tests, and configurations.
05Call the `plan_exit` tool to propose plan completion and ask to switch to the build agent for implementation.
06Answer 'Yes' to the `plan_exit` prompt to hand off to the build agent, or 'No' to continue refining your dbt plan.
07Allow the build agent to implement dbt changes, such as converting a table model to incremental with `is_incremental()` and `unique_key`.
08Approve Atlas's proposed additions of `not_null` and `unique` tests to new columns in `schema.yml` and the formatting of SQL with `sqlfmt`.
09Review the unified diffs for all dbt file edits and approve them before Atlas writes the changes and stages them for commit.
10Run `dbt test` and `dbt build` against your dev target, prompted by Atlas, to validate the implemented dbt changes.

Frequently asked questions

How does Atlas prevent accidental dbt code changes during planning?: Atlas's plan agent operates in a strictly read-only mode for your entire dbt codebase. It only permits writing to a designated plan markdown file under `.atlas/plans/*.md`, ensuring that research and design cannot accidentally turn into an edit of your `dbt_project.yml` or `models/` files.
Can Atlas understand my dbt model DAG and schema tests?: Yes, Atlas can read your dbt model DAG through `ref()` and `source()` calls, your `schema.yml` tests, and each model's materialization configuration. It uses tools like `lsp` and `codebase_search` to provide deep context on your dbt project structure.
What dbt-specific tools does Atlas integrate with?: Atlas integrates directly with core dbt tools. It can run `dbt test` to validate your models, manage dependencies with `dbt deps (packages.yml)`, and ensure code style with `sqlfmt`. Atlas also prompts for permission before running `dbt build` against your dev target.
How does Atlas ensure my dbt changes are reviewed before committing?: Atlas ensures review through several mechanisms: the `plan_exit` tool requires explicit approval to switch from planning to implementation, every tool call is permission-gated, and Atlas computes a unified diff for every file edit, surfacing it for your approval before writing. It can also stage and create commits on your behalf.
Can Atlas help me convert a dbt table model to incremental?: Yes, Atlas can assist in converting an expensive table model to incremental. It can modify the model's SQL to include a proper `is_incremental()` filter and define a `unique_key`, as part of the implementation phase after your plan is approved.
Is my dbt code kept private when using Atlas for planning?: Yes, Atlas prioritizes privacy. It can build its code index with local Ollama embeddings, keeping your dbt code off third-party servers. All Atlas tool calls are permission-gated, giving you control over data access.
How does Atlas handle dbt package dependencies?: While Atlas's primary role is planning and implementing code changes, it understands the dbt ecosystem. It recognizes `dbt deps (packages.yml)` as the package manager and can factor package dependencies into its understanding of your model DAG during research, though it doesn't directly manage `packages.yml` content without explicit instruction.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Plan a Multi-File Change Before Editing with Atlas in 2026

How to plan a multi-file change with Atlas in 2026: the plan agent denies all edit tools, you research with codebase_search and lsp, then plan_exit hands off.

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.

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.

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.

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

Audit a dbt Repository with Parallel Subagents in Atlas in 2026

Sweep your dbt project for issues without context window limits. Atlas uses parallel subagents to audit `dbt_project.yml` and `schema.yml` files, leveraging `dbt test` and `sqlfmt` for comprehensive review.

Review a dbt Pull Request with Atlas in 2026

Atlas helps dbt developers in 2026 review pull requests by providing deep context beyond the diff. Catch subtle bugs in dbt models, tests, and materializations with intelligent code analysis and real dbt toolchain

Browse this resource hub