feat: add /configure-claude and /configure-codex built-in commands

kulvirgit · kulvirgit · commit 6c08817bc9b9 · 2026-03-18T14:58:25.000-07:00
Adds built-in commands to configure altimate-code as a tool in external
AI CLIs:
- `/configure-claude` writes `~/.claude/commands/altimate.md` for Claude Code
- `/configure-codex` creates `~/.codex/skills/altimate/SKILL.md` for Codex CLI

Also adds `$$ARGUMENTS` escape support in the command processor so
templates can produce literal `$ARGUMENTS` in their output.

Updates docs: commands reference, getting-started, Claude Code guide,
and Codex guide.
diff --git a/docs/docs/configure/commands.md b/docs/docs/configure/commands.md
@@ -2,14 +2,16 @@
 
 ## Built-in Commands
 
-altimate ships with four built-in slash commands:
+altimate ships with six built-in slash commands:
 
 | Command | Description |
 |---------|-------------|
 | `/init` | Create or update an AGENTS.md file with build commands and code style guidelines. |
 | `/discover` | Scan your data stack and set up warehouse connections. Detects dbt projects, warehouse connections from profiles/Docker/env vars, installed tools, and config files. Walks you through adding and testing new connections, then indexes schemas. |
 | `/review` | Review changes — accepts `commit`, `branch`, or `pr` as an argument (defaults to uncommitted changes). |
 | `/feedback` | Submit product feedback as a GitHub issue. Guides you through title, category, description, and optional session context. |
