@ask-llm/plugin

Canonical Claude Code, Cursor Agent, and Pi host package for AI-to-AI collaboration

One publishable package that adds multi-provider code review, comparison, brainstorming, verification, image, and pairing workflows to Claude Code, Cursor Agent, and Pi. The hosts consume one skill corpus and package version; host-specific behavior is kept in explicit adapters.

Part of the Ask LLM monorepo.

Installation

From Marketplace

/plugin marketplace add Lykhoyda/ask-llm
/plugin install ask-llm@ask-llm-plugins

After installing or upgrading, fully restart Claude Code (quit and reopen) so the codex-pair PostToolUse hook registers. Claude Code binds hooks at session start; /reload-plugins refreshes the plugin cache but does not re-register hooks in a pre-existing session, so codex-pair won't auto-fire on edits until you restart (see #74). Run /codex-pair afterwards to confirm the hook is wired up.

MCP Servers

The recommended cross-provider server is @ask-llm/mcp. Keep npx -y @ask-llm/mcp as the primary registration; npm install -g @ask-llm/mcp is a first-class alternative when you want a pinned global binary. Split provider packages (@ask-llm/codex-mcp, @ask-llm/grok-mcp, and the others) remain an advanced optimization for a richer per-provider tool surface.

The plugin bundles only the Codex MCP registration under Claude Code's plugin namespace. After installation or upgrade, fully restart Claude Code and run /mcp; plugin:ask-llm:codex should be connected. Codex-facing workflows prefer that bundled ask-codex leaf (or a user-scoped ask-codex), then a fully pinned unified ask-llm call (provider: "codex" plus model and Codex options), then the disclosed codex exec fallback. An older unified schema that cannot honor those options is reported rather than stripped.

/grok-pair does not add servers to the plugin. Register the unified Ask LLM server at user scope (the recommended install: it exposes ask-cursor-agent for the Cursor Agent route plus the unified ask-llm tool, which pair skills call only fully pinned) and, optionally, the split Grok server for the ask-grok leaf:

claude mcp add --scope user ask-llm -- npx -y @ask-llm/mcp
# first-class alternative after `npm install -g @ask-llm/mcp`:
# claude mcp add --scope user ask-llm -- ask-llm-mcp
claude mcp add --scope user grok -- npx -y @ask-llm/grok-mcp

Existing user-scoped Codex registrations remain compatible and keep their shorter names. Other providers are registered explicitly at user scope only when you want their split leaves:

claude mcp add --scope user gemini -- npx -y @ask-llm/gemini-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

If Codex is missing entirely, provision the unified server first (claude mcp add --scope user ask-llm -- npx -y @ask-llm/mcp) or the split Codex leaf with claude mcp add --scope user codex -- npx -y @ask-llm/codex-mcp. If /mcp shows the bundled registration but it is disconnected, run npx -y @ask-llm/mcp doctor and restart Claude Code. /sol-review preserves source-plugin and session-local MCP/settings context when reading the active claude mcp list inventory, reports missing, unavailable, and unsupported-schema states separately, and discloses the explicit codex exec fallback after failed health, an incomplete unified schema, or MCP transport failure.

Cursor Agent

Cursor's supported Agent Skills surface exposes exactly /codex-pair and /grok-pair (the manifest sets agents: [], commands: [], and hooks: {} so Claude agents and the Claude-format hooks file are never auto-discovered, and the other skills stay Claude/Pi-only until they get Cursor adapters); its MCP surface is mcp.json, which bundles only the unified ask-llm server. For a source checkout:

agent --plugin-dir ./packages/claude-plugin

/codex-pair requires explicit model= and effort= values before consent, then uses a separately user-installed ask-codex leaf when exposed, otherwise the bundled unified ask-llm fully pinned (provider: "codex", model, effort, include directories, sandbox, session), with resumable Thread ID, cancellation, and result relay. It never guesses MCP-process environment defaults and does not pretend Claude-only hooks are active. /grok-pair gives Cursor-native .cursor/mcp.json and Tools & MCP reload guidance; it never sends Cursor users to claude mcp add. If installing only MCP configuration, the recommended minimal entry is ask-llm → npx -y @ask-llm/mcp in project .cursor/mcp.json or user ~/.cursor/mcp.json (keep one registration per server — do not duplicate it when the plugin is loaded); add codex → @ask-llm/codex-mcp or grok → @ask-llm/grok-mcp only when you specifically want their ask-codex/ask-grok leaves, then reload MCP/restart Cursor Agent. When Cursor hosts /grok-pair, it never recursively invokes Cursor Agent.

