git:20260824.f9f3e9d to git:20260902.c132496

# Ask LLM: Full Reference for AI Agents

> MCP servers for AI-to-AI collaboration: bridge your AI client with Codex, Claude, Grok, Antigravity, Ollama, and Gemini.

This file contains everything an AI agent needs to integrate with Ask LLM MCP servers: tool schemas, configuration examples, provider details, and plugin setup.

## Architecture

Ask LLM is a monorepo with 8 published npm packages + 1 private shared library. `@ask-llm/plugin` is the canonical Claude Code + Cursor Agent + Pi host package:

```

packages/shared/ @ask-llm/shared Internal shared code (inlined into each MCP at build: registry, executor, sessions, usage)

packages/codex-mcp/ @ask-llm/codex-mcp MCP server for OpenAI Codex CLI

packages/claude-mcp/ @ask-llm/claude-mcp MCP server for Anthropic Claude Code CLI

packages/grok-mcp/ @ask-llm/grok-mcp MCP server for Grok through the xAI Responses API

packages/antigravity-mcp @ask-llm/antigravity-mcp MCP server for Google Antigravity CLI (agy)

packages/ollama-mcp/ @ask-llm/ollama-mcp MCP server for local Ollama LLMs

packages/gemini-mcp/ @ask-llm/gemini-mcp MCP server for Google Gemini CLI

packages/llm-mcp/ @ask-llm/mcp Unified MCP server (auto-detects providers)

packages/claude-plugin @ask-llm/plugin Claude Code + Cursor Agent + Pi host package (one skill corpus; host adapters)

```

## Cursor Agent host quick start

```bash

agent --plugin-dir ./packages/claude-plugin # from a source checkout

```

Cursor loads `.cursor-plugin/plugin.json`: exactly the Cursor-adapted `/codex-pair` and `/grok-pair` skills through Agent Skills (`agents`, `commands`, and `hooks` are explicitly empty so the Claude agents and Claude-format `hooks/hooks.json` are never auto-discovered; the review/brainstorm/compare skills stay Claude/Pi-only for now) plus `mcp.json` registering only the unified `ask-llm` server (`@ask-llm/codex-mcp` / `@ask-llm/grok-mcp` are optional user installs whose `ask-codex`/`ask-grok` leaves the pair skills prefer when exposed; otherwise fully pinned unified calls, no fallback, one registration per server). It never consumes Claude hooks, `${CLAUDE_PLUGIN_ROOT}`, or plugin namespaces, and omits the `-ack`/`-pause`/`-resume` toggles (no background reviewer). MCP-only setup: copy the single `mcp.json` entry into `.cursor/mcp.json`. Guide: https://lykhoyda.github.io/ask-llm/plugin/cursor

## Pi host quick start

```bash

pi install npm:@ask-llm/plugin

```

Pi is the host, not a consulted provider, and has no built-in MCP client. The package registers native `ask-codex`, `ask-gemini`, `ask-grok`, `ask-ollama`, `ask-antigravity`, model-neutral `ask-cursor-agent`, and deterministic `ask-multi`; skills use `/skill:<name>`. `fable-review` and `grok-pair` are excluded. Pi codex-pair requires marker + project trust + interactive user-owned allowlist consent, surfaces findings non-blockingly, and does not support asynchronous pairing in one-shot print mode.

## Prerequisites

- Node.js >= 20.0.0 (runtime)

- For Codex: Codex CLI installed and authenticated

- For Claude: `npm install -g @anthropic-ai/claude-code`, then authenticate (provider is for Codex and other non-Claude hosts)

- For Antigravity: `agy` 1.1.5 or newer installed and logged in once (`agy --version`, then run `agy` interactively to authenticate)

- For Ollama: Ollama running locally (`https://ollama.com`) with a model pulled (`ollama pull qwen3.8:27b`)

- For Gemini: `npm install -g @google/gemini-cli && gemini login` (enterprise-gated since 2026-06-18)

