# Add dbt-checkpoint Pre-commit Hooks to a dbt Project

Yes. An agent extends your dbt project's pre-commit config with dbt-checkpoint hooks that fail a commit when a model lacks a description or tests, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-pre-commit-hooks/dbt/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads what the project already runs before a commit. In a project like dbt-labs/jaffle-shop, `.pre-commit-config.yaml` has two repos: `pre-commit-hooks` at v6.0.0 with `check-yaml`, `end-of-file-fixer`, `trailing-whitespace` and `requirements-txt-fixer`, and `ruff-pre-commit` at v0.14.10 with `ruff-check --fix --exit-non-zero-on-fix` and `ruff-format`. Both are about YAML, whitespace and Python; nothing looks at a model. `requirements.in` asks for `pre-commit>=3.6.0`, `requirements.txt` is compiled by uv and pins `pre-commit==3.7.0`, and the README's pre-commit section explains the four checks and says SQLFluff was left out on purpose because it does not work well with the dbt Cloud IDE, keeping `.sqlfluff` (dialect `snowflake`, templater `dbt-cloud`) only as a future-proofing file. The agent respects that decision and does not add a SQLFluff hook.

It then measures the models against the checks it is about to add. `dbt_project.yml` names the project `jaffle_shop` at version 3.0.0, puts tests under `data-tests/`, which is empty, and configures staging as views and marts as tables. Six staging models and seven marts have properties files, and every model has a description. Column documentation is uneven: the staging files describe every column, `orders.yml` and `customers.yml` describe most, but `locations.yml` describes none of its three columns, `products.yml` and `supplies.yml` describe only the model, and `metricflow_time_spine.yml` has a `date_day` column with no description. Tests are uneven too: every `stg_*` model has `not_null` and `unique` on its id, `orders` and `customers` carry model-level `dbt_utils.expression_is_true` tests, `order_items` tests its columns, and `locations`, `products`, `supplies` and `metricflow_time_spine` have no test at all, even though `locations.yml` already marks `location_id` as a primary entity. `packages.yml` pins `dbt_utils` 1.4.1 and `dbt-audit-helper` from git, with the resolved commit in `package-lock.yml`.

From that the agent adds a `dbt-checkpoint` repo to the config at a pinned tag and chooses hooks the repository can pass on the day they land: `check-model-has-description`, `check-model-has-properties-file`, `check-script-semicolon`, `check-script-has-no-table-name`, which passes because every model selects from `ref()` or `source()`, and `check-model-has-tests` with `--test-cnt 1`. For the last one it adds `not_null` and `unique` on the primary key of the four models that have none, `date_day` in the case of the time spine, the same shape the staging models use, so the hook holds everywhere rather than being scoped around the gap. `check-model-columns-have-desc` is added with a `files` filter limited to `models/staging/`, where it already passes, and the pull request lists the marts columns that would have to be described before the filter can be widened. The dbt-checkpoint hooks read `target/manifest.json`, so the agent adds the `dbt-parse` hook ahead of them and documents in the README section that a local profile is needed for the parse.

Before opening anything the agent installs `pre-commit` from `requirements.txt` and the dbt CLI the `Taskfile.yml` installs, writes a throwaway `profiles.yml` outside the repository, runs `dbt deps` and `dbt parse`, and runs `pre-commit run --all-files` to see every hook pass over the whole tree, including the new tests it added. Because `.github/workflows/ci.yml` only triggers dbt Cloud jobs through `dbt_cloud_run_job.py` and never runs pre-commit, it adds a small `lint` job to that workflow that installs the same pins, parses with a dummy profile and runs `pre-commit run --all-files`, so a commit made from the dbt Cloud IDE, where git hooks do not run, is still checked on its pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add dbt-checkpoint hooks to this dbt project's pre-commit configuration. Read .pre-commit-config.yaml, requirements.in, requirements.txt, dbt_project.yml, packages.yml, package-lock.yml, Taskfile.yml, the README's pre-commit section, .github/workflows/ci.yml and every properties file under models/ first. Keep the existing hooks and do not add SQLFluff, since the README explains why it was left out. Add the dbt-checkpoint repo at a pinned tag with dbt-parse first, then check-model-has-description, check-model-has-properties-file, check-script-semicolon, check-script-has-no-table-name and check-model-has-tests with --test-cnt 1; add not_null and unique tests on the primary key of each model that has no test so that hook passes everywhere; add check-model-columns-have-desc scoped with a files filter to the directory where every column is already described, and list in the pull request the columns that block widening it. Install pre-commit and dbt in the sandbox, write a throwaway profile outside the repository, run dbt deps, dbt parse and pre-commit run --all-files, and fix anything that fails. Add a lint job to the GitHub Actions workflow that runs the same pre-commit pass on pull requests. Update the README's list of checks and open a pull request with the pre-commit output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `.pre-commit-config.yaml`, adds `data_tests` to the four marts properties files that had none, adds a `lint` job to `.github/workflows/ci.yml`, and extends the README's list of checks. No SQL changes: the models, macros and seeds are as they were, and the dbt Cloud jobs in the workflow are untouched.

