Cortex Router

Cortex Code Router

Route Snowflake operations to Cortex Code CLI, which has specialized bundled skills (data-quality, semantic-view, cost-intelligence, ML, governance, etc.).

CRITICAL: Follow steps 1 → 2 → 3 in order. Do NOT skip to Step 3.

Step 1: Verify CLI

which cortex 2>/dev/null && cortex --version

If cortex is NOT found:

1. Tell the user: "Cortex Code CLI is not installed. Setting it up now."

2. Load the snowflake-cortex-code:cortex-setup skill using the Skill tool.

3. STOP — do not continue until the CLI is installed.

Step 2: Confirm Routing

Run the routing script to check if this prompt should go to Cortex or stay in Claude Code:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/run_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/router/route_request.py" --prompt "USER_PROMPT_HERE"

Replace USER_PROMPT_HERE with the actual user prompt (shell-escaped).

The shared launcher selects python3, or python only after verifying Python 3. Use Bash (Git Bash on Windows). It never retries a failed script under another interpreter. If routing fails, STOP and report the error; do not bypass a configuration/policy error.

Read the output carefully:

• If output says "route: cortex" → proceed to Step 3

• If output says "route: claude" → STOP. Handle the request yourself using Claude Code tools (sql_execute, Read, Write, etc.). Do NOT run execute_cortex.py.

Step 3: Execute via Cortex Code

Only reach this step if Step 2 confirmed routing to Cortex.

Choose a security envelope based on the operation:

• RO: Read-only queries (SELECT, SHOW, DESCRIBE) — won't run DDL or DML

• RW: Data modifications, DDL (CREATE, ALTER, DROP) — default for most operations

• RESEARCH: Read + web access, no writes

• DEPLOY: Full access (use sparingly)

Default to RW unless the request is clearly read-only.

bash "${CLAUDE_PLUGIN_ROOT}/scripts/run_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/router/execute_cortex.py" \
  --prompt "USER_PROMPT_HERE" \
  --envelope "RW"

Add --connection CONNECTION_NAME if a specific Snowflake connection is needed.

Multi-turn: --resume-last vs fresh

Every cortex invocation returns a session_id that the router persists. Follow-up turns can resume that session so Cortex sees the prior conversation -- real multi-turn, not one-shot batches per prompt.

• Add --resume-last when the current prompt is a continuation of the previous Cortex turn: "keep going", "apply the top suggestion", "dig deeper", "also show me ...", "and for last quarter", "fix that", or any clarification of an answer Cortex just gave.

• Omit --resume-last (start fresh) when the user switches topics, asks about a different database/warehouse, or begins a clearly new task.

• --resume <session_id> is also accepted if you have an explicit id.

# Follow-up on the previous Cortex turn
bash "${CLAUDE_PLUGIN_ROOT}/scripts/run_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/router/execute_cortex.py" \
  --prompt "drill into the top customer" --envelope "RO" \
  --resume-last

Timeout: This command may take 30-90 seconds. If it takes longer than 2 minutes, it likely hung — kill the process and tell the user to try $cortex-run for direct invocation.

Step 4: Return Results

Format Cortex's output for the user:

• Show SQL results in readable tables

• Display any generated artifacts or analysis

• Report success/failure clearly

Notes

• Cortex has bundled skills for: data-quality, semantic-view, cost-intelligence, ML, governance, security, lineage, dynamic-tables, and more

• For simple SQL queries that don't need Cortex skills, Step 2 should route to Claude Code

• If routing or execution fails, STOP and report the error rather than bypassing the plugin

• Multi-turn context is preserved across invocations via --resume-last (see Step 3)