Pi

pi install npm:@ask-llm/plugin
pi list

Pi discovers the portable skills as /skill:<name> commands and registers native ask-codex, ask-gemini, ask-grok, ask-ollama, ask-antigravity, model-neutral ask-cursor-agent, and bounded concurrent ask-multi tools. Pi intentionally has no built-in MCP client; do not configure these as MCP servers in Pi. fable-review and grok-pair are excluded from Pi discovery; Grok pairing currently has Claude/Cursor adapters, while Pi retains its dedicated Codex pairing lifecycle.

The plugin's ask-gemini-run, Gemini reviewer agent/skill, and Pi ask-gemini tool all delegate to the canonical Gemini executor: gemini-3.1-pro-preview remains primary and quota errors fall back to gemini-3.8-flash unless ASK_GEMINI_FALLBACK_MODEL overrides it.

For codex-pair, create .codex-pair/context.md, ensure Pi trusts the project, then run interactive /codex-pair to grant user-owned canonical-project consent. The marker alone never authorizes data transfer/cost. Revoke with /codex-pair revoke. Pi findings are non-blocking; blocking Stop-gate and one-shot print parity are not available.

pi update npm:@ask-llm/plugin
pi remove npm:@ask-llm/plugin

See the Pi host guide for security, provider authentication, project-local/temporary installs, lifecycle semantics, and troubleshooting.

Skills

Command	Description
/multi-review	Parallel Gemini + Codex review with 4-phase validation pipeline and consensus highlighting
/gemini-review	Gemini-only code review with confidence filtering
/codex-review	Codex-only code review (precision-first, ≥80 confidence — default for routine PR review)
/fable-review	Isolated, read-only review requesting native Fable, with runtime verification limits disclosed
/sol-review	Model-pinned GPT-5.6 Sol review: prefer bundled or user-scoped ask-codex, then fully pinned unified ask-llm, then the disclosed CLI fallback
/ollama-review	Local review — no data leaves your machine
/brainstorm	Explicit multi-model brainstorm (default external: Antigravity + Codex); supports an exact no-Gemini Grok + GPT-5.6 Sol panel through Cursor Agent
/grok-review	Grok review through explicit xAI API or Grok CLI harness; no fallback
/grok-pair	Consent-gated iterative Grok reviewer through exact Cursor Agent, xAI API, or Grok CLI route; no fallback
/codex-pair	Claude/Pi per-edit pairing dashboard; Cursor on-demand session adapter with explicit Thread ID continuity
/brainstorm-all	Brainstorm with all five external providers (Gemini, Codex, Grok, Ollama, Antigravity) + Claude Opus research
/compare	Side-by-side raw responses from multiple providers (no synthesis, no consensus extraction)

Exact Grok + GPT-5.6 Sol brainstorm

The preferred architect panel routes both models through the model-neutral Cursor Agent harness with provider and exact account-catalog ID kept separate:

/brainstorm grok@cursor-agent:cursor-grok-4.6-high,codex@cursor-agent:gpt-5.6-sol-high "review this architecture"

This panel calls exactly Grok and GPT-5.6 Sol—never Gemini. Cursor Auto, model rewriting, and harness/provider fallback are forbidden. If one participant fails, the result is partial and cannot be presented as two-model consensus. Catalogs are account-specific; confirm these exact IDs with agent --list-models and replace an unavailable ID explicitly.

Official Grok Build remains an explicit alternative when its installed headless contract is supported:

/brainstorm grok@grok-cli:grok-build,codex@cursor-agent:gpt-5.6-sol-high "review this architecture"

A Grok CLI failure remains a Grok CLI failure; the workflow does not pivot to Cursor or xAI.

Agents

Agent	Color	Description
gemini-reviewer	cyan	4-phase: context, prompt, synthesis, validation
codex-reviewer	green	4-phase: context, prompt, synthesis, validation
fable-reviewer	purple	Fable-requested review with source-verified findings
sol-reviewer	blue	GPT-5.6 Sol review through Codex with source validation
ollama-reviewer	yellow	4-phase: context, prompt, synthesis, validation (local)
brainstorm-coordinator	magenta	Source-grounded research + parallel multi-model consultation; exact two-model mode keeps the host non-voting and partial failures out of consensus

