ai-plugins-cc

ai-plugins-cc

Claude Code plugins that delegate to external AI CLIs — Codex, Gemini, and Grok — sharing a hardened core and an optional umbrella plugin that dispatches across providers.

Status: active development. The architecture is set; the gemini, grok, and ai umbrella plugins are usable today; the codex-adapter integrates with upstream openai/codex-plugin-cc and ships an installer + canary.

---

What you get

• Per-provider plugins. /gemini:*, /grok:*, and /codex:* (via the upstream plugin) all behave the same way: review changes, rescue a task, run an adversarial pre-stop gate, and queue background work. You install only the providers you want.
• An umbrella plugin. /ai:review, /ai:rescue, /ai:gater route to whichever provider you've configured as your default. /ai:compare fans out the same review to multiple providers and returns a side-by-side report. Both umbrella and per-provider commands ship — different prefixes, no collisions.
• A shared core. All providers run on @ai-plugins-cc/core: one implementation of state management, job lifecycle, hooks, context collection, prompt assembly, rendering. A bug fix in core fixes every provider at once.
• An adapter pattern for external plugins. @ai-plugins-cc/codex-adapter integrates with upstream openai/codex-plugin-cc without vendoring its source. The same pattern is the cutover path when official Gemini and Grok plugins ship — we'll add gemini-adapter / grok-adapter and deprecate the in-house plugins.

---

Installation

You need Node >=20.0.0 and a Claude Code install.

From the marketplace (recommended)

Add the marketplace in Claude Code:

/plugin marketplace add dysfunc/ai-plugins-cc

Install the plugin(s) you want. Three shapes:

A. The umbrella (recommended for most users). One install, all three providers under /ai:*:

/plugin install ai@ai-plugins-cc
/reload-plugins
/ai:setup

ai@ai-plugins-cc ships bundled fallbacks for the gemini and grok runtimes — you don't need to install those plugins separately for /ai:review, /ai:rescue, etc. to work. /ai:setup is the wizard that picks providers, installs CLIs, walks auth, and persists your defaults.

B. A single provider, dedicated slash commands. Install just the provider you want; you get its /<provider>:* surface (e.g. /gemini:review, /grok:rescue) without the umbrella:

/plugin install gemini@ai-plugins-cc      # /gemini:review, /gemini:rescue, /gemini:setup, ...
/plugin install grok@ai-plugins-cc        # /grok:review, /grok:rescue, /grok:setup, ...
/reload-plugins
/gemini:setup                             # or /grok:setup

For Codex, the canonical standalone path is OpenAI's own marketplace — we don't ship a wrapper because OpenAI maintains the upstream plugin directly:

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
/codex:setup

C. Umbrella + per-provider plugins together. Install both the umbrella and one or more per-provider plugins. You get /ai:* cross-provider routing and the per-provider commands. The umbrella prefers the installed sibling plugin's runtime over its bundled fallback when present, so updates to the per-provider plugin propagate immediately.

/plugin install ai@ai-plugins-cc
/plugin install gemini@ai-plugins-cc
/plugin install grok@ai-plugins-cc
/reload-plugins
/ai:setup

Codex is installed by the umbrella's /ai:codex-update command (see Codex setup below). There's no codex@ai-plugins-cc plugin in our marketplace because the canonical codex install lives at openai/codex-plugin-cc (see Path B above for the standalone flow).

Re-run /ai:setup any time, or use /ai:settings to change individual providers later.

From source (development)

git clone https://github.com/dysfunc/ai-plugins-cc.git
cd ai-plugins-cc
npm install

Then point Claude Code at this directory's .claude-plugin/marketplace.json.

Codex setup

Codex is not listed in the marketplace — it's an OpenAI plugin we don't vendor. The umbrella's /ai:codex-update command installs upstream openai/codex-plugin-cc from GitHub into a managed cache directory. Run it once before you use /ai:review --provider=codex:

/ai:codex-update

This downloads the SHA-pinned upstream release, hash-verifies the tarball, and atomic-renames it into ~/.cache/ai-plugins-cc/codex-plugin-cc/.

---

Provider authentication

Provider	Required env var	Fallback / SSO	Where to get a key
Gemini	GEMINI_API_KEY	GOOGLE_API_KEY · interactive gemini auth login (Google account) · gcloud auth application-default login (Vertex AI)	https://aistudio.google.com/
Grok	GROK_API_KEY	XAI_API_KEY	https://console.x.ai/
Codex	OPENAI_API_KEY	CODEX_API_KEY	https://platform.openai.com/

Each provider's setup command (/gemini:setup, /grok:setup, etc.) reports which credential is found and whether the underlying CLI is on PATH.

Node version requirements

This monorepo's own packages need Node >=20.0.0. The provider CLIs we drive have their own minimums:

CLI	Notes
@google/gemini-cli (Gemini)	Node 20+; recent versions track current LTS. Auto-installed by /ai:setup.
Grok	@vibe-kit/grok-cli — Node 18+, ESM, installs the grok binary. Auto-installed by /ai:setup. Avoid the older grok-dev package: it's Bun-targeted and fails under plain Node with Cannot find package "node:diagnostics_channel". /ai:setup runs an idempotent in-place patch (plugins/grok/scripts/patch-grok-cli.mjs, invoked via node ai-companion.mjs grok-patch) that strips a deprecated search_parameters field the bundled client.js sends on every chat call — without it, xAI returns 410 "Live search is deprecated" for accounts without a Live Search license. The patch follows the actual grok binary (resolves GROK_BIN → which grok → npm root -g in priority) and fails closed if the expected pattern isn't present, so an upstream-fixed CLI surfaces explicitly rather than being silently skipped. Re-apply after every npm install -g @vibe-kit/grok-cli upgrade; re-running /ai:setup does that.
Upstream openai/codex-plugin-cc (Codex)	See the upstream's package.json engines field. Installed for you by /ai:codex-update.

