From b2a6bf8b620e90f058b07982df4ff4007dceae57 Mon Sep 17 00:00:00 2001 From: Haider Date: Mon, 19 Oct 2026 00:17:39 +0530 Subject: [PATCH 1/5] fix: delegated runs no longer hang; route workspace questions; real agent and command names (1.1.0) Found by running the plugin end to end in Claude Code 2.1.300 against a linked Altimate workspace: - Every delegation hung: Claude Code's Bash tool leaves stdin open and `altimate-code run` reads piped stdin to EOF. Invocations now redirect stdin from `/dev/null`. - `--agent fast-edit` does not exist in altimate-code; every run fell back to `builder` with a warning. Runs ask for `builder`, which also has the workspace skills and memory tools (`analyst` failed to load workspace skills in testing). - `mktemp -t altimate-result.XXXXXX.md` left literal `X`s on macOS; use `mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX"`. - Questions about the team's own conventions, standards and knowledge did not reach altimate-code, so a linked workspace's skills and memory were never consulted. The skill description, SessionStart context and `/altimate-code:altimate` now cover them, and say how to check the link, sign in and link. - Docs say `/altimate-code:altimate`: Claude Code namespaces plugin commands and answers "Unknown command" to a bare `/altimate`. READMEs add the plugin-directory install command and an "Use an Altimate workspace" section. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011chv9Rmu7jQXokum1WNcs7 --- CONTRIBUTING.md | 6 +- PRIVACY.md | 2 +- README.md | 8 +++ .../altimate-code/.claude-plugin/plugin.json | 4 +- plugins/altimate-code/CHANGELOG.md | 14 ++++ plugins/altimate-code/README.md | 29 +++++++- plugins/altimate-code/commands/altimate.md | 47 +++++++------ .../hooks-handlers/session-start.sh | 2 +- .../skills/altimate-code/SKILL.md | 66 +++++++++++-------- 9 files changed, 116 insertions(+), 62 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c264273..647b164 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,7 +34,7 @@ altimate-claude-plugin/ │ ├── hooks-handlers/ │ │ └── session-start.sh # SessionStart hook handler │ ├── commands/ -│ │ └── altimate.md # /altimate slash command +│ │ └── altimate.md # /altimate-code:altimate slash command │ ├── README.md # plugin-specific docs │ └── CHANGELOG.md # plugin-specific changelog ├── README.md # repo overview @@ -47,7 +47,7 @@ altimate-claude-plugin/ ## What to change where - **Routing behavior** (when Claude picks up the skill): edit `plugins/altimate-code/skills/altimate-code/SKILL.md` frontmatter description and/or `plugins/altimate-code/hooks-handlers/session-start.sh` `additionalContext`. -- **Explicit-invocation UX** (what `/altimate ` does): edit `plugins/altimate-code/commands/altimate.md`. +- **Explicit-invocation UX** (what `/altimate-code:altimate ` does): edit `plugins/altimate-code/commands/altimate.md`. - **CLI invocation details** (agent selection, flags, follow-up handling): edit the workflow section in `plugins/altimate-code/skills/altimate-code/SKILL.md`. ## Frontmatter — YAML gotcha @@ -79,7 +79,7 @@ claude plugin install altimate-code@altimate-claude-plugin - **Skill** — `plugins/altimate-code/skills/altimate-code/SKILL.md` — the delegation logic (`altimate-code run "$USER_TASK"` and surface the result). - **Hook** — `plugins/altimate-code/hooks/hooks.json` + `plugins/altimate-code/hooks-handlers/session-start.sh` — SessionStart hook that describes the plugin's capabilities in the system prompt so Claude can route to it when the task shape fits. -- **Command** — `plugins/altimate-code/commands/altimate.md` — `/altimate` slash command for explicit delegation with agent-persona selection. +- **Command** — `plugins/altimate-code/commands/altimate.md` — `/altimate-code:altimate` slash command for explicit delegation with agent-persona selection. ## Reporting bugs / requesting features diff --git a/PRIVACY.md b/PRIVACY.md index 39247b9..47d28c0 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -18,7 +18,7 @@ This policy supplements the Altimate AI [Privacy Policy](https://www.altimate.ai The plugin contains no executable service of its own. Its only runtime behavior is a SessionStart hook that prints a fixed, static text block describing the skill's capabilities. It does not read your files, does not phone home, and does not collect analytics. -Data leaves Claude Code's process only when the delegation skill or the `/altimate` command fires and invokes the locally installed altimate-code CLI. +Data leaves Claude Code's process only when the delegation skill or the `/altimate-code:altimate` command fires and invokes the locally installed altimate-code CLI. ## Data flows when a task is delegated diff --git a/README.md b/README.md index 52a3f8e..8cdb50d 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,14 @@ Currently ships one plugin: **[altimate-code](./plugins/altimate-code/)** — de ## Install +From Anthropic's plugin directory: + +```bash +claude plugin install altimate-code +``` + +Or from this marketplace: + ``` /plugin marketplace add AltimateAI/altimate-claude-plugin /plugin install altimate-code@altimate-claude-plugin diff --git a/plugins/altimate-code/.claude-plugin/plugin.json b/plugins/altimate-code/.claude-plugin/plugin.json index ba2b6d7..560f79e 100644 --- a/plugins/altimate-code/.claude-plugin/plugin.json +++ b/plugins/altimate-code/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "altimate-code", "displayName": "Altimate Code", - "version": "1.0.0", - "description": "Delegates dbt and warehouse work to altimate-code, a specialized CLI agent with 100+ purpose-built data tools (SQL analysis, column-level lineage, dbt build/test/run, warehouse profiling, FinOps, connectivity to Snowflake, BigQuery, Redshift, Databricks, Postgres, MySQL, DuckDB).", + "version": "1.1.0", + "description": "Delegates dbt and warehouse work to altimate-code, a specialized CLI agent with 100+ purpose-built data tools (SQL analysis, column-level lineage, dbt build/test/run, warehouse profiling, FinOps, connectivity to Snowflake, BigQuery, Redshift, Databricks, Postgres, MySQL, DuckDB), and to the skills, knowledge and memory of a linked Altimate workspace.", "author": { "name": "AltimateAI", "url": "https://altimate.ai" diff --git a/plugins/altimate-code/CHANGELOG.md b/plugins/altimate-code/CHANGELOG.md index 51abc76..48f830f 100644 --- a/plugins/altimate-code/CHANGELOG.md +++ b/plugins/altimate-code/CHANGELOG.md @@ -2,6 +2,20 @@ All notable changes to this plugin will be documented in this file. +## [1.1.0] — 2026-10-19 + +### Fixed +- Delegated runs no longer hang. Claude Code's shell leaves stdin open and `altimate-code run` reads piped stdin as part of the task, so the run waited forever before it started. Every invocation now redirects stdin from `/dev/null`. +- The skill and `/altimate-code:altimate` no longer pass `--agent fast-edit`. altimate-code has no such agent, so every run fell back to `builder` with a warning. Runs now ask for `builder` directly. +- The output file is created with `mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX"`. On macOS, `mktemp -t altimate-result.XXXXXX.md` left the `X`s in the name. + +### Added +- Altimate workspaces: the skill, `/altimate-code:altimate` and the SessionStart context say that a linked project's runs use the workspace's skills, knowledge and memory, route questions about the team's own conventions and knowledge to altimate-code, and tell the user how to sign in and link. +- README: "Use an Altimate workspace" setup, and the install command for Anthropic's plugin directory. + +### Changed +- Docs name the command `/altimate-code:altimate`, as Claude Code lists it. Claude Code namespaces plugin commands, so a bare `/altimate` answers "Unknown command". + ## [1.0.0] — 2026-07-09 ### Added diff --git a/plugins/altimate-code/README.md b/plugins/altimate-code/README.md index 35ee013..39cd112 100644 --- a/plugins/altimate-code/README.md +++ b/plugins/altimate-code/README.md @@ -6,6 +6,14 @@ Routes dbt + warehouse tasks from Claude Code to [altimate-code](https://github. ## Install +From Anthropic's plugin directory: + +```bash +claude plugin install altimate-code +``` + +Or from this repository's marketplace: + ``` /plugin marketplace add AltimateAI/altimate-claude-plugin /plugin install altimate-code@altimate-claude-plugin @@ -27,13 +35,26 @@ If altimate-code is not on PATH or not configured, the plugin surfaces the failu ## How it works 1. A **SessionStart hook** adds a static description of altimate-code's capabilities to the session, so Claude Code knows when a task fits. -2. When a data-engineering task fires the **skill** (or you invoke **`/altimate `** explicitly), Claude Code runs `altimate-code run ""` locally, selecting the cheapest suitable agent persona (`fast-edit` for dbt/SQL edits, `analyst` for aggregation-heavy correctness work, `builder` for warehouse-state investigation). +2. When a data-engineering task fires the **skill** (or you invoke **`/altimate-code:altimate `** explicitly), Claude Code runs `altimate-code run ""` locally with its `builder` agent. 3. altimate-code plans and executes the task using your configured LLM provider. Warehouse queries, dbt commands, and file edits run **locally under your credentials**. 4. The result is written to a local output file and surfaced back in your Claude Code conversation. +## Use an Altimate workspace + +An [Altimate workspace](https://help.altimate.ai/workspaces/) holds your team's shared skills, knowledge, memory and warehouse integrations. Claude Code reaches it through altimate-code: every task the plugin hands over runs in your project, so it uses the workspace the project is linked to. Nothing in Claude Code needs configuring. + +1. **Sign in to Altimate** — `altimate-code auth login -p altimate-backend`, then choose **Altimate LLM Gateway**. It opens your browser. This also sets up the model provider altimate-code uses. +2. **Link the project** — run `altimate-code link` in the project folder and pick the workspace, or create one. From a script, use `altimate-code link --workspace ` or `altimate-code link --create`. +3. **Check it** — `altimate-code workspace status` shows the linked workspace and its page in the Altimate web app. +4. **Ask Claude** — questions about your team's conventions, standards or knowledge go to altimate-code, which answers from the workspace. Start a request with `/altimate-code:altimate` to be sure it does: *"/altimate-code:altimate what are our naming conventions for staging models?"* + +What altimate-code learns during these tasks is saved to the workspace's memory and shared with your team in the CLI, the IDE and Studio. Skills added to the workspace reach the next task. + +In Claude Code you can run the sign-in and link commands without leaving the session by prefixing them with `!`, for example `! altimate-code link`. + ## Example prompts -Once installed, try these in Claude Code (or prefix any of them with `/altimate`): +Once installed, try these in Claude Code (or prefix any of them with `/altimate-code:altimate`): 1. **Column-level lineage** — *"Trace the `revenue_usd` column in `models/marts/fct_revenue.sql` back to its sources, and list every downstream model that would be affected if I change its rounding."* 2. **Warehouse cost analysis** — *"Give me a cost report for our Snowflake account: the ten most expensive queries this month and any warehouses that look over-provisioned."* @@ -55,6 +76,8 @@ Full details: **[PRIVACY.md](../../PRIVACY.md)** · Security policy and disclosu | Task hangs for several minutes | Open `altimate-code` to check for a pending prompt in the TUI, or re-run specifying a known-good model. | | Empty result | The task may be too ambiguous — restate with the target table, expected columns, or time window. | | `UNKNOWN_USER` / `Database does not exist` mid-run | The CLI connects but your warehouse credentials don't match this project — reconfigure warehouse auth in the `altimate-code` TUI or `profiles.yml`. | +| `Not signed in to Altimate` | Run `altimate-code auth login -p altimate-backend` and choose Altimate LLM Gateway. | +| Answers ignore your workspace's skills or knowledge | Run `altimate-code workspace status` in the project. If it isn't linked, run `altimate-code link`. | | Plugin installed but never delegates | Confirm it's enabled: `claude plugin enable altimate-code@altimate-claude-plugin`. | Still stuck? See [Support](#support). @@ -62,7 +85,7 @@ Still stuck? See [Support](#support). ## Components - **Skill** — `skills/altimate-code/SKILL.md` — delegation logic and agent-persona selection -- **Command** — `commands/altimate.md` — `/altimate` slash command for explicit delegation +- **Command** — `commands/altimate.md` — `/altimate-code:altimate` slash command for explicit delegation - **Hook** — `hooks/hooks.json` — SessionStart capability description (static text only) ## Support diff --git a/plugins/altimate-code/commands/altimate.md b/plugins/altimate-code/commands/altimate.md index ee80180..3d9b4b5 100644 --- a/plugins/altimate-code/commands/altimate.md +++ b/plugins/altimate-code/commands/altimate.md @@ -1,9 +1,9 @@ --- -description: Delegate a task to altimate-code, the specialised data-engineering CLI agent (warehouse access, column-level lineage, cross-DB, FinOps, query optimization) +description: Delegate a task to altimate-code, the specialised data-engineering CLI agent (warehouse access, column-level lineage, cross-DB, FinOps, query optimization, your Altimate workspace's skills and knowledge) argument-hint: --- -The user explicitly invoked `/altimate` to delegate this task to altimate-code. You MUST run the task via the `altimate-code` CLI — do NOT attempt the work with native `Bash`/`Edit`/`Write` tools. +The user explicitly invoked `/altimate-code:altimate` to delegate this task to altimate-code. You MUST run the task via the `altimate-code` CLI — do NOT attempt the work with native `Bash`/`Edit`/`Write` tools, and do not read the project's files first: altimate-code investigates the project itself. Workflow (follow in order, no skipping): @@ -12,39 +12,33 @@ Workflow (follow in order, no skipping): command -v altimate-code ``` If it returns nothing, stop and tell the user: - > altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+), then run `altimate-code` once to configure your provider/warehouse auth, then re-run `/altimate `. + > altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+), then run `altimate-code` once to configure your provider/warehouse auth, then re-run `/altimate-code:altimate `. -2. **Pick the agent persona** based on the user's task shape. Start cheap and escalate on failure — fast-edit handles most dbt/SQL work at 10–20× lower cost than builder. +2. **Vague debug** ("X is broken") with no failure named: **stop — ask the user for the specific error before delegating.** - | Task shape | Use `--agent` | - |---|---| - | Any dbt / SQL task (rename, refactor, create, debug, structural) | `fast-edit` (default) | - | Aggregation correctness on multi-table joins | `analyst` if fast-edit fails the user's verification | - | Warehouse-state work (lineage, cost, parity, schema diff, PII, FinOps) | `builder` | - | Vague debug ("X is broken") | **Stop — ask the user for the specific error before delegating.** | - - Decision rule: start with `fast-edit`. Only use `analyst` / `builder` when the cheap path fails for a documented reason. - -3. **Run altimate-code with the chosen agent.** Pass `$ARGUMENTS` through a +3. **Run altimate-code with the `builder` agent**, which has the warehouse tools, workspace skills and memory. Pass `$ARGUMENTS` through a here-doc into a variable so the shell never command-substitutes anything the - user typed, and write the result to a private `mktemp` file (not a shared + user typed, write the result to a private `mktemp` file (not a shared `/tmp/altimate-result.md` — concurrent invocations clobber each other and a - world-readable fixed path leaks warehouse rows or PII): + world-readable fixed path leaks warehouse rows or PII), and redirect stdin + from `/dev/null` (`altimate-code run` reads piped stdin as part of the task, + and this shell leaves stdin open): ```bash TASK="$(cat <<'ALTIMATE_TASK' $ARGUMENTS ALTIMATE_TASK )" umask 077 - OUTPUT_FILE="$(mktemp -t altimate-result.XXXXXX.md)" + OUTPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX")" altimate-code run "$TASK" \ - --agent \ + --agent builder \ --yolo \ --output "$OUTPUT_FILE" \ - --dir "$(pwd)" + --dir "$(pwd)" \ + < /dev/null ``` - **If this is a follow-up task in the same project** (the user invoked `/altimate` already in this conversation about the same dbt project / warehouse / data context), add `--continue` to resume the warm session — cache is hot, follow-on cost is materially lower: + **If this is a follow-up task in the same project** (the user invoked `/altimate-code:altimate` already in this conversation about the same dbt project / warehouse / data context), add `--continue` to resume the warm session — cache is hot, follow-on cost is materially lower: ```bash TASK="$(cat <<'ALTIMATE_TASK' @@ -52,17 +46,20 @@ Workflow (follow in order, no skipping): ALTIMATE_TASK )" umask 077 - OUTPUT_FILE="$(mktemp -t altimate-result.XXXXXX.md)" + OUTPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX")" altimate-code run "$TASK" \ - --agent \ + --agent builder \ --yolo --output "$OUTPUT_FILE" --dir "$(pwd)" \ - --continue + --continue \ + < /dev/null ``` - Skip `--continue` if the user switched projects, switched debugging threads, or this is the first `/altimate` invocation in the conversation. + Skip `--continue` if the user switched projects, switched debugging threads, or this is the first `/altimate-code:altimate` invocation in the conversation. + + If the project is linked to an Altimate workspace, altimate-code uses its skills, knowledge and memory automatically. There is nothing to pass. 4. **Surface the result verbatim:** read `"$OUTPUT_FILE"` and present its contents to the user without re-summarising, re-formatting, or commenting. altimate-code has already produced the answer. Delete `"$OUTPUT_FILE"` after presenting so warehouse rows, lineage, or PII findings don't linger on disk. -5. **On any altimate-code error** (`Unauthorized`, `Token limit reached`, `No provider configured`, warehouse credentials wrong, process timeout) — surface the error message to the user along with the fix from the skill body's failure-modes table. Do NOT fall back to native tools. The user invoked `/altimate` specifically to use altimate-code; falling back would defeat the purpose. +5. **On any altimate-code error** (`Unauthorized`, `Token limit reached`, `No provider configured`, `Not signed in to Altimate`, warehouse credentials wrong, process timeout) — surface the error message to the user along with the fix from the skill body's failure-modes table. Do NOT fall back to native tools. The user invoked `/altimate-code:altimate` specifically to use altimate-code; falling back would defeat the purpose. Task to delegate: $ARGUMENTS diff --git a/plugins/altimate-code/hooks-handlers/session-start.sh b/plugins/altimate-code/hooks-handlers/session-start.sh index eae5dce..dd883a7 100755 --- a/plugins/altimate-code/hooks-handlers/session-start.sh +++ b/plugins/altimate-code/hooks-handlers/session-start.sh @@ -11,6 +11,6 @@ printf '%s\n' '{' printf ' "hookSpecificOutput": {\n' printf ' "hookEventName": "SessionStart",\n' -printf ' "additionalContext": "The altimate-code plugin ships two skills in this session. (1) The `altimate-code` skill routes data-engineering work to the altimate-code CLI — column-level lineage, downstream-impact, cross-database validation, FinOps, PII from sampled rows, query cost attribution, schema diffs, dev-vs-prod diffing. It is not well-suited for pure file/code edits to dbt models and SQL files that do not touch warehouse state — native Bash/Edit/Write handles those faster. (2) The `review` skill runs the altimate-code dbt PR reviewer on dbt project changes (models/**.sql, schema.yml, dbt_project.yml, sources.yml, macros, snapshots, seeds). It emits a signed verdict envelope with column lineage, query equivalence, dbt anti-pattern detection, and PII screening — none of which native tools or a generic code-review skill can compute. When the user asks to review dbt / SQL / warehouse changes, this is the specialized reviewer available. For non-dbt code review (TypeScript, Python, Go), the `review` skill declines."\n' +printf ' "additionalContext": "The altimate-code plugin ships two skills in this session. (1) The `altimate-code` skill routes data-engineering work to the altimate-code CLI — column-level lineage, downstream-impact, cross-database validation, FinOps, PII from sampled rows, query cost attribution, schema diffs, dev-vs-prod diffing. In a project linked to an Altimate workspace it also answers from the shared skills, knowledge and memory of that workspace, so questions about team conventions, standards or best practices fit it too. It is not well-suited for pure file/code edits to dbt models and SQL files that do not touch warehouse state — native Bash/Edit/Write handles those faster. (2) The `review` skill runs the altimate-code dbt PR reviewer on dbt project changes (models/**.sql, schema.yml, dbt_project.yml, sources.yml, macros, snapshots, seeds). It emits a signed verdict envelope with column lineage, query equivalence, dbt anti-pattern detection, and PII screening — none of which native tools or a generic code-review skill can compute. When the user asks to review dbt / SQL / warehouse changes, this is the specialized reviewer available. For non-dbt code review (TypeScript, Python, Go), the `review` skill declines."\n' printf ' }\n' printf '}\n' diff --git a/plugins/altimate-code/skills/altimate-code/SKILL.md b/plugins/altimate-code/skills/altimate-code/SKILL.md index 9fa80ec..1c0dc2e 100644 --- a/plugins/altimate-code/skills/altimate-code/SKILL.md +++ b/plugins/altimate-code/skills/altimate-code/SKILL.md @@ -10,9 +10,14 @@ description: >- from sampled rows, incremental/SCD2/backfill verification, FinOps reporting, model documentation generation, query optimization, anomaly detection, dev-vs-prod diffing, or tasks where the user names altimate-code - or the data agent by name. The skill routes to a purpose-built CLI, so it - covers workloads that touch live data, lineage, or warehouse state more - directly than native file-editing tools do. + or the data agent by name. Also suited for questions about the team's own + data conventions, standards, best practices, knowledge base or shared + memory, and for anything the user calls their Altimate workspace: in a + project linked to an Altimate workspace, altimate-code answers from that + workspace's skills, knowledge and memory, which native tools cannot read. + The skill routes to a purpose-built CLI, so it covers workloads that touch + live data, lineage, warehouse state or team knowledge more directly than + native file-editing tools do. --- # altimate-code @@ -27,22 +32,11 @@ altimate-code is a CLI AI agent with 100+ purpose-built data engineering tools. Do not attempt the work with Edit/Write/Bash yourself, even if it looks simple. The whole point of this skill is to route data-engineering work to the agent that's built for it. If you find yourself reaching for Edit or Write while this skill is active, stop and re-read this paragraph. -## Invocation — pick the right agent for the task +## Invocation -altimate-code has multiple agent personas. The default (`builder`) does a full project discovery sweep on every call — fine for warehouse-state work but ~10–20× more expensive than necessary on simple file edits. **Pick the agent based on task shape before invoking.** +**Vague debug** ("X is broken", "make it work", "fix this") with no failure named: **don't delegate yet.** Ask the user for the specific error message or symptom first. -### Step 1 — classify the task - -| Shape | Examples | Use | -|---|---|---| -| **Any dbt / SQL task** (rename, refactor, create model, debug, structural reorg, multi-step setup) | the vast majority of customer requests | `fast-edit` — try this first | -| **Multi-table aggregation correctness** | new model joining 3+ tables with `count(*)` / `sum() over (...)` / "first X, last X" logic that must be exactly right | `analyst` if `fast-edit` fails the user's verification | -| **Warehouse-state work** | column-level lineage, downstream-impact, cross-DB migration / parity, query cost attribution against a real warehouse, schema diff between environments, PII detection, FinOps reporting | `builder` (default — has warehouse tools enabled) | -| **Vague debug** ("X is broken", "make it work", "fix this") | unspecified failure mode | **Don't delegate yet.** Ask the user for the specific error message or symptom before invoking any agent — empirically all three agents fail vague debug prompts at ~700K tokens each. | - -**Decision policy:** start with `fast-edit` for any dbt/SQL task. If the user reports the result is wrong (e.g. aggregation values don't match), retry with `analyst`. Only use `builder` when the task genuinely needs the warehouse-investigation tools (it's 10–20× more expensive than fast-edit and rarely required). - -### Step 2 — invoke with the chosen agent +Otherwise, run the task with the `builder` agent. It has the warehouse tools, loads the linked workspace's skills and saves to its memory. Pass the task through a here-doc into a variable so the shell never command-substitutes anything the user typed (a task like @@ -56,12 +50,13 @@ TASK="$(cat <<'ALTIMATE_TASK' ALTIMATE_TASK )" umask 077 -OUTPUT_FILE="$(mktemp -t altimate-result.XXXXXX.md)" +OUTPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX")" altimate-code run "$TASK" \ - --agent \ + --agent builder \ --yolo \ --output "$OUTPUT_FILE" \ - --dir "$(pwd)" + --dir "$(pwd)" \ + < /dev/null ``` Then `Read "$OUTPUT_FILE"` and emit its contents to the user without re-summarising, re-formatting, or commenting on the result. altimate-code has already produced the answer. Delete `"$OUTPUT_FILE"` after presenting so warehouse rows, lineage, or PII findings don't linger on disk. @@ -70,10 +65,11 @@ Then `Read "$OUTPUT_FILE"` and emit its contents to the user without re-summaris | Flag | Why it is required | |---|---| -| `--agent ` | Picks the agent persona. Default `builder` is overkill for simple edits — see the classification table above. Wrong agent = either 10× too expensive (using `builder` on a rename) or wrong-answer (using `fast-edit` on a multi-table join). | +| `--agent builder` | The agent with the warehouse tools, workspace skills and memory. Other agents lack some of these. | | `--yolo` | Non-interactive mode. Without this the subprocess hangs on the first permission prompt and you will time out. | | `--output "$OUTPUT_FILE"` | Captures the final response. Use the private `mktemp` file from above — do NOT use a fixed path like `/tmp/altimate-result.md`; concurrent sessions clobber each other and a world-readable fixed path leaks data. | -| `--dir "$(pwd)"` | Runs altimate-code in the current project so it picks up dbt project config, profiles.yml, etc. | +| `--dir "$(pwd)"` | Runs altimate-code in the current project so it picks up dbt project config, profiles.yml, the linked workspace, etc. | +| `< /dev/null` | `altimate-code run` reads piped stdin as part of the task. The shell this runs in leaves stdin open, so without the redirect the run waits for input that never comes. | ### Follow-up tasks in the same project @@ -85,19 +81,33 @@ TASK="$(cat <<'ALTIMATE_TASK' ALTIMATE_TASK )" umask 077 -OUTPUT_FILE="$(mktemp -t altimate-result.XXXXXX.md)" +OUTPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX")" altimate-code run "$TASK" \ - --agent \ + --agent builder \ --yolo \ --output "$OUTPUT_FILE" \ --dir "$(pwd)" \ - --continue # resumes the most recent session in this dir + --continue \ + < /dev/null ``` -altimate-code's prompt cache is warm in a continued session — project structure, profiles.yml, schema index, source definitions don't need to be re-investigated. Cache reads are billed at a fraction of fresh input on altimate-gateway. The downside is zero: if there's no useful cached context for the new task, you pay normal cold cost. +`--continue` resumes the most recent session in this directory. altimate-code's prompt cache is warm in a continued session — project structure, profiles.yml, schema index, source definitions don't need to be re-investigated. Cache reads are billed at a fraction of fresh input on altimate-gateway. The downside is zero: if there's no useful cached context for the new task, you pay normal cold cost. If the user starts a clearly unrelated workflow (different project, different schema, different debugging thread), drop `--continue` and start fresh — the warm cache is irrelevant and you'd carry unrelated history into the prompt. +## Altimate workspaces + +A project can be linked to an Altimate workspace: the team's shared skills, knowledge, memory and warehouse integrations. Every `altimate-code run` in a linked project uses that workspace automatically — there is nothing to pass. That is why questions about the team's conventions, standards or knowledge belong to this skill. + +When the user asks about their workspace or wants to set one up: + +- **Check the link:** `altimate-code workspace status < /dev/null`. Exit code 3 means the project is not linked; 2 means the user is not signed in to Altimate. +- **Not signed in:** tell the user to run `! altimate-code auth login -p altimate-backend` in this session and choose **Altimate LLM Gateway**. It opens their browser to sign in. Do not try to sign in for them. +- **Not linked:** `altimate-code link` is interactive, so tell the user to run `! altimate-code link` in this session and pick the workspace. If they name the workspace, you can run `altimate-code link --workspace "" < /dev/null` instead; `altimate-code link --create < /dev/null` creates a new workspace named after the repository. +- **Open it in the browser:** `altimate-code workspace status` prints the workspace page's URL. + +What altimate-code learns during delegated tasks is saved to the workspace's memory and shared with the team in the CLI, the IDE and Studio. + ## Failure modes — route every one to the user When altimate-code returns an error, **report the error to the user and STOP**. Do not fall back to Bash, Edit, or Write. The skill's contract is "altimate-code handles this, or the user is told why it couldn't." @@ -105,7 +115,9 @@ When altimate-code returns an error, **report the error to the user and STOP**. | Symptom | What to tell the user — verbatim | |---|---| | `command not found: altimate-code` | "altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+) and run `altimate-code` once to configure auth. Then re-run your request." | -| `Unauthorized: Incorrect auth token` / `No provider configured` | "altimate-code's LLM provider auth is misconfigured. Run `altimate-code` in your terminal to open the TUI and reconfigure your provider, then re-run your request." | +| `Unauthorized: Incorrect auth token` / `No provider configured` | "altimate-code's LLM provider auth is misconfigured. Run `altimate-code` in your terminal to open the TUI and reconfigure your provider, or sign in to Altimate with `altimate-code auth login -p altimate-backend`, then re-run your request." | +| `Not signed in to Altimate` | "altimate-code is not signed in to Altimate, so it cannot reach your workspace. Run `! altimate-code auth login -p altimate-backend` and choose Altimate LLM Gateway, then re-run your request." | +| `memory was saved here but could not be sent to the workspace` (stderr) | Present the result as usual, then add: "altimate-code saved what it learned on this machine but could not send it to your workspace. Run `! altimate-code workspace sync` to send it." | | Process hangs >5 min | "altimate-code is unresponsive. Try `altimate-code` to inspect the TUI for an open prompt, or re-run with `--model anthropic/claude-sonnet-4-6` to force a known-good model." | | Output file empty | "altimate-code returned without producing output. The task may be too ambiguous — please restate with more detail (target table, expected columns, time window)." | | Warehouse error mid-run (`UNKNOWN_USER`, `Database does not exist`) | "altimate-code can connect but the warehouse credentials it has are wrong for this project. Configure provider/warehouse auth via `altimate-code` TUI." | From 13af34b909f80211116729bd15dcef1a36578004 Mon Sep 17 00:00:00 2001 From: Haider Date: Mon, 19 Oct 2026 02:19:31 +0530 Subject: [PATCH 2/5] fix: sign in and link from inside Claude Code Tested in an interactive Claude Code session: the advice to run `! altimate-code link` failed (its picker needs a TTY, and `!` gives none), and `! altimate-code auth login -p altimate-backend` waits at a method picker nobody can answer. - Sign-in advice adds `--method "Altimate LLM Gateway"` (supported by released altimate-code), which skips the picker. - Linking: the skill lists workspaces with `altimate-code workspace list`, lets the user choose, and runs `link --workspace`, or `link --create` for a new one. Falls back to asking for the name, or `altimate-code link` in a separate terminal, on a CLI without `workspace list`. - README and CHANGELOG to match. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011chv9Rmu7jQXokum1WNcs7 --- plugins/altimate-code/CHANGELOG.md | 3 ++- plugins/altimate-code/README.md | 10 ++++------ plugins/altimate-code/skills/altimate-code/SKILL.md | 6 +++--- 3 files changed, 9 insertions(+), 10 deletions(-) diff --git a/plugins/altimate-code/CHANGELOG.md b/plugins/altimate-code/CHANGELOG.md index 48f830f..d2cec1e 100644 --- a/plugins/altimate-code/CHANGELOG.md +++ b/plugins/altimate-code/CHANGELOG.md @@ -7,10 +7,11 @@ All notable changes to this plugin will be documented in this file. ### Fixed - Delegated runs no longer hang. Claude Code's shell leaves stdin open and `altimate-code run` reads piped stdin as part of the task, so the run waited forever before it started. Every invocation now redirects stdin from `/dev/null`. - The skill and `/altimate-code:altimate` no longer pass `--agent fast-edit`. altimate-code has no such agent, so every run fell back to `builder` with a warning. Runs now ask for `builder` directly. +- Sign-in advice uses `altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`. Without `--method`, `auth login` waits at a menu that Claude Code's `!` prompt cannot answer. - The output file is created with `mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX"`. On macOS, `mktemp -t altimate-result.XXXXXX.md` left the `X`s in the name. ### Added -- Altimate workspaces: the skill, `/altimate-code:altimate` and the SessionStart context say that a linked project's runs use the workspace's skills, knowledge and memory, route questions about the team's own conventions and knowledge to altimate-code, and tell the user how to sign in and link. +- Altimate workspaces: the skill, `/altimate-code:altimate` and the SessionStart context say that a linked project's runs use the workspace's skills, knowledge and memory, route questions about the team's own conventions and knowledge to altimate-code, and tell the user how to sign in and link. Linking from Claude Code lists the workspaces with `altimate-code workspace list` (in altimate-code releases that have it) and links the chosen one with `link --workspace`, because the `link` picker needs a terminal that `!` does not provide. - README: "Use an Altimate workspace" setup, and the install command for Anthropic's plugin directory. ### Changed diff --git a/plugins/altimate-code/README.md b/plugins/altimate-code/README.md index 39cd112..f5f3229 100644 --- a/plugins/altimate-code/README.md +++ b/plugins/altimate-code/README.md @@ -43,15 +43,13 @@ If altimate-code is not on PATH or not configured, the plugin surfaces the failu An [Altimate workspace](https://help.altimate.ai/workspaces/) holds your team's shared skills, knowledge, memory and warehouse integrations. Claude Code reaches it through altimate-code: every task the plugin hands over runs in your project, so it uses the workspace the project is linked to. Nothing in Claude Code needs configuring. -1. **Sign in to Altimate** — `altimate-code auth login -p altimate-backend`, then choose **Altimate LLM Gateway**. It opens your browser. This also sets up the model provider altimate-code uses. -2. **Link the project** — run `altimate-code link` in the project folder and pick the workspace, or create one. From a script, use `altimate-code link --workspace ` or `altimate-code link --create`. +1. **Sign in to Altimate** — `altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`. It opens your browser. This also sets up the model provider altimate-code uses. You can run it from Claude Code by typing it after `!`. +2. **Link the project** — ask Claude to link the project to your workspace. It lists your workspaces with `altimate-code workspace list` and links the one you choose with `altimate-code link --workspace `, or creates one with `altimate-code link --create`. In a terminal, `altimate-code link` does the same with a picker; the picker does not work after `!` in Claude Code. 3. **Check it** — `altimate-code workspace status` shows the linked workspace and its page in the Altimate web app. 4. **Ask Claude** — questions about your team's conventions, standards or knowledge go to altimate-code, which answers from the workspace. Start a request with `/altimate-code:altimate` to be sure it does: *"/altimate-code:altimate what are our naming conventions for staging models?"* What altimate-code learns during these tasks is saved to the workspace's memory and shared with your team in the CLI, the IDE and Studio. Skills added to the workspace reach the next task. -In Claude Code you can run the sign-in and link commands without leaving the session by prefixing them with `!`, for example `! altimate-code link`. - ## Example prompts Once installed, try these in Claude Code (or prefix any of them with `/altimate-code:altimate`): @@ -76,8 +74,8 @@ Full details: **[PRIVACY.md](../../PRIVACY.md)** · Security policy and disclosu | Task hangs for several minutes | Open `altimate-code` to check for a pending prompt in the TUI, or re-run specifying a known-good model. | | Empty result | The task may be too ambiguous — restate with the target table, expected columns, or time window. | | `UNKNOWN_USER` / `Database does not exist` mid-run | The CLI connects but your warehouse credentials don't match this project — reconfigure warehouse auth in the `altimate-code` TUI or `profiles.yml`. | -| `Not signed in to Altimate` | Run `altimate-code auth login -p altimate-backend` and choose Altimate LLM Gateway. | -| Answers ignore your workspace's skills or knowledge | Run `altimate-code workspace status` in the project. If it isn't linked, run `altimate-code link`. | +| `Not signed in to Altimate` | Run `altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`. | +| Answers ignore your workspace's skills or knowledge | Run `altimate-code workspace status` in the project. If it isn't linked, ask Claude to link it, or run `altimate-code link` in a terminal. | | Plugin installed but never delegates | Confirm it's enabled: `claude plugin enable altimate-code@altimate-claude-plugin`. | Still stuck? See [Support](#support). diff --git a/plugins/altimate-code/skills/altimate-code/SKILL.md b/plugins/altimate-code/skills/altimate-code/SKILL.md index 1c0dc2e..6fd59b5 100644 --- a/plugins/altimate-code/skills/altimate-code/SKILL.md +++ b/plugins/altimate-code/skills/altimate-code/SKILL.md @@ -102,8 +102,8 @@ A project can be linked to an Altimate workspace: the team's shared skills, know When the user asks about their workspace or wants to set one up: - **Check the link:** `altimate-code workspace status < /dev/null`. Exit code 3 means the project is not linked; 2 means the user is not signed in to Altimate. -- **Not signed in:** tell the user to run `! altimate-code auth login -p altimate-backend` in this session and choose **Altimate LLM Gateway**. It opens their browser to sign in. Do not try to sign in for them. -- **Not linked:** `altimate-code link` is interactive, so tell the user to run `! altimate-code link` in this session and pick the workspace. If they name the workspace, you can run `altimate-code link --workspace "" < /dev/null` instead; `altimate-code link --create < /dev/null` creates a new workspace named after the repository. +- **Not signed in:** tell the user to run `! altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"` in this session. It opens their browser to sign in. Do not try to sign in for them. Keep the `--method` flag: without it the command waits at a menu that cannot be answered from this session. +- **Not linked:** do not suggest `! altimate-code link`: its picker needs a terminal, and this session does not give it one. Instead run `altimate-code workspace list < /dev/null`, show the user the workspaces it prints, and once they choose, run `altimate-code link --workspace "" < /dev/null`. If they want a new workspace, run `altimate-code link --create < /dev/null`, which names it after the repository. If `workspace list` is an unknown command (an older altimate-code), ask the user for the workspace's name, or tell them to run `altimate-code link` in a separate terminal. - **Open it in the browser:** `altimate-code workspace status` prints the workspace page's URL. What altimate-code learns during delegated tasks is saved to the workspace's memory and shared with the team in the CLI, the IDE and Studio. @@ -116,7 +116,7 @@ When altimate-code returns an error, **report the error to the user and STOP**. |---|---| | `command not found: altimate-code` | "altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+) and run `altimate-code` once to configure auth. Then re-run your request." | | `Unauthorized: Incorrect auth token` / `No provider configured` | "altimate-code's LLM provider auth is misconfigured. Run `altimate-code` in your terminal to open the TUI and reconfigure your provider, or sign in to Altimate with `altimate-code auth login -p altimate-backend`, then re-run your request." | -| `Not signed in to Altimate` | "altimate-code is not signed in to Altimate, so it cannot reach your workspace. Run `! altimate-code auth login -p altimate-backend` and choose Altimate LLM Gateway, then re-run your request." | +| `Not signed in to Altimate` | "altimate-code is not signed in to Altimate, so it cannot reach your workspace. Run `! altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`, sign in in the browser, then re-run your request." | | `memory was saved here but could not be sent to the workspace` (stderr) | Present the result as usual, then add: "altimate-code saved what it learned on this machine but could not send it to your workspace. Run `! altimate-code workspace sync` to send it." | | Process hangs >5 min | "altimate-code is unresponsive. Try `altimate-code` to inspect the TUI for an open prompt, or re-run with `--model anthropic/claude-sonnet-4-6` to force a known-good model." | | Output file empty | "altimate-code returned without producing output. The task may be too ambiguous — please restate with more detail (target table, expected columns, time window)." | From bebecf5c32f86723701efcfc7cb23dff0c6b23d7 Mon Sep 17 00:00:00 2001 From: Haider Date: Mon, 19 Oct 2026 02:25:50 +0530 Subject: [PATCH 3/5] docs: drop agent-persona wording; `--method` in the provider-auth row Review follow-ups: the skill and command no longer choose an agent, and the provider-auth failure row now prints the sign-in command that works from Claude Code's `!` prompt. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011chv9Rmu7jQXokum1WNcs7 --- CONTRIBUTING.md | 2 +- plugins/altimate-code/README.md | 2 +- plugins/altimate-code/skills/altimate-code/SKILL.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 647b164..6330447 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,7 +79,7 @@ claude plugin install altimate-code@altimate-claude-plugin - **Skill** — `plugins/altimate-code/skills/altimate-code/SKILL.md` — the delegation logic (`altimate-code run "$USER_TASK"` and surface the result). - **Hook** — `plugins/altimate-code/hooks/hooks.json` + `plugins/altimate-code/hooks-handlers/session-start.sh` — SessionStart hook that describes the plugin's capabilities in the system prompt so Claude can route to it when the task shape fits. -- **Command** — `plugins/altimate-code/commands/altimate.md` — `/altimate-code:altimate` slash command for explicit delegation with agent-persona selection. +- **Command** — `plugins/altimate-code/commands/altimate.md` — `/altimate-code:altimate` slash command for explicit delegation. ## Reporting bugs / requesting features diff --git a/plugins/altimate-code/README.md b/plugins/altimate-code/README.md index f5f3229..1328a76 100644 --- a/plugins/altimate-code/README.md +++ b/plugins/altimate-code/README.md @@ -82,7 +82,7 @@ Still stuck? See [Support](#support). ## Components -- **Skill** — `skills/altimate-code/SKILL.md` — delegation logic and agent-persona selection +- **Skill** — `skills/altimate-code/SKILL.md` — delegation logic and workspace guidance - **Command** — `commands/altimate.md` — `/altimate-code:altimate` slash command for explicit delegation - **Hook** — `hooks/hooks.json` — SessionStart capability description (static text only) diff --git a/plugins/altimate-code/skills/altimate-code/SKILL.md b/plugins/altimate-code/skills/altimate-code/SKILL.md index 6fd59b5..180e206 100644 --- a/plugins/altimate-code/skills/altimate-code/SKILL.md +++ b/plugins/altimate-code/skills/altimate-code/SKILL.md @@ -115,7 +115,7 @@ When altimate-code returns an error, **report the error to the user and STOP**. | Symptom | What to tell the user — verbatim | |---|---| | `command not found: altimate-code` | "altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+) and run `altimate-code` once to configure auth. Then re-run your request." | -| `Unauthorized: Incorrect auth token` / `No provider configured` | "altimate-code's LLM provider auth is misconfigured. Run `altimate-code` in your terminal to open the TUI and reconfigure your provider, or sign in to Altimate with `altimate-code auth login -p altimate-backend`, then re-run your request." | +| `Unauthorized: Incorrect auth token` / `No provider configured` | "altimate-code's LLM provider auth is misconfigured. Run `altimate-code` in your terminal to open the TUI and reconfigure your provider, or sign in to Altimate with `altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`, then re-run your request." | | `Not signed in to Altimate` | "altimate-code is not signed in to Altimate, so it cannot reach your workspace. Run `! altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`, sign in in the browser, then re-run your request." | | `memory was saved here but could not be sent to the workspace` (stderr) | Present the result as usual, then add: "altimate-code saved what it learned on this machine but could not send it to your workspace. Run `! altimate-code workspace sync` to send it." | | Process hangs >5 min | "altimate-code is unresponsive. Try `altimate-code` to inspect the TUI for an open prompt, or re-run with `--model anthropic/claude-sonnet-4-6` to force a known-good model." | From 033a2eea2c0194e855aa8e2c1526a8abd454d036 Mon Sep 17 00:00:00 2001 From: Haider Date: Mon, 19 Oct 2026 02:37:17 +0530 Subject: [PATCH 4/5] docs: match altimate-code's unsent-memory notice; re-link needs `--yes` Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011chv9Rmu7jQXokum1WNcs7 --- plugins/altimate-code/skills/altimate-code/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/altimate-code/skills/altimate-code/SKILL.md b/plugins/altimate-code/skills/altimate-code/SKILL.md index 180e206..b3f94be 100644 --- a/plugins/altimate-code/skills/altimate-code/SKILL.md +++ b/plugins/altimate-code/skills/altimate-code/SKILL.md @@ -103,7 +103,7 @@ When the user asks about their workspace or wants to set one up: - **Check the link:** `altimate-code workspace status < /dev/null`. Exit code 3 means the project is not linked; 2 means the user is not signed in to Altimate. - **Not signed in:** tell the user to run `! altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"` in this session. It opens their browser to sign in. Do not try to sign in for them. Keep the `--method` flag: without it the command waits at a menu that cannot be answered from this session. -- **Not linked:** do not suggest `! altimate-code link`: its picker needs a terminal, and this session does not give it one. Instead run `altimate-code workspace list < /dev/null`, show the user the workspaces it prints, and once they choose, run `altimate-code link --workspace "" < /dev/null`. If they want a new workspace, run `altimate-code link --create < /dev/null`, which names it after the repository. If `workspace list` is an unknown command (an older altimate-code), ask the user for the workspace's name, or tell them to run `altimate-code link` in a separate terminal. +- **Not linked:** do not suggest `! altimate-code link`: its picker needs a terminal, and this session does not give it one. Instead run `altimate-code workspace list < /dev/null`, show the user the workspaces it prints, and once they choose, run `altimate-code link --workspace "" < /dev/null`. If they want a new workspace, run `altimate-code link --create < /dev/null`, which names it after the repository. If the project is already linked to a different workspace, `link` refuses; confirm the move with the user, then re-run it with `--yes`. If `workspace list` is an unknown command (an older altimate-code), ask the user for the workspace's name, or tell them to run `altimate-code link` in a separate terminal. - **Open it in the browser:** `altimate-code workspace status` prints the workspace page's URL. What altimate-code learns during delegated tasks is saved to the workspace's memory and shared with the team in the CLI, the IDE and Studio. @@ -117,7 +117,7 @@ When altimate-code returns an error, **report the error to the user and STOP**. | `command not found: altimate-code` | "altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+) and run `altimate-code` once to configure auth. Then re-run your request." | | `Unauthorized: Incorrect auth token` / `No provider configured` | "altimate-code's LLM provider auth is misconfigured. Run `altimate-code` in your terminal to open the TUI and reconfigure your provider, or sign in to Altimate with `altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`, then re-run your request." | | `Not signed in to Altimate` | "altimate-code is not signed in to Altimate, so it cannot reach your workspace. Run `! altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`, sign in in the browser, then re-run your request." | -| `memory was saved here but could not be sent to the workspace` (stderr) | Present the result as usual, then add: "altimate-code saved what it learned on this machine but could not send it to your workspace. Run `! altimate-code workspace sync` to send it." | +| `not in the workspace yet` or `Could not confirm that the memory saved here reached the workspace` (stderr) | Present the result as usual, then add: "altimate-code saved what it learned on this machine, but it has not reached your workspace yet. Run `! altimate-code workspace sync` to send it." | | Process hangs >5 min | "altimate-code is unresponsive. Try `altimate-code` to inspect the TUI for an open prompt, or re-run with `--model anthropic/claude-sonnet-4-6` to force a known-good model." | | Output file empty | "altimate-code returned without producing output. The task may be too ambiguous — please restate with more detail (target table, expected columns, time window)." | | Warehouse error mid-run (`UNKNOWN_USER`, `Database does not exist`) | "altimate-code can connect but the warehouse credentials it has are wrong for this project. Configure provider/warehouse auth via `altimate-code` TUI." | From 6d26f1e3991aea5417da2b054897f62dbd3b5d81 Mon Sep 17 00:00:00 2001 From: Haider Date: Mon, 19 Oct 2026 04:48:49 +0530 Subject: [PATCH 5/5] fix: consensus review follow-ups MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - `/altimate-code:altimate` passes on altimate-code's unsent-memory notice, which the CLI writes to stderr, not the output file. - "Could not confirm…" maps to `workspace status`, not `workspace sync`. - `workspace status` exit codes: 0 linked, 3 not linked, 2 with "Not signed in" means sign in; anything else shows the CLI's message. - `link --create` on a name already taken: offer `--workspace`, or `--allow-duplicate` once the user confirms. - README: quote ``, re-link needs `--yes`, older CLIs have no `workspace list`. - Marketplace entry: description and version match plugin.json (1.1.0). - CHANGELOG scopes the stdin redirect to `run`; no nested double quotes in verbatim messages. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011chv9Rmu7jQXokum1WNcs7 --- .claude-plugin/marketplace.json | 4 ++-- plugins/altimate-code/CHANGELOG.md | 2 +- plugins/altimate-code/README.md | 2 +- plugins/altimate-code/commands/altimate.md | 2 +- plugins/altimate-code/skills/altimate-code/SKILL.md | 11 ++++++----- 5 files changed, 11 insertions(+), 10 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 36550af..ec7662c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,12 +7,12 @@ }, "metadata": { "description": "Altimate's Claude Code plugin — delegates dbt and warehouse work to the altimate-code CLI agent.", - "version": "1.0.0" + "version": "1.1.0" }, "plugins": [ { "name": "altimate-code", - "description": "Delegates dbt and warehouse work to altimate-code, a specialized CLI agent with 100+ purpose-built data tools (SQL analysis, column-level lineage, dbt build/test/run, warehouse profiling, FinOps, connectivity to Snowflake, BigQuery, Redshift, Databricks, Postgres, MySQL, DuckDB).", + "description": "Delegates dbt and warehouse work to altimate-code, a specialized CLI agent with 100+ purpose-built data tools (SQL analysis, column-level lineage, dbt build/test/run, warehouse profiling, FinOps, connectivity to Snowflake, BigQuery, Redshift, Databricks, Postgres, MySQL, DuckDB), and to the skills, knowledge and memory of a linked Altimate workspace.", "source": "./plugins/altimate-code", "strict": false } diff --git a/plugins/altimate-code/CHANGELOG.md b/plugins/altimate-code/CHANGELOG.md index d2cec1e..b072262 100644 --- a/plugins/altimate-code/CHANGELOG.md +++ b/plugins/altimate-code/CHANGELOG.md @@ -5,7 +5,7 @@ All notable changes to this plugin will be documented in this file. ## [1.1.0] — 2026-10-19 ### Fixed -- Delegated runs no longer hang. Claude Code's shell leaves stdin open and `altimate-code run` reads piped stdin as part of the task, so the run waited forever before it started. Every invocation now redirects stdin from `/dev/null`. +- Delegated runs no longer hang. Claude Code's shell leaves stdin open and `altimate-code run` reads piped stdin as part of the task, so the run waited forever before it started. Every `altimate-code run` invocation now redirects stdin from `/dev/null`. - The skill and `/altimate-code:altimate` no longer pass `--agent fast-edit`. altimate-code has no such agent, so every run fell back to `builder` with a warning. Runs now ask for `builder` directly. - Sign-in advice uses `altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`. Without `--method`, `auth login` waits at a menu that Claude Code's `!` prompt cannot answer. - The output file is created with `mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX"`. On macOS, `mktemp -t altimate-result.XXXXXX.md` left the `X`s in the name. diff --git a/plugins/altimate-code/README.md b/plugins/altimate-code/README.md index 1328a76..09e2294 100644 --- a/plugins/altimate-code/README.md +++ b/plugins/altimate-code/README.md @@ -44,7 +44,7 @@ If altimate-code is not on PATH or not configured, the plugin surfaces the failu An [Altimate workspace](https://help.altimate.ai/workspaces/) holds your team's shared skills, knowledge, memory and warehouse integrations. Claude Code reaches it through altimate-code: every task the plugin hands over runs in your project, so it uses the workspace the project is linked to. Nothing in Claude Code needs configuring. 1. **Sign in to Altimate** — `altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`. It opens your browser. This also sets up the model provider altimate-code uses. You can run it from Claude Code by typing it after `!`. -2. **Link the project** — ask Claude to link the project to your workspace. It lists your workspaces with `altimate-code workspace list` and links the one you choose with `altimate-code link --workspace `, or creates one with `altimate-code link --create`. In a terminal, `altimate-code link` does the same with a picker; the picker does not work after `!` in Claude Code. +2. **Link the project** — ask Claude to link the project to your workspace. It lists your workspaces with `altimate-code workspace list` and links the one you choose with `altimate-code link --workspace ""`, or creates one with `altimate-code link --create`. Moving a linked project to a different workspace also needs `--yes`. `workspace list` is in newer altimate-code releases; with an older one, tell Claude the workspace's name. In a terminal, `altimate-code link` does the same with a picker; the picker does not work after `!` in Claude Code. 3. **Check it** — `altimate-code workspace status` shows the linked workspace and its page in the Altimate web app. 4. **Ask Claude** — questions about your team's conventions, standards or knowledge go to altimate-code, which answers from the workspace. Start a request with `/altimate-code:altimate` to be sure it does: *"/altimate-code:altimate what are our naming conventions for staging models?"* diff --git a/plugins/altimate-code/commands/altimate.md b/plugins/altimate-code/commands/altimate.md index 3d9b4b5..e6c3a12 100644 --- a/plugins/altimate-code/commands/altimate.md +++ b/plugins/altimate-code/commands/altimate.md @@ -58,7 +58,7 @@ Workflow (follow in order, no skipping): If the project is linked to an Altimate workspace, altimate-code uses its skills, knowledge and memory automatically. There is nothing to pass. -4. **Surface the result verbatim:** read `"$OUTPUT_FILE"` and present its contents to the user without re-summarising, re-formatting, or commenting. altimate-code has already produced the answer. Delete `"$OUTPUT_FILE"` after presenting so warehouse rows, lineage, or PII findings don't linger on disk. +4. **Surface the result verbatim:** read `"$OUTPUT_FILE"` and present its contents to the user without re-summarising, re-formatting, or commenting. altimate-code has already produced the answer. Delete `"$OUTPUT_FILE"` after presenting so warehouse rows, lineage, or PII findings don't linger on disk. If the command's stderr says `not in the workspace yet` or `Could not confirm that the memory saved here reached the workspace`, add the matching note from the skill body's failure-modes table after the result. 5. **On any altimate-code error** (`Unauthorized`, `Token limit reached`, `No provider configured`, `Not signed in to Altimate`, warehouse credentials wrong, process timeout) — surface the error message to the user along with the fix from the skill body's failure-modes table. Do NOT fall back to native tools. The user invoked `/altimate-code:altimate` specifically to use altimate-code; falling back would defeat the purpose. diff --git a/plugins/altimate-code/skills/altimate-code/SKILL.md b/plugins/altimate-code/skills/altimate-code/SKILL.md index b3f94be..e23b733 100644 --- a/plugins/altimate-code/skills/altimate-code/SKILL.md +++ b/plugins/altimate-code/skills/altimate-code/SKILL.md @@ -101,9 +101,9 @@ A project can be linked to an Altimate workspace: the team's shared skills, know When the user asks about their workspace or wants to set one up: -- **Check the link:** `altimate-code workspace status < /dev/null`. Exit code 3 means the project is not linked; 2 means the user is not signed in to Altimate. +- **Check the link:** `altimate-code workspace status < /dev/null`. Exit code 0 means linked and 3 means not linked. Exit code 2 with `Not signed in to Altimate` means the user must sign in. For anything else, show the user the CLI's message. - **Not signed in:** tell the user to run `! altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"` in this session. It opens their browser to sign in. Do not try to sign in for them. Keep the `--method` flag: without it the command waits at a menu that cannot be answered from this session. -- **Not linked:** do not suggest `! altimate-code link`: its picker needs a terminal, and this session does not give it one. Instead run `altimate-code workspace list < /dev/null`, show the user the workspaces it prints, and once they choose, run `altimate-code link --workspace "" < /dev/null`. If they want a new workspace, run `altimate-code link --create < /dev/null`, which names it after the repository. If the project is already linked to a different workspace, `link` refuses; confirm the move with the user, then re-run it with `--yes`. If `workspace list` is an unknown command (an older altimate-code), ask the user for the workspace's name, or tell them to run `altimate-code link` in a separate terminal. +- **Not linked:** do not suggest `! altimate-code link`: its picker needs a terminal, and this session does not give it one. Instead run `altimate-code workspace list < /dev/null`, show the user the workspaces it prints, and once they choose, run `altimate-code link --workspace "" < /dev/null`. If they want a new workspace, run `altimate-code link --create < /dev/null`, which names it after the repository. If a workspace with that name already exists, `--create` refuses and names it: offer to link to that one with `--workspace`, or, if the user confirms they want a second one, re-run with `--allow-duplicate`. If the project is already linked to a different workspace, `link` refuses; confirm the move with the user, then re-run it with `--yes`. If `workspace list` is an unknown command (an older altimate-code), ask the user for the workspace's name, or tell them to run `altimate-code link` in a separate terminal. - **Open it in the browser:** `altimate-code workspace status` prints the workspace page's URL. What altimate-code learns during delegated tasks is saved to the workspace's memory and shared with the team in the CLI, the IDE and Studio. @@ -115,9 +115,10 @@ When altimate-code returns an error, **report the error to the user and STOP**. | Symptom | What to tell the user — verbatim | |---|---| | `command not found: altimate-code` | "altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+) and run `altimate-code` once to configure auth. Then re-run your request." | -| `Unauthorized: Incorrect auth token` / `No provider configured` | "altimate-code's LLM provider auth is misconfigured. Run `altimate-code` in your terminal to open the TUI and reconfigure your provider, or sign in to Altimate with `altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`, then re-run your request." | -| `Not signed in to Altimate` | "altimate-code is not signed in to Altimate, so it cannot reach your workspace. Run `! altimate-code auth login -p altimate-backend --method "Altimate LLM Gateway"`, sign in in the browser, then re-run your request." | -| `not in the workspace yet` or `Could not confirm that the memory saved here reached the workspace` (stderr) | Present the result as usual, then add: "altimate-code saved what it learned on this machine, but it has not reached your workspace yet. Run `! altimate-code workspace sync` to send it." | +| `Unauthorized: Incorrect auth token` / `No provider configured` | "altimate-code's LLM provider auth is misconfigured. Run `altimate-code` in your terminal to open the TUI and reconfigure your provider, or sign in to Altimate with `altimate-code auth login -p altimate-backend --method 'Altimate LLM Gateway'`, then re-run your request." | +| `Not signed in to Altimate` | "altimate-code is not signed in to Altimate, so it cannot reach your workspace. Run `! altimate-code auth login -p altimate-backend --method 'Altimate LLM Gateway'`, sign in in the browser, then re-run your request." | +| `not in the workspace yet` (stderr) | Present the result as usual, then add: "altimate-code saved what it learned on this machine, but it has not reached your workspace yet. Run `! altimate-code workspace sync` to send it." | +| `Could not confirm that the memory saved here reached the workspace` (stderr) | Present the result as usual, then add: "altimate-code could not confirm that what it learned reached your workspace. Run `! altimate-code workspace status` to check." | | Process hangs >5 min | "altimate-code is unresponsive. Try `altimate-code` to inspect the TUI for an open prompt, or re-run with `--model anthropic/claude-sonnet-4-6` to force a known-good model." | | Output file empty | "altimate-code returned without producing output. The task may be too ambiguous — please restate with more detail (target table, expected columns, time window)." | | Warehouse error mid-run (`UNKNOWN_USER`, `Database does not exist`) | "altimate-code can connect but the warehouse credentials it has are wrong for this project. Configure provider/warehouse auth via `altimate-code` TUI." |