cortex-code

name	cortex-code
description	Routes Snowflake-related operations to Cortex Code CLI for specialized Snowflake expertise. Use when the user asks about Snowflake databases, warehouses, schemas, tables, SQL on Snowflake, Cortex AI features, Snowpark, dynamic tables, streams, tasks, governance, or Snowflake security. Do not use for general programming, local file operations, non-Snowflake databases, web development, or infrastructure unrelated to Snowflake.
license	Proprietary. See LICENSE for complete terms
metadata	{"author":"Snowflake Integration Team","compatibility":"Requires Cortex Code CLI installed and configured"}

Cortex Code Integration for Codex

This skill lets Codex delegate Snowflake-specific work to Cortex Code via the cortexcode-tool CLI while Codex remains the primary assistant for general coding and local repository tasks.

Routing Principle

Only Snowflake-specific operations go to Cortex Code. Everything else stays in Codex. The cortexcode-tool automatically handles routing.

How to use this skill

When this skill triggers, follow this workflow.

1. Execute Snowflake queries via cortexcode-tool

Ask the user for approval in Codex before execution. After approval, run cortexcode-tool as a foreground command with --yes — do NOT background it with &. Codex automatically waits for long-running commands ("Waited for background terminal"). The command takes 30-90 seconds.

cortexcode-tool --yes "USER_PROMPT_HERE" --envelope RO --config ~/.local/lib/cortexcode-tool/config.yaml

Choose envelope based on operation:

• RO for read-only queries (default for most operations)
• RW for data modifications or writes
• RESEARCH for exploratory work
• DEPLOY for deployment operations

IMPORTANT: Do not call cortex -p directly — it requires interactive stdin and will hang. IMPORTANT: Do not use & disown or background execution — Codex cannot track orphaned processes. IMPORTANT: Do not use --yes until the user has approved the planned Cortex Code execution in Codex chat. IMPORTANT: If cortexcode-tool says it requires network access, ask the user to approve the planned Cortex Code execution in Codex chat and retry with --yes.

2. Present results back in Codex

After cortexcode-tool finishes:

• The tool returns clean, formatted output (not JSON)
• Summarize the result clearly for the user
• Include key findings, SQL, errors, or next actions
• Keep Codex as the user-facing orchestrator

Example output (stdout only — routing/debug messages go to stderr):

You have **64 databases** in your Snowflake account...

3. Handle non-Snowflake requests locally

For non-Snowflake requests, handle directly using Codex tools:

• Local file reads/writes/edits
• Git operations
• Web or app development unrelated to Snowflake
• General Python, JavaScript, shell, or infrastructure work
• Non-Snowflake databases

Security expectations

The cortexcode-tool uses built-in security flow:

• Prompt approval by default (approval_mode: "prompt")
• Audit logging to ~/.cache/cortexcode-tool/audit.log
• Envelope-based tool restrictions
• Prompt sanitization
• Credential path blocking

Config file location: ~/.local/lib/cortexcode-tool/config.yaml (written by install.sh, persists across reboots)

Notes for Codex

• Handle local file operations, git, and non-Snowflake work directly - don't use cortexcode-tool
• For Snowflake queries, use cortexcode-tool with appropriate envelope
• Keep context minimal when invoking Cortex
• cortexcode-tool automatically determines if a query is Snowflake-related
• If a query fails routing or times out, handle locally or explain the limitation

Troubleshooting

Error: Permission denied on audit log or cache

Solution: Use the provided config (audit/cache go to ~/.cache/cortexcode-tool):

--config ~/.local/lib/cortexcode-tool/config.yaml

Error: Cortexcode-tool not found

Solution: Run the Codex install script — it installs cortexcode-tool automatically:

bash integrations/codex/install.sh

Query takes too long

Note: Queries typically take 30-60 seconds. Codex will wait automatically. If the command times out, retry once — Snowflake connection may have been cold.

cortex -p hangs with no output

Cause: Direct cortex -p invocation may wait for interactive approval in non-TTY terminals. Solution: Use cortexcode-tool, which invokes Cortex in stream JSON mode with the configured envelope.

Examples

Snowflake database count:

cortexcode-tool --yes "How many databases do I have in Snowflake?" --envelope RO --config ~/.local/lib/cortexcode-tool/config.yaml

Query specific database:

cortexcode-tool --yes "What tables are in DB_STOCK database?" --envelope RO --config ~/.local/lib/cortexcode-tool/config.yaml

Data modification:

cortexcode-tool --yes "Create a backup table of SALES_DATA" --envelope RW --config ~/.local/lib/cortexcode-tool/config.yaml