Skip to content
Open
Show file tree
Hide file tree
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
1 change: 1 addition & 0 deletions plugins/altimate-code/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ All notable changes to this plugin will be documented in this file.
- `/scan-cost` with no model keeps the planner label of the last Snowflake or Databricks estimate ("Snowflake plan estimate").

### Added
- The README documents the cost check, project health, team comments, `/runs`, `/profile-ctes`, `/sql-graph`, `/to-model`, `/defer` and `/target`, and `/propagate`, lists the hooks module among the components, and says those need altimate-code 0.12.12 (the release with the dbt Power User tools they call) while the plugin itself runs from 0.12.11.
- The README explains `altimate-dbt`, the dbt command line that comes with altimate-code, what the agent uses it for, and that you do not need to run it.

## [1.8.2] — 2026-11-19
Expand Down
19 changes: 18 additions & 1 deletion plugins/altimate-code/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Then restart Claude Code.

## Prerequisites

The altimate-code CLI must be installed and configured on your PATH, version 0.12.11 or later. Older releases give no column answer, so the end-of-task summary and report can't say which columns a change reaches. Install it with npm:
The altimate-code CLI must be installed and configured on your PATH, version 0.12.11 or later. The cost check, project health, team comments, `/runs`, `/profile-ctes`, `/sql-graph`, `/to-model`, `/defer` and `/propagate` need 0.12.12, the release that brings the dbt Power User tools they call; on 0.12.11 most of them say so where their answer would be, while `/runs` records nothing and `/defer` adds no flags (`/defer status` shows the error), and the plugin's own version notice at session start only warns below 0.12.11. Releases before 0.12.11 give no column answer, so the end-of-task summary and report can't say which columns a change reaches. Install it with npm:

```bash
npm i -g @altimateai/altimate-code # requires Node 20+; exposes `altimate` and `altimate-code`
Expand Down Expand Up @@ -156,6 +156,22 @@ Compile and validate runs a query on your warehouse after every model edit (`dbt