+| `/configure-claude` | Configure altimate as a `/altimate` slash command in [Claude Code](https://claude.com/claude-code). Writes `~/.claude/commands/altimate.md` so you can invoke altimate from within Claude Code sessions. |
+| `/configure-codex` | Configure altimate as a skill in [Codex CLI](https://developers.openai.com/codex). Creates `~/.codex/skills/altimate/SKILL.md` so Codex can delegate data engineering tasks to altimate. |
 
 ### `/discover`
 
@@ -47,6 +49,31 @@ Submit product feedback directly from the CLI. The agent walks you through:
 
 Requires the `gh` CLI to be installed and authenticated (`gh auth login`).
 
+### `/configure-claude`
+
+Set up altimate as a tool inside Claude Code:
+
+```
+/configure-claude
+```
+
+This creates `~/.claude/commands/altimate.md`, which registers a `/altimate` slash command in Claude Code. After running this, you can use `/altimate` in any Claude Code session to delegate data engineering tasks:
+
+```
+# In Claude Code
+/altimate analyze the cost of our top 10 most expensive queries
+```
+
+### `/configure-codex`
+
+Set up altimate as a skill inside Codex CLI:
+
+```
+/configure-codex
+```
+
+This creates `~/.codex/skills/altimate/SKILL.md`. Restart Codex after running this command. Codex will then automatically invoke altimate when you ask about data engineering tasks.
+
 ## Custom Commands
 
 Custom commands let you define reusable slash commands.
@@ -109,3 +136,14 @@ Commands are loaded from:
 2. `~/.config/altimate-code/commands/` globally
 
 Press leader + `/` to see all available commands.
+
+## External CLI integration
+
+The `/configure-claude` and `/configure-codex` commands write integration files to external CLI tools:
+
+| Command | File created | Purpose |
+|---------|-------------|---------|
+| `/configure-claude` | `~/.claude/commands/altimate.md` | Registers `/altimate` slash command in Claude Code |
+| `/configure-codex` | `~/.codex/skills/altimate/SKILL.md` | Registers altimate as a Codex CLI skill |
+
+These files allow you to invoke altimate's data engineering capabilities from within other AI coding agents.
diff --git a/docs/docs/data-engineering/guides/using-with-claude-code.md b/docs/docs/data-engineering/guides/using-with-claude-code.md
@@ -4,11 +4,11 @@ altimate can work alongside Claude Code. While Claude Code handles general codin
 
 ## How it works
 
-Claude Code can invoke altimate as a tool when working on data projects. The `/data` skill routes data engineering tasks to altimate's specialized tools.
+Claude Code can invoke altimate as a tool when working on data projects. The `/altimate` command routes data engineering tasks to altimate's specialized tools.
 
 ```
 # In Claude Code
-/data "analyze the cost of our Snowflake warehouse"
+/altimate analyze the cost of our Snowflake warehouse
 ```
 
 This gives Claude Code access to:
@@ -29,7 +29,7 @@ When Claude Code reviews a PR that includes SQL changes:
 Claude Code: I see changes to models/marts/fct_revenue.sql. Let me check
              for data engineering concerns.
 
-> /data "analyze fct_revenue.sql for anti-patterns and estimate cost"
+> /altimate analyze fct_revenue.sql for anti-patterns and estimate cost
 
 altimate:
   sql_analyze: No anti-patterns detected ✓
@@ -45,7 +45,7 @@ You (in Claude Code): Set up a new dbt model for our customer metrics
 Claude Code: I'll create the model structure. Let me use altimate
              to inspect the source tables first.
 
-> /data "inspect the raw.customers and raw.orders tables"
+> /altimate inspect the raw.customers and raw.orders tables
 
 altimate:
   schema_inspect raw.customers → 12 columns
@@ -62,7 +62,7 @@ You (in Claude Code): This query is slow, can you optimize it?
 
 Claude Code: Let me analyze it with altimate's SQL tools.
 
-> /data "analyze and optimize: SELECT * FROM events WHERE YEAR(event_date) = 2026"
+> /altimate analyze and optimize: SELECT * FROM events WHERE YEAR(event_date) = 2026
 
 altimate:
   sql_analyze:
@@ -77,7 +77,15 @@ altimate:
 
 1. Install altimate globally: `npm install -g altimate-code`
 2. Configure warehouse connections in your project
-3. Claude Code automatically discovers altimate's tools when the `/data` skill is invoked
+3. Run `/configure-claude` inside altimate to set up the integration:
+
+```bash
+altimate
+# then in the TUI:
+/configure-claude
+```
+
+This creates `~/.claude/commands/altimate.md`. You can now use `/altimate` in any Claude Code session.
 
 ## When to use which
 
diff --git a/docs/docs/data-engineering/guides/using-with-codex.md b/docs/docs/data-engineering/guides/using-with-codex.md
@@ -1,4 +1,18 @@
-# Using altimate with Codex (ChatGPT Subscription)
+# Using altimate with Codex
+
+altimate integrates with Codex in two ways: as an **LLM provider** (use your ChatGPT subscription to power altimate) and as a **Codex skill** (invoke altimate from within Codex CLI).
+
+## Using altimate as a Codex CLI skill
+
+You can delegate data engineering tasks from Codex CLI to altimate. Run `/configure-codex` inside altimate to set up the integration:
+
+```
+/configure-codex
+```
+
+This creates `~/.codex/skills/altimate/SKILL.md`. Restart Codex to pick up the new skill. Codex will then automatically invoke altimate when you ask about data engineering tasks like SQL analysis, lineage, dbt, or FinOps.
+
+## Using Codex as an LLM provider
 
 If you have a ChatGPT Plus or Pro subscription, you can use Codex as your LLM backend in altimate at no additional API cost. Your subscription covers all usage.
 
diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
@@ -276,22 +276,36 @@ my-dbt-project/
 
 ## Using with Claude Code
 
-altimate works as a standalone agent, but you can also invoke it from within Claude Code sessions. Claude Code can call altimate's tools when working on data projects:
+altimate works as a standalone agent, but you can also invoke it from within Claude Code sessions. Run `/configure-claude` inside altimate to set up the integration:
+
+```
+/configure-claude
+```
+
+This creates a `/altimate` command in Claude Code. You can then use it in any Claude Code session:
 
 ```bash
-# In Claude Code, use the /data skill to route to altimate
-/data "analyze the cost of our top 10 most expensive queries"
+# In Claude Code
+/altimate analyze the cost of our top 10 most expensive queries
 ```
 
+See [Using with Claude Code](data-engineering/guides/using-with-claude-code.md) for detailed workflows.
+
 ## Using with Codex
 
-If you have a ChatGPT Plus/Pro subscription, you can use Codex as your LLM backend at no additional API cost:
+altimate integrates with Codex in two ways:
+
+**As a Codex CLI skill** — run `/configure-codex` inside altimate to install an `altimate` skill in Codex CLI. Restart Codex, and it can delegate data engineering tasks to altimate automatically.
+
+**As an LLM provider** — if you have a ChatGPT Plus/Pro subscription, you can use Codex as your LLM backend at no additional API cost:
 
 1. Run `/connect` in the TUI
 2. Select **Codex** as your provider
 3. Authenticate via browser OAuth
 4. Your subscription covers all usage — no API keys needed
 
+See [Using with Codex](data-engineering/guides/using-with-codex.md) for details.
+
 ## Verify your setup
 
 ```
diff --git a/packages/opencode/src/command/index.ts b/packages/opencode/src/command/index.ts
@@ -8,6 +8,10 @@ import PROMPT_INITIALIZE from "./template/initialize.txt"
 import PROMPT_DISCOVER from "./template/discover.txt"
 import PROMPT_REVIEW from "./template/review.txt"
 import PROMPT_FEEDBACK from "./template/feedback.txt"
+// altimate_change start — configure commands for external AI CLIs
+import PROMPT_CONFIGURE_CLAUDE from "./template/configure-claude.txt"
+import PROMPT_CONFIGURE_CODEX from "./template/configure-codex.txt"
+// altimate_change end
 import { MCP } from "../mcp"
 import { Skill } from "../skill"
 import { Log } from "../util/log"
@@ -60,6 +64,10 @@ export namespace Command {
     DISCOVER: "discover",
     REVIEW: "review",
     FEEDBACK: "feedback",
+    // altimate_change start
+    CONFIGURE_CLAUDE: "configure-claude",
+    CONFIGURE_CODEX: "configure-codex",
+    // altimate_change end
   } as const
 
   const state = Instance.state(async () => {
@@ -103,6 +111,26 @@ export namespace Command {
         },
         hints: hints(PROMPT_FEEDBACK),
       },
+      // altimate_change start — configure commands for external AI CLIs
+      [Default.CONFIGURE_CLAUDE]: {
+        name: Default.CONFIGURE_CLAUDE,
+        description: "configure /altimate command in Claude Code",
+        source: "command",
+        get template() {
+          return PROMPT_CONFIGURE_CLAUDE
+        },
+        hints: hints(PROMPT_CONFIGURE_CLAUDE),
+      },
+      [Default.CONFIGURE_CODEX]: {
+        name: Default.CONFIGURE_CODEX,
+        description: "configure altimate skill in Codex CLI",
+        source: "command",
+        get template() {
+          return PROMPT_CONFIGURE_CODEX
+        },
+        hints: hints(PROMPT_CONFIGURE_CODEX),
+      },
+      // altimate_change end
     }
 
     for (const [name, command] of Object.entries(cfg.command ?? {})) {
diff --git a/packages/opencode/src/command/template/configure-claude.txt b/packages/opencode/src/command/template/configure-claude.txt
@@ -0,0 +1,45 @@
+Configure the `/altimate` slash command for Claude Code (Anthropic's CLI).
+
+Your task: write a command file at `~/.claude/commands/altimate.md` so that users can type `/altimate` inside Claude Code to delegate tasks to altimate-code.
+
+Step 1 — Find the binary path by running: `which altimate || which altimate-code`
+
+Step 2 — Create directory `~/.claude/commands/` if it does not exist.
+
+Step 3 — Write the file `~/.claude/commands/altimate.md` with this exact content (replace BINARY_PATH with the path from Step 1):
+
+```
+---
+name: altimate
+description: "Run data engineering tasks using altimate-code"
+---
+
+# Data Engineering Tasks
+
+Delegate data engineering tasks to `altimate-code`, an AI agent with 40+ data engineering capabilities (SQL analysis, schema ops, lineage, dbt, FinOps, RBAC, etc.).
+
+## Usage
+
+Run this command to execute the task:
+
+` ` `bash
+BINARY_PATH run "$$ARGUMENTS"
+` ` `
+
+Pass the user's task directly — altimate-code is itself an AI agent that knows its own tools, explores the codebase, picks the right tools, and returns results.
+
+## After Getting Results
+
+Once you have the output from altimate-code:
+1. Parse and present the results clearly to the user
+2. Highlight key findings, warnings, or errors
+3. Save to a file if requested
+
+$$ARGUMENTS
+```
+
+IMPORTANT: The triple backticks in the bash block above have spaces between them to avoid conflicts with this template's own markdown. Remove those spaces when writing the actual file. The `$$ARGUMENTS` tokens above will appear as `$ARGUMENTS` in the written file — this is correct, as `$ARGUMENTS` is a Claude Code template variable.
+
+Step 4 — Read back the file to verify it was written correctly.
+
+Tell the user they can now use `/altimate` inside Claude Code.
diff --git a/packages/opencode/src/command/template/configure-codex.txt b/packages/opencode/src/command/template/configure-codex.txt
@@ -0,0 +1,26 @@
+Configure Codex CLI to use altimate-code as a skill.
+
+Your task: create a skill at `~/.codex/skills/altimate/` so that Codex can delegate data engineering tasks to altimate-code.
+
+Step 1 — Find the binary path by running: `which altimate || which altimate-code`
+
+Step 2 — Create the skill directory: `~/.codex/skills/altimate/`
+
+Step 3 — Write the file `~/.codex/skills/altimate/SKILL.md` with this content:
+
+Frontmatter (YAML):
+- name: altimate
+- description: "Delegate data engineering tasks to altimate-code, an AI agent with 40+ data engineering capabilities including SQL analysis, schema operations, lineage, dbt, FinOps, and RBAC. Use when the user asks about data warehouse operations, SQL queries, dbt models, data lineage, schema management, or any data engineering task."
+
+Body (Markdown):
+- Title: "# Altimate Code"
+- Explain that altimate-code is an external AI agent specialized in data engineering
+- Provide a "## Usage" section instructing Codex to run: `BINARY_PATH run "<user's request>"` (replace BINARY_PATH with the path found in Step 1)
+- Explain that altimate-code handles tool selection autonomously — just pass the user's request as-is
+- Add a "## After Getting Results" section: parse output, highlight findings/warnings/errors, save to file if requested
+
+Keep the SKILL.md concise (under 50 lines) per Codex skill best practices.
+
+Step 4 — Read back the file to verify it was written correctly.
+
+Tell the user: the `altimate` skill is now installed in Codex. They should restart Codex to pick it up.
diff --git a/packages/opencode/src/session/prompt.ts b/packages/opencode/src/session/prompt.ts
@@ -1901,7 +1901,10 @@ NOTE: At any point in time through this workflow you should feel free to ask the
       return args[argIndex]
     })
     const usesArgumentsPlaceholder = templateCommand.includes("$ARGUMENTS")
-    let template = withArgs.replaceAll("$ARGUMENTS", input.arguments)
+    // altimate_change start — allow $$ARGUMENTS to produce literal $ARGUMENTS in output
+    const ESCAPE_SENTINEL = "\x00ESCAPED_DOLLAR_ARGUMENTS\x00"
+    let template = withArgs.replaceAll("$$ARGUMENTS", ESCAPE_SENTINEL).replaceAll("$ARGUMENTS", input.arguments).replaceAll(ESCAPE_SENTINEL, "$ARGUMENTS")
+    // altimate_change end
 
     // If command doesn't explicitly handle arguments (no $N or $ARGUMENTS placeholders)
     // but user provided arguments, append them to the template