## Installation

### Claude Code (user scope: available across all projects)

```bash

claude mcp add --scope user gemini -- npx -y @ask-llm/gemini-mcp

claude mcp add --scope user codex -- npx -y @ask-llm/codex-mcp

claude mcp add --scope user ollama -- npx -y @ask-llm/ollama-mcp

claude mcp add --scope user antigravity -- npx -y @ask-llm/antigravity-mcp

```

### Claude Code (project scope)

```bash

claude mcp add gemini -- npx -y @ask-llm/gemini-mcp

claude mcp add codex -- npx -y @ask-llm/codex-mcp

claude mcp add ollama -- npx -y @ask-llm/ollama-mcp

claude mcp add antigravity -- npx -y @ask-llm/antigravity-mcp

```

### Claude Desktop (claude_desktop_config.json)

```json

{

"mcpServers": {

"gemini": {

"command": "npx",

"args": ["-y", "@ask-llm/gemini-mcp"]

},

"codex": {

"command": "npx",

"args": ["-y", "@ask-llm/codex-mcp"]

},

"ollama": {

"command": "npx",

"args": ["-y", "@ask-llm/ollama-mcp"]

},

"antigravity": {

"command": "npx",

"args": ["-y", "@ask-llm/antigravity-mcp"]

}

}

}

```

### Cursor (.cursor/mcp.json)

```json

{

"mcpServers": {

"gemini": {

"command": "npx",

"args": ["-y", "@ask-llm/gemini-mcp"]

},

"codex": {

"command": "npx",

"args": ["-y", "@ask-llm/codex-mcp"]

},

"ollama": {

"command": "npx",

"args": ["-y", "@ask-llm/ollama-mcp"]

},

"antigravity": {

"command": "npx",

"args": ["-y", "@ask-llm/antigravity-mcp"]

}

}

}

```

### Codex CLI (~/.codex/config.toml)

```toml

[mcp_servers.claude]

command = "npx"

args = ["-y", "@ask-llm/claude-mcp"]

```

The block above registers the focused Codex → Claude second-opinion path. Add a `[mcp_servers.<name>]` section per provider, or register the unified `@ask-llm/mcp` to expose all installed providers through one server.

### Any MCP Client (STDIO transport)

```json

{

"transport": {

"type": "stdio",

"command": "npx",

"args": ["-y", "@ask-llm/gemini-mcp"]

}

}

```

The `@ask-llm/gemini-mcp` argument above is just an example: the same STDIO block works for any package (`@ask-llm/codex-mcp`, `@ask-llm/claude-mcp`, `@ask-llm/grok-mcp`, `@ask-llm/ollama-mcp`, `@ask-llm/antigravity-mcp`, or the unified `@ask-llm/mcp`).

### Unified Server (all providers in one)

```bash

claude mcp add ask-llm -- npx -y @ask-llm/mcp

```

The unified server detects configured providers at startup (via `which`/`where` for CLIs, an HTTP probe for Ollama, and the presence of `XAI_API_KEY` for Grok) and registers only available tools.

## Tool Reference

### ask-gemini

Send prompts to Google Gemini CLI. Supports @ file syntax for including files in context.

- **Package:** @ask-llm/gemini-mcp

- **Parameters:**

- `prompt` (string, required): The question, code review request, or analysis task. Use @ syntax to include files (e.g., "@src/main.ts explain this code").

- `sessionId` (string, optional): Resume a prior conversation. Reuse the sessionId returned in a previous response to continue multi-turn context.

- **Returns:** Gemini's text response plus a structured payload (provider, model, sessionId, usage).

- **Annotations:** readOnlyHint=false, destructiveHint=false, openWorldHint=true

### ask-gemini-edit

Send a code edit request to Gemini and get structured OLD/NEW edit blocks. Gemini analyzes files and returns precise, applicable code changes.