---

Usage

Per-provider commands

Every plugin exposes the same surface, scoped to its prefix:

Command	What it does
/<provider>:review [--scope=diff|repo] [--base=REF] [focus]	Review the pending change against main.
/<provider>:rescue <prompt>	Hand a substantial coding task to the provider's agent.
/<provider>:setup	Probe the CLI install and current auth state.
/<provider>:status [--all]	List active and recent jobs.
/<provider>:cancel [job-id]	Cancel a running background job.
/<provider>:result [job-id]	Show a finished job's output.
/<provider>:adversarial-review	Stricter review with explicit blocking criteria.

Umbrella commands

/ai:review [--provider=gemini|grok|codex] [--scope=...] [focus]
/ai:rescue [--provider=...] <prompt>
/ai:gater  [--provider=...]
/ai:compare [--providers=A,B,C] [--action=review|rescue|gater] [--scope=...] [focus]
/ai:codex-update [--tag=vX.Y.Z]

/ai:compare fans the review out to your enabled providers in parallel and returns a single markdown report with one fenced section per provider. A single provider's failure is shown in its section but doesn't abort the others. --action= switches the fanned-out verb (default review); use --action=rescue to ask every provider the same investigation/coding task. While running, each provider's stderr streams through prefixed with [<provider>] so you see live progress instead of a 5–10 minute blank wait. Provider list precedence: explicit --providers= → compareProviders in workspace/user config → enabledProviders in workspace/user config → all registered providers (last is the unconfigured-first-run fallback only).

Provider precedence

Resolved in this order — first hit wins:

1. --provider=ID on the command line.
2. <workspace>/.claude-plugin/ai.json with { "provider": "...", "compareProviders": [...] }.
3. ~/.claude/ai-plugins-cc.json (same shape).
4. AI_PLUGINS_CC_DEFAULT_PROVIDER env var.
5. Default: gemini.

Workspace and user config files are JSON, e.g.:

{
  "provider": "grok",
  "enabledProviders": ["gemini", "grok", "codex"],
  "compareProviders": ["gemini", "grok", "codex"]
}

---

First-run setup

After installing the umbrella plugin, run:

/ai:setup

It walks through:

1. Pick providers. Multi-select across Gemini, Grok, and Codex.
2. Install missing CLIs. For each pick:
   • Gemini: npm install -g @google/gemini-cli (only with your confirmation).
   • Grok: npm install -g @vibe-kit/grok-cli (Node-compatible; the older grok-dev package is Bun-targeted and fails under Node).
   • Codex: downloads the pinned upstream openai/codex-plugin-cc release into a managed cache (no vendoring).
3. Walk through auth. API key or SSO per provider; keys are read from env (never echoed back into chat or written to shell config without consent).
4. Verify each. Per-provider probe runs after every change to confirm ready: true.
5. Save settings. Writes ~/.claude/ai-plugins-cc.json with enabled providers, default, and /ai:compare set.

Re-run /ai:setup at any time to re-verify or change selections; rerun on a fresh machine to bring the new install up to speed.

The first SessionStart on any workspace where settings haven't been written yet emits a one-line nudge: "ai-plugins-cc: no settings yet — run /ai:setup...". The hook never blocks the session.

Changing settings later

/ai:settings                              # interactive — show + edit
/ai:settings show                         # current state
/ai:settings enable codex                 # add codex to active providers
/ai:settings disable grok                 # remove (rolls default forward if needed)
/ai:settings set-default gemini           # change /ai:review's provider
/ai:settings set-compare gemini,codex     # ordered list for /ai:compare fan-out

Every mutation writes ~/.claude/ai-plugins-cc.json atomically (temp file + rename). Disabling the current default automatically reassigns it to the first remaining enabled provider; the change is visible in the JSON output of every settings command.

---

Architecture

ai-plugins-cc/
├── packages/
│   ├── core/             @ai-plugins-cc/core
│   │                     state · process · git · context · render · job-control
│   │                     tracked-jobs · workspace · fs · args · hooks · config
│   │                     The boundary every provider runs on.
│   │
│   ├── shared-prompts/   @ai-plugins-cc/shared-prompts
│   │                     Canonical prompt templates and review-output schema.
│   │
│   └── codex-adapter/    @ai-plugins-cc/codex-adapter
│                         discover · install · invoke · normalize
│                         Wraps upstream openai/codex-plugin-cc; never vendors it.
│
├── plugins/
│   ├── gemini/           @ai-plugins-cc/gemini    (in-house Claude Code plugin)
│   ├── grok/             @ai-plugins-cc/grok      (in-house Claude Code plugin)
│   └── ai/               @ai-plugins-cc/ai        (umbrella; depends on the others)
│
├── scripts/
│   ├── check-core-changeset.mjs   CI gate: core PRs require a changeset entry
│   └── codex-canary.mjs           Daily install→invoke against pinned upstream
│
└── .github/workflows/
    ├── ci.yml                     Matrix tests + changeset enforcement + release
    └── codex-canary.yml           Auto-files an issue on upstream contract drift