diff --git a/docs/docs/data-engineering/guides/using-with-claude-code.md b/docs/docs/data-engineering/guides/using-with-claude-code.md index 08032f933b..1142d230b7 100644 --- a/docs/docs/data-engineering/guides/using-with-claude-code.md +++ b/docs/docs/data-engineering/guides/using-with-claude-code.md @@ -100,6 +100,20 @@ altimate: The plugin runs `altimate-code run` in your project for each task, with the model provider Altimate Code is set up with. If you have not set one up, run `altimate-code` once and choose a provider, or sign in to Altimate (below). +### dbt helpers beside the chat + +In a dbt project the plugin also does what dbt Power User does in VS Code, inside the Claude Code session. Each helper runs the project's own dbt (from a `.venv` or `venv` in the project folder when there is one, else `dbt` on `PATH`) and makes no model-provider call on its own (only **Explain** and **Fix with Altimate Code**, when you press them, hand a failure to Claude or Altimate Code): + +| Helper | When it runs | What you see | What Claude is told | +|---|---|---|---| +| Compile and validate | After Claude edits or writes a model's `.sql` file, and again after Claude's next command or edit when the model, a schema file or another SQL file (a macro) changed | A line above the prompt: the model compiled and ran (`dbt show`, one row), with the columns `schema.yml` documents but the query did not return, and those it returned undocumented. When the query returns no row or `schema.yml` documents no columns, it says the columns were not compared. A problem opens the **dbt check** pane with every column, or dbt's whole error | dbt's own error when the model does not compile or run, or the column differences | +| Explain and Fix | After a `dbt run`, `test`, `build`, `seed`, `snapshot` or `retry` Claude ran fails | The failed nodes with **Explain** (Claude explains each failure without changing files) and **Fix with Altimate Code** (runs `/altimate-code:altimate` on the failures) | The failure, read from the `target/run_results.json` the command wrote, together with the errors dbt printed, when you press a button. A passing run of the same kind (or a build) clears it when it matches the failed one: the same selection, the same flags (target, vars, `--full-refresh`, …), the same folder and the same environment variables set in the command. Flags that change only the output or the concurrency, such as `--log-format` or `--threads`, are ignored (a passing `dbt retry` never clears it; a compound command is cleared only by the same command or a whole-project build, and a killed run or output that cannot be split per command, such as output piped through `tail` with its headers cut off, clears nothing) | +| Query results pane | After Claude runs `dbt show`, or when you run `/dbt-show ` or `/dbt-show select …` | The rows as a table beside the chat, resizable with **Min / Default / Max** (Default is the widest dock beside the chat; Min narrows it to a quarter; Max is as wide as Default and taller above the prompt; a size you drag yourself wins), with **Re-run** (Claude's own command with the same flags and folder, unless it depended on its shell, such as a variable or `~`; or your query), **Bookmark**, **Clear history**, the history and your bookmarks (kept on this machine across sessions); several different `dbt show`s in one command save no preview | Nothing | +| Model context | When Claude reads a model's `.sql` file | A toast with the counts | The model's materialization, columns with their types, descriptions and tests, its parents and children, and how deep it sits upstream and downstream, from `target/manifest.json` | +| Environment doctor | At session start, and `/dbt-doctor` | A line above the prompt when something is wrong: dbt, Python, the profile's adapter, `dbt deps`, and a manifest older than the files it was built from, with **Run dbt parse** or **Run dbt deps** | The checks, with the first prompt after they finish | + +The doctor tests the warehouse connection (`dbt debug`) only when you run `/dbt-doctor` or press **Test connection**, never at session start. Compile and validate runs a query on your warehouse after each model edit, which costs money on a warehouse that bills by bytes scanned or wakes a suspended one. To turn the helpers off, set the plugin's `dbt_mods` option to false in `/config`. + ### The `/altimate` command, without the plugin Run `/configure-claude` inside altimate to write the command: