Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/docs/data-engineering/guides/using-with-claude-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <model>` 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:
Expand Down
Loading