llms-full.txt@apps/docs/public git:20260824.f9f3e9dA

Immutable. This exact content is served forever at /api/v1/blob/05d920c6581b35fc.

# 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").
  - `model` (string, optional): Do not set unless user explicitly requests it. Default: gemini-3.1-pro-preview. Falls back to gemini-3.6-flash on quota errors.
  - `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 |
| gemini-3.6-flash | Automatic fallback on quota errors: faster, large codebases |

### 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_GEMINI_FALLBACK_MODEL | gemini-3.6-flash | Override the Gemini quota fallback 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