The description lists each new hook with what it checks and quotes the `pre-commit run --all-files` summary from the sandbox showing every hook passing, followed by the table of marts columns without descriptions that the scoped hook leaves for later. The `dbt parse` and pre-commit commands with their full output are in the session transcript at `GET /o/{org}/sessions/{id}/messages`.

Before merging, a reviewer reads the new tests to confirm the keys they assert are the right grain for those models, checks the pinned dbt-checkpoint tag, and runs `pre-commit install` once locally so the hooks fire on their own commits. A follow-up message to the same session can add the missing column descriptions and widen the `files` filter to the whole `models/` tree.

## Run it on every terminal hand-off

An analytics engineer who keeps catching undocumented models in review starts this from the terminal with this body and goes back to the model they were writing. The run reads the real properties files, so the hooks it enables and the tests it adds come from where the project stands, not from a default list that fails on day one.

Send a `request_id`, a UUID, with the body so a retried start returns the run it already began. When the run finishes, its `GET /o/{org}/sessions/{id}` answer names the pull request.

## Why run it on Rush?

The hard part of adopting dbt-checkpoint is not the YAML, it is finding out which hooks the repository can pass and closing the gaps so the first commit after merge does not fail for everyone. The agent runs the whole pass in its own sandbox with a parsed manifest, reads what fails, adds the tests or the scope needed, and runs it again until it is clean, before anyone else sees it.

Every `dbt parse` and `pre-commit run` the agent executed is kept with its output in the session record, so the claim that the hooks pass is backed by the run that showed it. A data team with several dbt projects can send this request for each at once and get one pull request per project, each with the hooks that project can hold today and a list of what blocks the rest.

## Frequently asked questions

### Why not add SQLFluff while you are at it?

Because the project's README says it was left out deliberately: the `dbt-cloud` templater does not work well with the dbt Cloud IDE, and `.sqlfluff` is kept only as a reference. The agent follows the repository's stated decision and names it in the pull request, so a team that has moved to the local CLI can ask for it in a follow-up.

### Do the hooks need a warehouse connection?

The dbt-checkpoint checks read `target/manifest.json`, which `dbt parse` produces without running a query, but parsing needs a profile that names an adapter. The README section the agent writes shows a minimal local profile, and the CI job uses a dummy one for the same reason.

### Will commits from the dbt Cloud IDE be checked?

Git hooks do not run inside the IDE, so a commit made there bypasses pre-commit. That is why the agent adds a `lint` job to the GitHub Actions workflow: the pull request still gets the same pass, and a model without a description fails the check there.

### Why scope the column-description hook to staging?

Because `locations.yml`, `products.yml`, `supplies.yml` and `metricflow_time_spine.yml` have columns with no description today, and enabling the hook repo-wide would fail every commit that touches them until someone writes the text. Scoping it to `models/staging/` makes it enforceable now; the pull request lists the exact columns that stand between the team and the wider filter.

## More dbt jobs

- [Add Semantic Models and Metrics to a dbt Project](https://getrush.ai/run/add-semantic-models/dbt/)
- [Add Slim CI for a dbt Project With GitHub Actions](https://getrush.ai/run/add-slim-ci/dbt/)
- [Add Snapshots to a dbt Project](https://getrush.ai/run/add-snapshots/dbt/)

## The same job on other stacks

- [Add Pre-commit Hooks to a Kubernetes Manifest Repository](https://getrush.ai/run/add-pre-commit-hooks/kubernetes/)
- [Add Pre-commit Hooks to a Python Project](https://getrush.ai/run/add-pre-commit-hooks/python/)
- [Add Pre-commit Hooks to a Reflex App](https://getrush.ai/run/add-pre-commit-hooks/reflex/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