- **Package:** @ask-llm/gemini-mcp

- **Parameters:**

- `prompt` (string, required): Describe the code changes you want. Reference files with @ syntax.

- `model` (string, optional): Default: gemini-3.1-pro-preview.

- `includeDirs` (string[], optional): Additional directories to include in Gemini's context. Useful for monorepos. Paths must be relative: no `..`, absolute paths, or `~`.

- **Returns:** Structured edit format with OLD/NEW blocks, or chunked response with cache key for large edits.

- **Annotations:** readOnlyHint=false, destructiveHint=false, openWorldHint=true

### fetch-chunk

Retrieve subsequent chunks from cached large responses (used after ask-gemini-edit returns chunked output).

- **Package:** @ask-llm/gemini-mcp

- **Parameters:**

- `cacheKey` (string, required): Cache key returned by the original chunked response.

- `chunkIndex` (number, required): 1-based index of the chunk to retrieve.

- **Returns:** The requested chunk content.

- **Annotations:** readOnlyHint=true, idempotentHint=true, openWorldHint=false

### ask-codex

Send prompts to OpenAI Codex CLI.

- **Package:** @ask-llm/codex-mcp

- **Parameters:**

- `prompt` (string, required): The question, code review request, or analysis task.

- `model` (string, optional): Do not set unless user explicitly requests it. Default: gpt-5.6-sol. Falls back to gpt-5.6-terra on quota errors.

- `reasoningEffort` (string, optional): low, medium, high, xhigh, or max. Default: medium. /codex-review and /brainstorm use high.

- `sessionId` (string, optional): Omit for an ephemeral call, pass `""` to create a fresh persisted thread, or pass a non-empty returned thread_id to resume.

- `includeDirs` (string[], optional): Additional directories to expose to Codex (`--add-dir`) on fresh calls only; not forwarded when resuming. Paths must be relative: no `..`, absolute paths, or `~`.

- `preferred` (boolean, optional): Opt into ASK_CODEX_PREFERRED_MODEL only when configured to differ from the gpt-5.6-sol default. Review skills leave it unset.

- **Returns:** Codex's text response plus a structured payload (provider, model, sessionId, usage).

- **Annotations:** readOnlyHint=false, destructiveHint=false, openWorldHint=true

### ask-codex-edit

Get structured, read-only code edits from Codex via `--output-schema`. Codex analyzes files and proposes changes without writing to disk.

- **Package:** @ask-llm/codex-mcp

- **Parameters:**

- `prompt` (string, required): Describe the code changes you want.

- `model` (string, optional): Default: gpt-5.6-sol.

- `sessionId` (string, optional): Omit for an ephemeral call, pass `""` to create a fresh persisted thread, or pass a non-empty returned thread_id to resume.

- `includeDirs` (string[], optional): Additional directories to expose to Codex (`--add-dir`) on fresh calls only; not forwarded when resuming. Paths must be relative: no `..`, absolute paths, or `~`.

- **Returns:** Structured edit proposal (read-only: the caller applies the changes).

- **Annotations:** readOnlyHint=false, destructiveHint=false, openWorldHint=true

### ask-claude

Send prompts to Anthropic Claude Code CLI from Codex or another non-Claude MCP host. Claude runs in safe mode with only Read, Glob, and Grep tools; it cannot execute commands or modify files.

- **Package:** @ask-llm/claude-mcp

- **Parameters:**

- `prompt` (string, required): The question, review, or analysis task. Delivered over stdin.

- `model` (string, optional): Default `opus`; Claude Code natively falls back to `sonnet` when unavailable or overloaded.

- `sessionId` (string, optional): Resume a native Claude conversation with `--resume`.

- `includeDirs` (string[], optional): Additional relative directories Claude may read. No `..`, absolute paths, or `~`.

- **Returns:** Claude's response plus actual model, native session ID, and token usage.

