# dbt-agents

`dbt-agents` is an open-source, local-first toolkit for reviewing, querying,
testing, and safely fixing dbt projects and their warehouses with AI agents.

The initial warehouse implementation targets BigQuery, while the core contracts
are designed for additional adapters. The primary interfaces are an MCP server
for ChatGPT/Codex and a CLI for local use and GitHub Actions.

The same policy-enforced core powers:

- a Model Context Protocol server for ChatGPT and Codex;
- a local CLI for inspection and diagnostics; and
- deterministic automation suitable for GitHub Actions.

## ChatGPT and Codex plugin

The internal plugin is branded as **dbt Agents** and packages the existing authenticated remote
connection with a guided setup workflow. From this checkout, install it with:

```bash
make plugin-install
```

Restart the ChatGPT desktop app, choose **The Data Strategist Internal** in the Plugins Directory,
install **dbt Agents**, and connect with an approved Google account. See
[Plugin distribution](docs/plugin-distribution.md) for team setup, validation, and the requirements
that remain before a public submission. Brand Monitor uses a separate hosted connection; see
[Brand Monitor plugin distribution](docs/brand-monitor-plugin-distribution.md) for its exact
project boundary and teammate onboarding flow.

The hosted internal plugin exposes only bounded, read-only access to the approved dbt mart. The
local toolkit retains its separate plan-and-approval workflow for dbt changes.

## Quick start

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[all,dev]'
cp examples/keylo.dbt-agents.yml dbt-agents.yml
.venv/bin/dbt-agents check-config --config dbt-agents.yml
.venv/bin/dbt-agents project keylo --config dbt-agents.yml
```

See [Getting started](docs/getting-started.md) for authentication, Codex, and
ChatGPT setup. The architecture and acceptance criteria are in the
[design specification](docs/design-spec.md).

Project-scoped tools use the configured dbt-agents alias (for example,
`keylo`), not the warehouse project ID. Use the read-only `project_list` MCP
tool or `dbt-agents projects` CLI command to discover valid aliases. See the
[project discovery specification](docs/specs/project-discovery.md).

For a repository that has not yet been configured, use the initial CLI-first
[project onboarding and readiness flow](docs/specs/project-onboarding.md).
It discovers a dbt project's configuration contract, collects
operator-confirmed non-secret values, validates from offline checks through
optional bounded warehouse access, and only then registers an MCP project
alias.

Before approving dbt execution, run the offline and live readiness checks in
[Operational readiness](docs/operations.md). The same guide covers non-mutating
IAM verification, the validation ladder, and trusted release publishing.

## Safety model

- strict repository roots and writable-path allowlists;
- protected credential and environment files;
- SHA-guarded atomic file replacement;
- SQL AST validation, one-statement enforcement, dry runs, byte budgets, row
  limits, and IAM read-only query credentials;
- exact short-lived plans plus out-of-band local approval for writes;
- separate query and dbt-runner identities;
- fixed dbt and Git command builders with no arbitrary shell tool; and
- sanitized, owner-only JSONL audit events without file bodies or query results.

The initial warehouse provider is BigQuery. Provider contracts are intentionally
small so other adapters can implement the same safety semantics.

## Compatibility

The public names, safety defaults, and v1 support boundary are frozen in the
[v1 contract](docs/contracts/v1.md) and
[ADR-0001](docs/adr/0001-v1-contract-freeze.md). Additive changes remain
possible; breaking configuration or MCP changes require a new contract version
and migration guide.

v1 supports Python 3.11–3.13, dbt Core 1.10–1.11, BigQuery, macOS/Linux local
execution, and GitHub.com publishing through `git` and `gh`.