Hooks

Hook	Trigger	Action
PreToolUse	Before git commit	Reviews staged changes via Gemini, warns about critical issues
PostToolUse	After Edit/Write/MultiEdit	Runs codex-pair review IF .codex-pair/context.md marker file is present in the project (opt-in, ADR-077; layout per ADR-092)
Stop	Turn-end	Blocks turn-end while unaddressed HIGH codex-pair findings remain — opt-in default OFF, enabled via blockOn: HIGH in .codex-pair/context.md frontmatter; zero new LLM calls (reads log.jsonl); defer findings with /codex-pair-ack <hash> "<reason>" (ADR-118)

Enabling codex-pair mode

codex-pair has two surfaces: a PostToolUse hook that runs continuously after every file edit when opted in (the workhorse), and a /codex-pair slash command for setup-and-status (the human-facing dashboard). The hook is the recall-first complement to /codex-review. In the four-task benchmark from ADR-077 (four structurally different task types — CRUD endpoint, URL shortener, RFC-spec implementation, stateful business logic — chosen so the result would generalize, not be a fluke of one domain): Claude alone caught 2 of 10 probes; Claude + /codex-review caught 7 of 10; Claude + codex-pair caught 10 of 10. The three probes /codex-review missed exemplified the "looks fine, runs wrong" class its ≥80-confidence precision filter structurally suppresses — code that compiles and type-checks but produces wrong results at runtime because of an implicit invariant the model couldn't infer from a single file. The recall improvement is task-agnostic; it reproduced across all four task types, not just the headline one. Subsequent lived-experience audit in ADR-095 confirms the benchmark holds in real flow.

The hook is loaded by default but self-gates on a marker file. Without the marker, every edit triggers one fs.access() call and exits — zero codex calls, zero cost.

To enable for a project:

mkdir -p .codex-pair
cat > .codex-pair/context.md <<'EOF'
# .codex-pair/context.md

This is a payment-processing service. Currency must use integer cents
(floats lose precision on every charge). Concurrent requests are real.
URL inputs are untrusted.

[Add domain invariants Codex can't infer from one file — e.g.
"all routes check user.role", "handler must be idempotent under retry".]
EOF

Do not commit .codex-pair/ — gitignore it. The hook ships with the plugin (project policy); the marker is each developer's own activation switch and review context. A single .codex-pair/ line in .gitignore covers the marker, log, cache, and all state files (see ADR-092).

Once present, every Edit/Write/MultiEdit triggers a Codex review of the file with the marker's content as project context. HIGH and MED concerns appear to Claude as system reminders on the next turn; LOW concerns are logged to .codex-pair/log.jsonl but suppressed from surfacing.

To disable:

Goal	Mechanism
Permanently for this project	rm -rf .codex-pair/
Just this session	/plugin disable ask-llm
Just this command	CODEX_PAIR_DISABLED=1 <command>

Usage characteristics: GPT-5.6 Sol by default with Terra quota fallback; ~13–50s per file. Files >20KB skipped (override with CODEX_PAIR_MAX_FILE_BYTES). node_modules/dist/lockfiles/images skipped automatically.

When to enable: any project where missed correctness issues cost more than the per-edit review (~$0.04–0.07). The decision is about code characteristics, not domain — codex-pair catches bugs earlier wherever a project has implicit invariants the model can't infer from one file in isolation (which most projects do, somewhere). When NOT to enable: routine refactors, glue code, simple CRUD where /codex-review at PR time is sufficient (~1/4 the cost). The four-task benchmark in ADR-077 has the full task-agnostic evidence trail; ADR-095 is the lived-experience replication on this very repo.

Requirements

• Claude Code, Cursor Agent, or Pi 0.83.0+ installed
• Claude Code installed for marketplace agents, hooks, independent Fable review, and the blocking Stop gate
• Gemini CLI authenticated — required for hooks and Gemini features
• Codex CLI — required for /codex-review and direct-Codex brainstorm routes
• Cursor Agent CLI authenticated with exact catalog IDs — required only for @cursor-agent brainstorm routes
• Ollama running locally — required for /ollama-review

Documentation

Full docs at lykhoyda.github.io/ask-llm/plugin/overview

License

MIT