From a4e3f0c9ca977b4a20f583c402dc92af6806da90 Mon Sep 17 00:00:00 2001 From: Haider Date: Sat, 21 Nov 2026 21:10:33 +0530 Subject: [PATCH 1/2] docs: install the Claude Code plugin from Altimate's marketplace, and document its panes - README and the "Using with Claude Code" guide now install the plugin from `AltimateAI/altimate-claude-plugin`; Anthropic's directory copy is a pin several versions behind, without the lineage pane or the dbt helpers - The guide gets a "Lineage, cost, health and more" section: the lineage pane, the scan cost check (`/scan-cost`, `/allow-scan`), project health, team comments, `/runs`, `/profile-ctes`, `/sql-graph`, `/to-model`, `/defer` and `/target`, and `/propagate`, with what each runs and needs - Both say the helpers need altimate-code 0.12.12 or later, the release with the dbt Power User tools they call Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01XM3J9kD6sRhQQyPAe2BVyn --- README.md | 8 +++-- .../guides/using-with-claude-code.md | 31 +++++++++++++------ 2 files changed, 27 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index d22e5e410e..3f85b11955 100644 --- a/README.md +++ b/README.md @@ -87,15 +87,17 @@ The Altimate Code plugins let Claude Code and Codex hand dbt and warehouse work altimate. Install the CLI above first — the plugins run it, they do not install it. ```bash -# Claude Code -claude plugin install altimate-code +# Claude Code — from Altimate's marketplace, which has the current plugin +# (the copy in Anthropic's plugin directory is an older pin) +claude plugin marketplace add AltimateAI/altimate-claude-plugin +claude plugin install altimate-code@altimate-claude-plugin # Codex — add the marketplace, then open Codex, type /plugins and install "Altimate Code" codex plugin marketplace add AltimateAI/altimate-codex-plugin ``` See [Using with Claude Code](docs/docs/data-engineering/guides/using-with-claude-code.md) for -the marketplace install, sign-in and the `/altimate-code:altimate` command, and the +the dbt helpers and panes, sign-in and the `/altimate-code:altimate` command, and the [Codex plugin README](https://github.com/AltimateAI/altimate-codex-plugin#install) for Codex. ## Why a specialized harness? 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 f7ede7ea56..03101fdb4e 100644 --- a/docs/docs/data-engineering/guides/using-with-claude-code.md +++ b/docs/docs/data-engineering/guides/using-with-claude-code.md @@ -86,27 +86,23 @@ altimate: ### The Altimate Code plugin (recommended) -1. Install Altimate Code (Node.js 20 or later): `npm install -g altimate-code` -2. Install the plugin from Anthropic's plugin directory: - - ```bash - claude plugin install altimate-code - ``` - - Or add Altimate's own marketplace and install from it: +1. Install Altimate Code (Node.js 20 or later): `npm install -g altimate-code`. The helpers below need version 0.12.12 or later; `altimate-code --version` shows what you have. +2. Add Altimate's marketplace and install the plugin from it: ```bash claude plugin marketplace add AltimateAI/altimate-claude-plugin claude plugin install altimate-code@altimate-claude-plugin ``` + Anthropic's plugin directory also lists the plugin (`claude plugin install altimate-code` with no marketplace), but it serves a reviewed, pinned copy that is several versions behind: it hands tasks to Altimate Code and has none of the panes and helpers below. If you installed that copy, remove it first (see [dbt helpers beside the chat](#dbt-helpers-beside-the-chat)). + 3. Start a new Claude Code session in your project. Ask for dbt or warehouse work as usual, or start a request with `/altimate-code:altimate` to hand it over yourself. (Claude Code names plugin commands `:`; the bare `/altimate` below comes from `/configure-claude`.) 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 -Plugin 1.8.0 or later brings five dbt Power User helpers into the Claude Code session when you work in a dbt project. They are on by default; to turn them off, set the plugin's `dbt_mods` option to false in `/config`. Anthropic's plugin directory serves a reviewed, pinned version of the plugin that does not yet include these helpers, so `claude plugin update altimate-code` will not bring them. Install from Altimate's marketplace instead, remove the other copy, then start a new session. Run `claude plugin list` to see which copy you have: the directory's copy is `altimate-code@anthropic-plugin-directory` (or `altimate-code@claude-plugins-official` when you added Anthropic's catalog from GitHub), and the uninstall below names it. +Plugin 1.8.0 or later brings five dbt Power User helpers into the Claude Code session when you work in a dbt project; they run the project's own dbt. The plugin also adds a lineage pane and more dbt Power User commands that call Altimate Code's dbt tools instead (see [Lineage, cost, health and more](#lineage-cost-health-and-more)). The five helpers are on by default; to turn them off, set the plugin's `dbt_mods` option to false in `/config`. Anthropic's plugin directory serves a reviewed, pinned version of the plugin that does not yet include these helpers, so `claude plugin update altimate-code` will not bring them. Install from Altimate's marketplace instead, remove the other copy, then start a new session. Run `claude plugin list` to see which copy you have: the directory's copy is `altimate-code@anthropic-plugin-directory` (or `altimate-code@claude-plugins-official` when you added Anthropic's catalog from GitHub), and the uninstall below names it. ```bash claude plugin uninstall altimate-code@anthropic-plugin-directory # or the ID `claude plugin list` shows @@ -144,6 +140,23 @@ Compile and validate runs one query on your warehouse after each model edit (a ` The helpers read `manifest.json` and `run_results.json` from the `target-path` that `dbt_project.yml` names (`target/` by default). A path set by `DBT_TARGET_PATH`, a command's `--target-path` or a Jinja `target-path` is not followed. +#### Lineage, cost, health and more + +The rest of the plugin's panes and commands call Altimate Code's tools through its MCP server or `altimate tool run`, and make no model-provider call of their own. The dbt Power User ones need altimate-code 0.12.12 or later, the release with the [dbt Power User tools](../tools/dbt-tools.md#dbt-power-user-tools); with an older one each says so and does nothing. Cost, health, the SQL graph and CTE timing start the project's dbt adapter, so they run through the CLI with write permission. The commands are listed by the bare names the plugin registers. + +- **Lineage pane** (`/lineage [.column]`). The dbt model Claude reads or edits, with every model upstream and downstream, its dashboards (exposures), each output column's sources and, for a picked column, the downstream models and dashboards that read it, from `dbt_lineage` and `impact_analysis` on `target/manifest.json`. When a task changed a model, a band above the prompt sums up each changed column's downstream reach, and **Open report** or `/lineage-report` builds an offline HTML report of it. On its own the pane opens only in a terminal at least 144 columns wide; `/lineage` opens it at any width. +- **Scan cost check** (`/scan-cost `, `/allow-scan`). Before a `dbt run`, `build` or `show` that Claude runs names one model or an inline query, `dbt_cost_estimate` says what it would scan: a BigQuery dry run, or the planner's `EXPLAIN` on Snowflake and Databricks. Over the plugin's `maxScanBytes` setting (10 GiB by default; 0 never holds) the command is refused with the estimate until you run `/allow-scan`, which lets that same command through once. A query with no estimate runs, with a line saying why, and other warehouses are never held. On Databricks the `EXPLAIN` can start a stopped SQL warehouse, which is billed while it runs. +- **Project health** (`/health`). At session start `dbt_health` (DataPilot) records the project's existing insights; after a turn in which Claude changed model files, the check runs again and the new issues on those models show in a band. With `healthBlocksPush` on, `git push` is refused while the check of your latest changes is not in or finds new issues. `healthConfigPath` names a DataPilot config file. A check can take minutes, and it needs the `altimate-datapilot-cli` package in the project's Python. +- **Team comments** (`/comments`). The open comment threads on dbt docs your team shared through Altimate, fetched at session start and every `commentsPollSeconds` (15 minutes by default). When Claude reads or edits a model that has open threads, they are added to its context as quoted data (`commentsInContext`), so it sees the review before it changes the model. Reply and resolve are buttons you press in the pane; Claude has no way to post. Needs an Altimate sign-in. +- **dbt runs** (`/runs`). Every dbt command Claude ran, with its per-node results from `dbt_run_results`, up to 50 runs per project, kept on this machine across sessions. From the pane a run can be opened, run again, or its failures run again through the prompt. +- **Profile CTEs** (`/profile-ctes [model]`). Times each CTE of a model with one `COUNT(*)` warehouse query per CTE (`dbt_cte_profile`), slowest first, in a pane that fills as the queries finish. It runs only when asked, never on an edit, since every CTE is a warehouse query. Without a model it profiles the model last read or edited. +- **SQL graph** (`/sql-graph [model]`). A model's CTEs, joins and filters as a graph beside the chat (`dbt_sql_graph`). It compiles the model and reads the parents' column metadata from the warehouse. +- **Raw SQL to a dbt model** (`/to-model [path/to/query.sql]`). `dbt_map_relations` maps each table in the SQL (a file, or the text you selected) to a `ref()` or `source()` call; the pane lists the tables that need a decision first, and then asks Claude to write the model with exactly those replacements. +- **Defer and target** (`/defer [status|on|off|reset]`, `/target [|reset]`). Adds `--defer --state ` (and `--favor-state`) and `--target ` to the dbt commands Claude runs that do not set them, from the dbt Power User defer setting (`dbt_defer_state`) or your choice for the session. The target shows in the status line, and Claude's result says what the command ran as. +- **Docs coverage and propagation** (`/propagate`). After Claude edits a model's SQL, the model's documentation coverage (`dbt_docs_coverage`) is shown. After Claude writes a column description in a model's YAML, the downstream columns that carry the same value, as is or renamed, are offered as copies, one button per column. + +The settings named above are the plugin's options in `/config`. The plugin's [README](https://github.com/AltimateAI/altimate-claude-plugin/blob/main/plugins/altimate-code/README.md) describes each pane in full, and its [PRIVACY.md](https://github.com/AltimateAI/altimate-claude-plugin/blob/main/PRIVACY.md) what each one reads, keeps and sends. + ### The `/altimate` command, without the plugin Run `/configure-claude` inside altimate to write the command: From 82e10543ce0fb2c8d5e50df31e2b6d32bff22bb5 Mon Sep 17 00:00:00 2001 From: Haider Date: Sat, 21 Nov 2026 22:33:41 +0530 Subject: [PATCH 2/2] docs: correct the Claude Code plugin guide after a cold review - The plugin runs from altimate-code 0.12.11; only the dbt Power User commands need 0.12.12. The install step said all helpers need 0.12.12. - The panes call tools through `altimate tool run` only, never the plugin's MCP server, and pass `--allow-write` without asking. - On an old CLI `/runs` records nothing and `/defer` adds no flags; the text claimed each feature says so. - `/runs` keeps the commands that wrote `run_results.json`, not every dbt command; `/propagate` has one Apply button for the ticked columns. - PRIVACY.md does not describe these panes, so the pointer to it is gone. - `healthConfigPath` is a path inside the project; comments poll only in an interactive session; the 144-column floor is Claude Code's. - README comment names the directory pin (1.0.0). Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01XM3J9kD6sRhQQyPAe2BVyn --- README.md | 2 +- .../guides/using-with-claude-code.md | 18 +++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 3f85b11955..701a309683 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ altimate. Install the CLI above first — the plugins run it, they do not instal ```bash # Claude Code — from Altimate's marketplace, which has the current plugin -# (the copy in Anthropic's plugin directory is an older pin) +# (the copy in Anthropic's plugin directory is pinned at 1.0.0) claude plugin marketplace add AltimateAI/altimate-claude-plugin claude plugin install altimate-code@altimate-claude-plugin 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 03101fdb4e..9773be5183 100644 --- a/docs/docs/data-engineering/guides/using-with-claude-code.md +++ b/docs/docs/data-engineering/guides/using-with-claude-code.md @@ -86,7 +86,7 @@ altimate: ### The Altimate Code plugin (recommended) -1. Install Altimate Code (Node.js 20 or later): `npm install -g altimate-code`. The helpers below need version 0.12.12 or later; `altimate-code --version` shows what you have. +1. Install Altimate Code (Node.js 20 or later): `npm install -g altimate-code`. The plugin needs version 0.12.11 or later, and the commands under [Lineage, cost, health and more](#lineage-cost-health-and-more) need 0.12.12; `altimate-code --version` shows what you have. 2. Add Altimate's marketplace and install the plugin from it: ```bash @@ -102,7 +102,7 @@ The plugin runs `altimate-code run` in your project for each task, with the mode #### dbt helpers beside the chat -Plugin 1.8.0 or later brings five dbt Power User helpers into the Claude Code session when you work in a dbt project; they run the project's own dbt. The plugin also adds a lineage pane and more dbt Power User commands that call Altimate Code's dbt tools instead (see [Lineage, cost, health and more](#lineage-cost-health-and-more)). The five helpers are on by default; to turn them off, set the plugin's `dbt_mods` option to false in `/config`. Anthropic's plugin directory serves a reviewed, pinned version of the plugin that does not yet include these helpers, so `claude plugin update altimate-code` will not bring them. Install from Altimate's marketplace instead, remove the other copy, then start a new session. Run `claude plugin list` to see which copy you have: the directory's copy is `altimate-code@anthropic-plugin-directory` (or `altimate-code@claude-plugins-official` when you added Anthropic's catalog from GitHub), and the uninstall below names it. +Plugin 1.8.0 or later brings five dbt Power User helpers into the Claude Code session when you work in a dbt project; they run the project's own dbt. The plugin also has a lineage pane and more dbt Power User commands that call Altimate Code's dbt tools instead (see [Lineage, cost, health and more](#lineage-cost-health-and-more)). The five helpers are on by default; to turn them off, set the plugin's `dbt_mods` option to false in `/config`. Anthropic's plugin directory serves a reviewed, pinned version of the plugin that does not yet include these helpers, so `claude plugin update altimate-code` will not bring them. Install from Altimate's marketplace instead, remove the other copy, then start a new session. Run `claude plugin list` to see which copy you have: the directory's copy is `altimate-code@anthropic-plugin-directory` (or `altimate-code@claude-plugins-official` when you added Anthropic's catalog from GitHub), and the uninstall below names it. ```bash claude plugin uninstall altimate-code@anthropic-plugin-directory # or the ID `claude plugin list` shows @@ -142,20 +142,20 @@ The helpers read `manifest.json` and `run_results.json` from the `target-path` t #### Lineage, cost, health and more -The rest of the plugin's panes and commands call Altimate Code's tools through its MCP server or `altimate tool run`, and make no model-provider call of their own. The dbt Power User ones need altimate-code 0.12.12 or later, the release with the [dbt Power User tools](../tools/dbt-tools.md#dbt-power-user-tools); with an older one each says so and does nothing. Cost, health, the SQL graph and CTE timing start the project's dbt adapter, so they run through the CLI with write permission. The commands are listed by the bare names the plugin registers. +The rest of the plugin's panes and commands call Altimate Code's tools through `altimate tool run`, and make no model-provider call of their own. The dbt Power User ones need altimate-code 0.12.12 or later, the release with the [dbt Power User tools](../tools/dbt-tools.md#dbt-power-user-tools); with an older one most say so where their answer would be, while `/runs` records nothing and `/defer` adds no flags. Cost, health, the SQL graph and CTE timing start the project's dbt adapter, so the plugin runs them with `altimate tool run --allow-write` itself, without asking. The commands are listed by the bare names the plugin registers. -- **Lineage pane** (`/lineage [.column]`). The dbt model Claude reads or edits, with every model upstream and downstream, its dashboards (exposures), each output column's sources and, for a picked column, the downstream models and dashboards that read it, from `dbt_lineage` and `impact_analysis` on `target/manifest.json`. When a task changed a model, a band above the prompt sums up each changed column's downstream reach, and **Open report** or `/lineage-report` builds an offline HTML report of it. On its own the pane opens only in a terminal at least 144 columns wide; `/lineage` opens it at any width. +- **Lineage pane** (`/lineage [.column]`). The dbt model Claude reads or edits, with every model upstream and downstream, its exposures (dashboards and other consumers), each output column's sources and, for a picked column, the downstream models and dashboards that read it, from `dbt_lineage` and `impact_analysis` on `target/manifest.json`. When a task changed a model, a band above the prompt sums up each changed column's downstream reach, and **Open report** or `/lineage-report` builds an offline HTML report of it. Claude Code opens the pane on its own only in a terminal at least 144 columns wide; `/lineage` opens it at any width. - **Scan cost check** (`/scan-cost `, `/allow-scan`). Before a `dbt run`, `build` or `show` that Claude runs names one model or an inline query, `dbt_cost_estimate` says what it would scan: a BigQuery dry run, or the planner's `EXPLAIN` on Snowflake and Databricks. Over the plugin's `maxScanBytes` setting (10 GiB by default; 0 never holds) the command is refused with the estimate until you run `/allow-scan`, which lets that same command through once. A query with no estimate runs, with a line saying why, and other warehouses are never held. On Databricks the `EXPLAIN` can start a stopped SQL warehouse, which is billed while it runs. -- **Project health** (`/health`). At session start `dbt_health` (DataPilot) records the project's existing insights; after a turn in which Claude changed model files, the check runs again and the new issues on those models show in a band. With `healthBlocksPush` on, `git push` is refused while the check of your latest changes is not in or finds new issues. `healthConfigPath` names a DataPilot config file. A check can take minutes, and it needs the `altimate-datapilot-cli` package in the project's Python. -- **Team comments** (`/comments`). The open comment threads on dbt docs your team shared through Altimate, fetched at session start and every `commentsPollSeconds` (15 minutes by default). When Claude reads or edits a model that has open threads, they are added to its context as quoted data (`commentsInContext`), so it sees the review before it changes the model. Reply and resolve are buttons you press in the pane; Claude has no way to post. Needs an Altimate sign-in. -- **dbt runs** (`/runs`). Every dbt command Claude ran, with its per-node results from `dbt_run_results`, up to 50 runs per project, kept on this machine across sessions. From the pane a run can be opened, run again, or its failures run again through the prompt. +- **Project health** (`/health`). At session start `dbt_health` (DataPilot) records the project's existing insights; after a turn in which Claude changed model files, the check runs again and the new issues on those models show in a band. With `healthBlocksPush` on, `git push` is refused while the check of your latest changes is not in or finds new issues. `healthConfigPath` names a DataPilot config file by a path inside the dbt project. A check can take minutes, and it needs the `altimate-datapilot-cli` package in the project's Python. +- **Team comments** (`/comments`). The open comment threads on dbt docs your team shared through Altimate, fetched at session start and, in an interactive session, every `commentsPollSeconds` (15 minutes by default). When Claude reads or edits a model that has open threads, they are added to its context as quoted data (`commentsInContext`), so it sees the review before it changes the model. Reply and resolve are buttons you press in the pane; Claude has no way to post. Needs an Altimate sign-in. +- **dbt runs** (`/runs`). The dbt commands Claude ran that wrote `run_results.json`, with their per-node results from `dbt_run_results`, up to 50 runs per project, kept on this machine across sessions. From the pane a run can be opened, run again, or its failures run again through the prompt. - **Profile CTEs** (`/profile-ctes [model]`). Times each CTE of a model with one `COUNT(*)` warehouse query per CTE (`dbt_cte_profile`), slowest first, in a pane that fills as the queries finish. It runs only when asked, never on an edit, since every CTE is a warehouse query. Without a model it profiles the model last read or edited. - **SQL graph** (`/sql-graph [model]`). A model's CTEs, joins and filters as a graph beside the chat (`dbt_sql_graph`). It compiles the model and reads the parents' column metadata from the warehouse. - **Raw SQL to a dbt model** (`/to-model [path/to/query.sql]`). `dbt_map_relations` maps each table in the SQL (a file, or the text you selected) to a `ref()` or `source()` call; the pane lists the tables that need a decision first, and then asks Claude to write the model with exactly those replacements. - **Defer and target** (`/defer [status|on|off|reset]`, `/target [|reset]`). Adds `--defer --state ` (and `--favor-state`) and `--target ` to the dbt commands Claude runs that do not set them, from the dbt Power User defer setting (`dbt_defer_state`) or your choice for the session. The target shows in the status line, and Claude's result says what the command ran as. -- **Docs coverage and propagation** (`/propagate`). After Claude edits a model's SQL, the model's documentation coverage (`dbt_docs_coverage`) is shown. After Claude writes a column description in a model's YAML, the downstream columns that carry the same value, as is or renamed, are offered as copies, one button per column. +- **Docs coverage and propagation** (`/propagate`). After Claude edits a model's SQL, the model's documentation coverage (`dbt_docs_coverage`) is shown. After Claude writes a column description in a model's YAML, the downstream columns that carry the same value, as is or renamed, are offered as copies: tick the columns you want and press **Apply**. -The settings named above are the plugin's options in `/config`. The plugin's [README](https://github.com/AltimateAI/altimate-claude-plugin/blob/main/plugins/altimate-code/README.md) describes each pane in full, and its [PRIVACY.md](https://github.com/AltimateAI/altimate-claude-plugin/blob/main/PRIVACY.md) what each one reads, keeps and sends. +The settings named above are the plugin's options in `/config`. The plugin's [README](https://github.com/AltimateAI/altimate-claude-plugin/blob/main/plugins/altimate-code/README.md) describes each pane in full. ### The `/altimate` command, without the plugin