- **Annotations:** readOnlyHint=true, destructiveHint=false, openWorldHint=true

- **Host constraint:** unavailable when `CLAUDECODE` indicates Claude Code is already the host, because nested Claude sessions are unsupported.

### ask-grok

Send a one-shot prompt through either xAI's Responses API (`xai-api`, default) or the official Grok Build headless CLI (`grok-cli`). Harness and model are separate; neither falls back. Requires `XAI_API_KEY`; API usage is metered separately from consumer subscriptions.

- **Package:** @ask-llm/grok-mcp

- **Parameters:**

- `prompt` (string, required): The review, question, or analysis task.

- `model` (string, optional): Exact selected-harness model ID, sent unchanged. Default: `grok-4.6` (xAI API) or `grok-build` (Grok CLI). There is no fallback.

- `harness` (string, optional): `xai-api` or `grok-cli`; default `xai-api` or `ASK_GROK_HARNESS`. No harness failover.

- `reasoningEffort` (string, optional): `low`, `medium`, `high`, or `xhigh`; default `high`.

- **Returns:** Grok text plus standard structured provider/model/usage metadata. Machine-mode callers get strict JSON Schema output.

- **Annotations:** readOnlyHint=true, destructiveHint=false, openWorldHint=true

- **Cost/privacy:** never enables billing, credits, overage, priority processing, or server-side tools; requests set `store:false`.

- **Discovery:** `GET https://api.x.ai/v1/models` with the API key lists exact IDs without billed inference.

### ask-ollama

Send prompts to a local Ollama LLM via HTTP. No API keys or network calls needed.

- **Package:** @ask-llm/ollama-mcp

- **Parameters:**

- `prompt` (string, required): The question, code review request, or analysis task.

- `model` (string, optional): Do not set unless user explicitly requests it. Default: qwen3.8:27b. No fallback: returns a clear "ollama pull" error if the model isn't installed.

- `sessionId` (string, optional): Resume a prior on-disk session for multi-turn context.

- **Returns:** Ollama's text response plus a structured payload.

- **Annotations:** readOnlyHint=false, destructiveHint=false, openWorldHint=false

