> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-mintlify-5a87a3b2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI writeback (Beta)

> Ask an AI agent to edit your dbt project in chat and open a pull request with the changes.

<Warning>
  AI writeback is currently in Beta and gated by a feature flag. Contact
  Lightdash support to enable it for your organization.
</Warning>

AI writeback lets you ask an AI agent in chat or Slack to change something in the dbt repository that backs your project — rename a metric, add a dimension, edit a model's SQL, fix a YAML description — and have the agent open a pull request (or GitLab merge request) with the change.

This is the same writeback capability you would normally trigger from the Custom Metric or SQL Runner menus, surfaced inside the conversation with your AI agent.

## When to use it

Use AI writeback when the change you want needs to land in your dbt project files:

* Rename a metric in a YAML file
* Add a new metric or dimension to a dbt model
* Edit a model's SQL
* Update a description, label, or `meta` block
* Fix a typo in a column definition

For other kinds of changes, the agent will pick a different tool:

| You want to…                                     | The agent uses…           |
| ------------------------------------------------ | ------------------------- |
| Ask a question about data                        | Query and discovery tools |
| Edit an existing chart or dashboard in Lightdash | `editContent`             |
| Change the underlying dbt repository             | `proposeWriteback`        |

## Prerequisites

* The **AI writeback** feature flag must be enabled for your organization.
* Your project's dbt connection must be a **GitHub** or **GitLab** repository. Bitbucket, Azure DevOps, dbt Cloud, and local dbt projects are not supported.
* The matching Lightdash app must be installed for the repository so the agent can open requests:
  * **GitHub** — install the Lightdash GitHub App on the repository.
  * **GitLab** — connect the Lightdash GitLab App for your organization (self-hosted GitLab is supported via the project's `host_domain`).
* You need at least [project Developer](/references/workspace/roles) permissions on the project.

## How it works

When you ask the agent for a change that belongs in the repo, it calls a tool called `proposeWriteback`. The tool:

1. Spawns a separate, sandboxed writeback agent with no memory of your chat.
2. Hands that agent a self-contained instruction generated from your request.
3. The writeback agent edits the relevant files, runs `lightdash compile` to validate the result, and pushes a new branch.
4. A pull request (GitHub) or merge request (GitLab) is opened against your repository's default branch and the URL is returned to you in chat.

The tool call is synchronous and can take a few minutes. The agent will tell you a pull request is being prepared while it waits.

<Note>
  GitHub commits are signed by the Lightdash GitHub App. GitLab commits are
  pushed over OAuth and are unsigned.
</Note>

## Using it in chat

Phrase your request as a direct change to the repo and, where possible, name the file, model, or field you want touched. The more specific you are, the more reliably the writeback agent finds the right place to edit.

**Good prompts**

```text theme={null}
In models/orders.yml, rename the metric `total_revenue` to `net_revenue`
and update its description to "Revenue after refunds and discounts."
```

```text theme={null}
Add a new metric `active_users_7d` to the users model. It should be a
count_distinct of user_id filtered to events in the last 7 days.
```

```text theme={null}
In the customers model, fix the typo in the `lifetime_value` dimension
description: change "lifteime" to "lifetime."
```

**Less effective prompts**

```text theme={null}
Clean up our metrics.
```

```text theme={null}
Make the orders model better.
```

When the pull request is ready, the agent posts the URL in the thread. Open it, review the diff, and merge as you would any other pull request. After merging, refresh dbt in Lightdash (or let your CI/CD do it) so the change takes effect.

## Iterating on an existing pull request

If you've already opened a writeback pull request — either earlier in the same thread or by pasting a link to one — the agent commits follow-up changes onto that PR's branch instead of opening a new one. The PR's title and description are refreshed to reflect the latest change.

There are two ways this happens:

* **Same thread.** If the thread already has a writeback PR, any further writeback requests in that thread automatically resume it. You don't need to paste the link.
* **Paste a link.** In a new thread (or before a writeback PR exists for the current thread), paste the GitHub pull request URL alongside your request. The agent picks up the link, checks out that PR's branch, and commits your edits onto it.

```text theme={null}
Update https://github.com/my-org/analytics/pull/482 so the `net_revenue`
metric is rounded to 2 decimal places.
```

The pasted pull request must:

* Live in the same GitHub repository as the project's dbt connection.
* Be **open** — merged or closed PRs are rejected.
* Have its branch in the same repository (PRs opened from forks are rejected).

If any of those checks fail, the agent stops and tells you why instead of silently opening a new pull request.

## What happens if it can't run

| Situation                                                             | Result                                                                                                                                            |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Feature flag is off                                                   | The tool isn't available. The agent answers normally without offering to open a pull request.                                                     |
| Project's dbt connection isn't GitHub or GitLab                       | The agent tells you the project must be connected to a supported git host for writeback.                                                          |
| GitHub App isn't installed on the repo                                | The agent surfaces a setup error. Install the Lightdash GitHub App on the repository (from your project's dbt connection settings) and try again. |
| Writeback agent makes no file changes                                 | No pull request is opened. The agent reports back that nothing needed to change.                                                                  |
| Pasted PR link is in a different repo, merged, closed, or from a fork | The agent rejects the link with an explanation and does not open a new pull request.                                                              |
| GitLab App isn't connected for the organization                       | The agent surfaces a `GitLab App is not installed` error. Connect the Lightdash GitLab App for your organization and try again.                   |
| Writeback agent makes no file changes                                 | No pull request or merge request is opened. The agent reports back that nothing needed to change.                                                 |

## Related

* [dbt write-back](/guides/developer/dbt-write-back) — write back individual custom metrics, dimensions, and SQL Runner queries from the Lightdash UI.