When Claude mentions `altimate-dbt`, it is the dbt command line that comes with altimate-code (`npm i -g @altimateai/altimate-code`, the same install as the plugin's engine). It finds your dbt project folder, Python environment and warehouse adapter by itself, and altimate-code's agent uses it instead of the raw dbt tool for better error messages. Its commands include `init`, `doctor`, `compile`, `build`, `run`, `test`, `deps`, `columns <model>`, `graph` (lineage) and `execute "<sql>"` (a query through the dbt adapter). You do not need to run it yourself: Claude and the altimate-code agent call it when a task needs it, and the plugin's own dbt helpers above do not depend on it. See [altimate-dbt in the altimate-code docs](https://docs.altimate.sh/data-engineering/tools/dbt-tools/#altimate-dbt-cli).

## Cost, health, comments and more

The rest of dbt Power User, as panes and commands in the session. They call altimate-code's dbt tools (release 0.12.12 or later) through `altimate tool run`, never the plugin's MCP server, and make no model-provider call of their own. The cost check, project health, the SQL graph and CTE timing start the project's dbt adapter, which needs write permission, so the plugin runs them with `--allow-write` itself, without asking. One that cannot work (no altimate-code, or one without its tool) says so where it would have shown its answer, except dbt runs, which records nothing, and defer, which adds no flags.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SUGGESTION: Subject-verb agreement: dbt runs is plural

"except dbt runs, which records nothing" should read "which record nothing" (or "except /runs, which records nothing"). The parallel exception that follows ("defer, which adds no flags") is singular, so this reads as a typo rather than a deliberate reference to the /runs feature.


- **Scan cost check** (`/scan-cost <model>`, `/allow-scan`; setting `maxScanBytes`). Before a `dbt run`, `build` or `show` that Claude runs, the plugin asks `dbt_cost_estimate` what the query would scan: a dry run on BigQuery, the planner's `EXPLAIN` estimate on Snowflake and Databricks. Over the limit (10 GiB by default; 0 never holds) the command is refused with the estimate, in a line above the prompt, until you run `/allow-scan`, which lets that same command through once when it is run again unchanged. Only a command that names its query is estimated: `dbt show --inline <sql>` or a single plain model name (`-s orders`); any other selection, and a command that sets its own target, defer state, vars or project, runs as it is with a line saying so under the Bash row. A query with no estimate (a Databricks table without statistics, an `EXPLAIN` that failed) runs with a line saying why; a warehouse with no estimate is never held after its first answer. Snowflake's number is an upper bound, except where the answer says the bound is unknown (an external table, a stage, a secure view, or a plan that reports 0); Databricks' is the tables' size; and on Databricks the `EXPLAIN` can start a stopped SQL warehouse, which is billed while it runs. `/scan-cost <model>` asks for an estimate; with no model it repeats the last one.
- **Project health** (`/health`; settings `healthBlocksPush`, `healthConfigPath`). Needs the `altimate-datapilot-cli` package in the project's Python. At session start `dbt_health` (DataPilot) records every insight the project already has. After a turn in which Claude changed model files (`.sql`, `.yml`), the check runs again, and the insights the baseline lacks, on the models those files hold, are the new issues: a band above the prompt lists them, and `/health` shows them in a pane. With `healthBlocksPush` on, `git push` is held until the check of your latest changes is in and refused while any issue remains, or while the check cannot run. One check runs at a time and can take minutes (the dbt adapter starts, then DataPilot reads the manifest); its dbt run writes its artifacts under `target/.altimate-plugin/`, not over the project's `manifest.json`.
- **Team comments** (`/comments`; settings `commentsPollSeconds`, `commentsInContext`). The open comment threads of the dbt docs your team shared through Altimate, fetched with `docs_share_comments` at session start (or at the first model read, for a project below the session folder) and, in an interactive session, every `commentsPollSeconds`. When Claude reads or edits a model that has open threads, one context block names each thread's line and text (up to 8 threads, as quoted data), so it sees the review before it changes the model. The pane lists the threads with **Reply**, **Resolve** and **Refresh**; a post is confirmed against the list before the thread is unlocked. Claude has no way to post. Needs an Altimate sign-in; signed out, the poll stops, and **Refresh** or `/comments` starts it again once you are signed in.
- **dbt runs** (`/runs`). After a Bash call that ran a dbt command which writes `run_results.json` (`run`, `build`, `test`, `seed`, `snapshot`, `compile`, `retry`, `clone`), the run is read with `dbt_run_results` and recorded once: command, timings, counts and up to 50 node rows, failures first, for up to 50 runs per project, kept in Claude Code's plugin store on this machine. The pane shows them newest first; a run can be opened, run again, or its failures run again through the prompt. A run whose folder or artifact cannot be told apart is not recorded: for overlapping dbt commands Claude is told so, for a shell-expanded target folder nothing is said.
- **Profile CTEs** (`/profile-ctes [model]`). Times each CTE of a model: one `COUNT(*)` query per CTE through `dbt_cte_profile`, each holding the CTEs before it, listed slowest first in a pane that fills as the queries finish (**Stop** works between queries; a query already running cannot be cancelled). Hot, warm and cool follow dbt Power User's rule: half or more of the largest added time, a fifth, the rest. 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, from `dbt_sql_graph`, with joins, filters, groups and sorts named by their clause. The tool compiles the model and reads the parents' column metadata from the warehouse. A node's SQL over 20,000 characters is cut, and the pane says so.
- **Raw SQL to a dbt model** (`/to-model <model_name> [path/to/query.sql]`). Takes a SQL file, or the text you selected, and asks `dbt_map_relations` for the `ref()` or `source()` call of each table in it, matched against the manifest. The pane lists the tables that need a decision first (no match, a partial match), then matches that differ only in case, then exact matches; one instruction asks Claude to write the model with exactly those replacements. The model name must be a dbt identifier (letters, digits and underscores).
- **Defer and target** (`/defer [status|on|off|reset]`, `/target [<name>|reset]`). Reads the dbt Power User defer setting through `dbt_defer_state` and adds `--defer --state <dir>` (and `--favor-state`) to the dbt commands Claude runs that take it (`build`, `run`, `test`, `compile`, `show`, `snapshot`) and do not set it themselves, and `--target <name>` to those without one once you chose a target for the session. `/defer on` and `/defer off` override the setting for the session; `reset` goes back to it. `/target` works on any altimate-code version; only the defer state needs 0.12.12. The target shows in the status line, Claude's result says what the command ran as, and a line above the prompt shows the flags added until the next prompt. A command with a word the parser cannot read (`$FLAGS`, `~/x`, a glob) is left as written.
- **Docs coverage and propagation** (`/propagate`). After Claude edits a model's SQL, the model's documentation coverage from `dbt_docs_coverage` (which output columns have no description, and the percent documented) is shown; until the edit's compile-and-validate check has run, it says it is from before the edit. After Claude writes a column description in a model's YAML, the downstream columns that carry the same value (`impact_analysis` column reach; only a column carried as is or renamed, not a calculation from it) are offered as copies: a line under the edit, a band line, and the `/propagate` pane, where you tick the columns you want and one **Apply** button asks Claude to write the description there. Up to three descriptions per edit are traced, and the pane keeps up to ten pending.

[Data handling](#data-handling) lists which of these count their use anonymously. Several act without a command: the cost check holds dbt commands, project health runs at session start and after model edits, comments are polled, dbt runs are recorded after each dbt command, defer adds its flags when the project's setting is on, and propagation offers copies after each description Claude writes. `maxScanBytes` 0 turns the cost check off and the two comments settings bound the comments; project health and the coverage line have no off switch (`healthBlocksPush` only decides the push gate).

## Settings

The plugin has seven settings, shown when you enable it (`userConfig` in `.claude-plugin/plugin.json`). All are optional: Claude Code may report them as "not set", and each then takes the default below. `dbt_mods` is used by the dbt helpers, `maxScanBytes` by the scan check (BigQuery, Snowflake, Databricks), `healthBlocksPush` and `healthConfigPath` by the project health check, the two comments settings by team comments, and `show_edit_impact` by the per-edit impact note.
Expand Down Expand Up @@ -217,6 +233,7 @@ Still stuck? See [Support](#support).
- **Agent** — `agents/analyst.md` — read-only data analyst (MCP or CLI)
- **Command** — `commands/altimate.md` — `/altimate-code:altimate` slash command for explicit delegation
- **Command** — `commands/rules.md` — `/altimate-code:rules` to answer proposed team rules
- **Hooks module** — `hooks/integrations.tsx` (named in `hooks/hooks.json` `modules`) — the panes and in-session commands: one-click integrations, the lineage pane and end-of-task summary (`hooks/lineage.tsx`, `hooks/task-impact.tsx`), the dbt helpers (`hooks/dbt-mods.tsx`), the dbt Power User features (`hooks/features/`: runs, defer and target, to-model, team comments, cost check, project health, SQL graph, docs coverage, CTE profile), the review-decision toasts, the status line and the usage events
- **Hooks** — `hooks/hooks.json` — SessionStart capability description and workspace skill copy; Stop hook hourly background skill refresh; the team rules hooks (`hooks-handlers/workspace-rules.sh`): SessionStart, UserPromptSubmit and Stop, which call `altimate learn hook <event>` and never fail the session (the per-turn hooks run in the background; session start waits at most 15 seconds); opt-in PreToolUse `warehouse-guard.sh` (needs `ALTIMATE_ROUTE_GUARD=1`)

## Support
Expand Down
Loading