- **Environment:** Set OLLAMA_HOST to customize the Ollama server address (default: http://localhost:11434).

### ask-antigravity

Send prompts to Google's Antigravity CLI (`agy`) for a subscription-backed second opinion, code review, or analysis. Intended for read-only review, but note: `agy` is an agent that *can* act. ask-antigravity constrains it with a read-only prompt preamble **plus** a sandbox (`--sandbox`, on by default; disable with `ASK_ANTIGRAVITY_SANDBOX=0`) and runs `agy` with `--dangerously-skip-permissions` to avoid headless approval hangs: this is a soft, defense-in-depth guard, not a hard non-mutating execution mode, so treat workspace context passed via `includeDirs` accordingly. Single-turn only (no multi-turn sessions).

- **Package:** @ask-llm/antigravity-mcp

- **Parameters:**

- `prompt` (string, required): The question, code review request, or analysis task.

- `includeDirs` (string[], optional): Additional directories to expose to agy (`--add-dir`). Paths must be relative: no `..`, absolute paths, or `~`.

- **Model selection:** There is NO per-call `model` parameter. The model is chosen via the `ASK_ANTIGRAVITY_MODEL` env var. Default: `gemini-3.1-pro` at high effort; falls back to `gemini-3.5-flash` at high effort on a subscription rate limit. Run `agy models` for available options.

- **Returns:** Antigravity's text response plus a structured payload. Single-turn only: no sessionId.

- **Annotations:** readOnlyHint=false, destructiveHint=false, openWorldHint=true

- **Requires:** `agy` 1.1.5 or newer, installed and logged in once; the executor rejects older versions before model invocation.

### ask-llm

Route a single prompt to any one installed provider (unified server).

- **Package:** @ask-llm/mcp

- **Parameters:**

- `prompt` (string, required): The question or task.

- `provider` (string, required): Which provider to route to: one of gemini, codex, claude, grok, ollama, antigravity. Must be one that is installed/detected; there is no default.

- `model` (string, optional): Provider-specific model override.

- `sessionId` (string, optional): For Codex, omit it for an ephemeral call, pass `""` to create a fresh persisted thread, or pass a non-empty returned Thread ID to resume. For other session-capable providers, pass a prior session ID to resume.

- `harness` (string, optional): `xai-api` or `grok-cli`; valid only with `provider: "grok"`.

- `includeDirs` (string[], optional): Relative workspace directories forwarded only to codex, claude, or antigravity; other providers reject it instead of silently dropping it. Codex accepts it only on a fresh call (`sessionId` omitted or `""`), never on a resumed thread.

- `reasoningEffort` (string, optional): `low` | `medium` | `high` | `xhigh` | `max`, forwarded only to codex (all five) or grok (no `max`); unsupported combinations are schema errors, never stripped.

- **Returns:** The chosen provider's text response plus a structured payload (including the resolved provider and model, so quota fallbacks are visible).

- **Annotations:** readOnlyHint=false, destructiveHint=false, openWorldHint=true

### ask-cursor-agent

Use Cursor Agent as a model-neutral read-only harness. Requires an authenticated `agent` CLI.

- **Package:** @ask-llm/mcp

- **Parameters:** `provider` (canonical model provider), `model` (required exact ID from `agent --list-models`), `prompt`, `includeDirs` (optional relative directories mapped to repeated `--add-dir`), `sessionId` (optional prior Cursor conversation ID; omit on the first call).

- **Behavior:** `agent --print --mode ask`; no `--force`, no automatic `--trust`, no Auto model, no spend-limit changes, and no fallback. A provided `sessionId` is passed as `--resume`.

- **Returns:** Standard AskResponse with separate provider, the exact requested Cursor ID echoed as `model`, Cursor's display label as optional `reportedModel`, the Cursor conversation ID as `sessionId` (reuse it to resume), and `harness: "cursor-agent"`.

### multi-llm

Dispatch one prompt to multiple installed providers in parallel and return a structured comparison report.

- **Package:** @ask-llm/mcp

- **Parameters:**

- `prompt` (string, required): The question or task.

- `providers` (string[], optional): Subset of installed providers to query. Defaults to all detected providers.

- **Returns:** A structured report with each provider's response, model, and usage.

- **Annotations:** readOnlyHint=false, destructiveHint=false, openWorldHint=true

### get-usage-stats

Report aggregated session usage (tokens, call counts) for the server's provider(s). Available in all packages.

- **Parameters:** none

- **Returns:** Session usage aggregation.

- **Annotations:** readOnlyHint=true, idempotentHint=true, openWorldHint=false

### diagnose

Environment diagnostics for the unified server: reports which provider CLIs are installed, reachable, and correctly configured (includes codex-doctor enrichment).

- **Package:** @ask-llm/mcp

- **Parameters:** none

- **Returns:** A per-provider diagnostic report.

- **Annotations:** readOnlyHint=true, idempotentHint=true, openWorldHint=false

### ping

Test MCP server connectivity. Available in all packages.

- **Parameters:**

- `message` (string, optional): A message to echo back.

- **Returns:** The echoed message or a default pong response. Grok's ping validates the key and lists exact API model IDs without inference; Ollama's ping lists locally available models; Antigravity's ping probes the agy version.

- **Annotations:** readOnlyHint=true, idempotentHint=true, openWorldHint=false

## Models

### Gemini

| Model | Use Case |

|-------|----------|

| gemini-3.1-pro-preview | Default: best quality reasoning, 1M+ token context |

### Codex

| Model | Use Case |

|-------|----------|

| gpt-5.6-sol | Default: flagship capability |

| gpt-5.6-terra | Automatic balanced fallback on quota errors |

### Ollama

| Model | Use Case |

|-------|----------|

| qwen3.8:27b | Default: Qwen's flagship-level local coding model (~18 GB) |

Ollama is local: no automatic fallback. Override with `ASK_OLLAMA_MODEL`; a model that isn't pulled returns a clear `ollama pull` error.

### Antigravity

| Model | Use Case |

|-------|----------|

| `gemini-3.1-pro` + `--effort high` | Default: strongest reasoning tier for the second-opinion workload |

| `gemini-3.5-flash` + `--effort high` | Automatic fallback on subscription rate limits |

Antigravity models use base slugs plus a separate effort tier (run `agy models`). Override with `ASK_ANTIGRAVITY_MODEL` and `ASK_ANTIGRAVITY_EFFORT`.

## Usage Patterns

### Code review (second opinion)

```

Ask Gemini to review @src/auth.ts for security issues

```

### Codebase analysis

```

Ask Gemini to summarize @. the current directory

```

> Note: `@` file/directory syntax is a **Gemini-CLI feature only**. Codex, Grok, Ollama, and Antigravity receive `@paths` as literal prompt text: give them file context via `includeDirs` (codex / codex-edit / antigravity) or by pasting the code into the prompt (ollama has no file access).

### Architecture debate

```

Ask Codex: should we use a message queue or direct HTTP calls for this service?

```

### Local private review

```

Ask Ollama to review this diff (paste the code: Ollama reads no files):

<paste the changed lines of src/payments.ts here>

```

### Subscription-backed second opinion

```

Ask Antigravity to critique the trade-offs in the scheduler module

(pass its directory via includeDirs, e.g. includeDirs=["src/scheduler"], or paste the code)

```

### Multi-provider review (Claude Code plugin)

```

/multi-review

```

Launches Antigravity and Codex reviews in parallel with a validation pipeline and consensus highlighting.

## Claude Code Plugin

### Installation

```

/plugin marketplace add Lykhoyda/ask-llm

/plugin install ask-llm@ask-llm-plugins

```

### Skills (slash commands)

| Skill | Description |

|-------|-------------|

| /multi-review | Parallel Antigravity + Codex code review with validation pipeline and consensus highlighting |

| /fable-review | Native read-only review in an isolated context pinned to the Fable model; source-verified, confidence-filtered findings (no MCP server needed) |

| /sol-review | Model-pinned review explicitly requesting GPT-5.6 Sol at high reasoning through Codex; quota fallback to Terra is disclosed |

| /codex-review | Codex-only code review with confidence filtering |

| /antigravity-review | Antigravity-only code review (subscription-backed) |

| /ollama-review | Local Ollama code review: no data leaves machine |

| /gemini-review | Gemini-only code review with confidence filtering |

| /brainstorm [participants] topic | Multi-LLM brainstorm; Claude researches in parallel (default external providers: antigravity,codex). Participants are either all bare provider names or all routed provider@harness:exact-model-id specs; the exact no-Gemini panel is grok@cursor-agent:cursor-grok-4.6-high,codex@cursor-agent:gpt-5.6-sol-high (one failure = partial, never two-model consensus) |

| /brainstorm-all topic | Brainstorm with all five providers (gemini, codex, grok, ollama, antigravity) |

| /grok-review | Grok review through explicit xAI API or Grok CLI harness; no fallback |

| /compare | Side-by-side raw responses from multiple providers (no synthesis) |

| /codex-verify | Verify the assistant's claims against actual state using Codex (read-only) |

| /codex-image | Generate images via Codex (gpt-image-2) |

| /grok-pair | Consent-gated iterative Grok reviewer through one explicit route (Cursor Agent `ask-cursor-agent`, xAI API, or Grok CLI); exact model/effort attribution, no fallback; needs user-scoped `@ask-llm/mcp` / `@ask-llm/grok-mcp` |

| /codex-pair (+ -ack, -pause, -resume) | Seamless per-edit Codex pairing dashboard and controls (Claude/Pi); on Cursor Agent the same skill runs an on-demand persisted Codex session (user-installed `ask-codex` leaf when exposed, otherwise fully pinned unified `ask-llm`) without the toggles |

### Agents

| Agent | Description |

|-------|-------------|

| fable-reviewer | Native read-only Fable review in an isolated context, source-verified high-confidence findings |

| sol-reviewer | Isolated read-only review pinned to GPT-5.6 Sol via Codex, source-verified high-confidence findings |

| codex-reviewer | Isolated Codex review, confidence-filtered findings |

| antigravity-reviewer | Isolated Antigravity review, confidence-filtered findings |

| ollama-reviewer | Isolated local Ollama review, confidence-filtered findings |

| gemini-reviewer | Isolated Gemini review, confidence-filtered findings |

| codex-verifier | Verifies the assistant's claims against actual state (STATUS + CONFIDENCE) |

| brainstorm-coordinator | Claude's own research + parallel external-provider consultation, synthesized; non-voting in the exact Grok + GPT-5.6 Sol mode |

### Hooks

Every hook the plugin registers is part of the **codex-pair** continuous-review pipeline (flagship feature, dedicated page: https://lykhoyda.github.io/ask-llm/plugin/codex-pair). All are dependency-free and self-gate on a `.codex-pair/context.md` marker (zero cost without it); only `codex-pair-watch` shells out to `codex exec --json` to run a review.

| Hook | Trigger | Action |

|------|---------|--------|

| codex-pair-watch (PostToolUse) | After Edit / Write / MultiEdit | Debounced per-edit Codex review of the settled file state (opt-in per project) |

| codex-pair-prompt-drain (UserPromptSubmit) | On every user prompt | Drains queued verdicts that finished mid-turn so they reach Claude |

| codex-pair-stop-gate (Stop) | Turn end | Drains remaining verdicts; with blockOn: HIGH (opt-in, default OFF) blocks turn-end on unaddressed HIGH findings or in-flight reviews |

| codex-pair-session (SessionStart / SessionEnd) | Session lifecycle | Announce a paused project (auto-resume only an expired automatic pause, never a manual /codex-pair-pause) and clear debounce state; start/tear down the experimental codex app-server broker only with ASK_CODEX_BROKER=1 |

(The old PreToolUse pre-commit review hook was removed because continuous codex-pair review covers the same need with higher recall.)

## Error Handling

All MCP servers handle errors gracefully:

- **Quota / rate-limit errors:** Automatic fallback to a lighter model for hosted providers that define one (codex GPT-5.6 Sol→Terra, claude opus→sonnet, antigravity Pro→Flash, gemini pro→flash). Grok and Ollama never substitute: Grok preserves explicit harness/model selection; Ollama is local and a missing model returns a clear "ollama pull" error.

- **CLI not found:** Clear error message with installation instructions.

- **Timeout:** Per-provider defaults (codex 800s, claude 600s, grok 600s, Cursor harness 600s, antigravity 300s, ollama 600s, gemini 210s). Resolution order: `ASK_{PROVIDER}_TIMEOUT_MS` > `GMCPT_TIMEOUT_MS` > the provider default.

- **Large responses:** Automatic chunking with fetch-chunk retrieval (Gemini only).

## Environment Variables

| Variable | Default | Description |

|----------|---------|-------------|

| XAI_API_KEY | required for xai-api | xAI credential; never logged/returned |

| ASK_GROK_HARNESS | xai-api | Explicit xai-api or grok-cli selection; no failover |

| ASK_GROK_MODEL | grok-4.6 (API) / grok-build (CLI) | Exact selected-harness Grok model ID |

| ASK_GROK_REASONING_EFFORT | high | low, medium, high, or xhigh |

| ASK_GROK_MAX_OUTPUT_TOKENS | 16384 | xAI API output cap to bound accidental spend |

| ASK_GROK_TIMEOUT_MS | 600000 | Grok API/CLI timeout |

| CURSOR_API_KEY | optional | Cursor CLI credential alternative to agent login |

| ASK_CURSOR_TIMEOUT_MS | 600000 | Model-neutral Cursor Agent harness timeout |

| ASK_GEMINI_MODEL | gemini-3.1-pro-preview | Override the Gemini default model |

| ASK_CODEX_MODEL | gpt-5.6-sol | Override the Codex default model |

| ASK_CODEX_PREFERRED_MODEL | gpt-5.6-sol | Legacy review-tier escape hatch; only attempted separately when it differs from ASK_CODEX_MODEL |

| ASK_CODEX_FALLBACK_MODEL | gpt-5.6-terra | Override the Codex quota fallback model |

| ASK_CODEX_REASONING_EFFORT | medium | Default Codex reasoning effort; per-call reasoningEffort wins |

| ASK_CLAUDE_MODEL | opus | Override the Claude default model |

| ASK_CLAUDE_FALLBACK_MODEL | sonnet | Override Claude Code's native fallback model |

| ASK_OLLAMA_MODEL | qwen3.8:27b | Override the Ollama model (no fallback) |

| ASK_ANTIGRAVITY_MODEL | gemini-3.1-pro | Override the Antigravity base model slug |

| ASK_ANTIGRAVITY_EFFORT | high | Override Antigravity reasoning effort (`low`, `medium`, or `high`) |

| ASK_GEMINI_TIMEOUT_MS | 210000 (210s) | Gemini process timeout |

| ASK_CODEX_TIMEOUT_MS | 800000 (800s) | Codex process timeout |

| ASK_CLAUDE_TIMEOUT_MS | 600000 (600s) | Claude process timeout |

| ASK_OLLAMA_TIMEOUT_MS | 600000 (600s) | Ollama request timeout |

| ASK_ANTIGRAVITY_TIMEOUT_MS | 300000 (300s) | Antigravity process timeout |

| GMCPT_TIMEOUT_MS | (per-provider default) | Cross-provider timeout fallback (lower precedence than ASK_*_TIMEOUT_MS) |

| GMCPT_LOG_LEVEL | warn | Log level: debug, info, warn, error |

| OLLAMA_HOST | http://localhost:11434 | Ollama server address |

### Safety / behavior switches

| Variable | Default | Description |

|----------|---------|-------------|

| ASK_CODEX_LOAD_USER_CONFIG | unset (isolated) | By default @ask-llm/codex-mcp passes `--ignore-user-config` + `--ignore-rules` so your `~/.codex` config, MCP servers, and hooks are NOT loaded. Set to `1` to load them. |

| ASK_GEMINI_REQUIRE_WORKSPACE_TRUST | unset (auto-trust) | By default @ask-llm/gemini-mcp co-emits the workspace-trust env vars so the CWD is trusted. Set to `1` to require explicit workspace trust instead (Gemini blocks untrusted dirs). |

| ASK_ANTIGRAVITY_SANDBOX | 1 (sandboxed) | Antigravity runs `agy` with `--sandbox` by default. Set to `0` to drop the sandbox flag. |

## Links

- Source: https://github.com/Lykhoyda/ask-llm

- Docs: https://lykhoyda.github.io/ask-llm/

- npm (codex): https://www.npmjs.com/package/@ask-llm/codex-mcp

- npm (claude): https://www.npmjs.com/package/@ask-llm/claude-mcp

- npm (antigravity): https://www.npmjs.com/package/@ask-llm/antigravity-mcp

- npm (ollama): https://www.npmjs.com/package/@ask-llm/ollama-mcp

- npm (gemini): https://www.npmjs.com/package/@ask-llm/gemini-mcp

- npm (unified): https://www.npmjs.com/package/@ask-llm/mcp