Gemini for Codex

Gemini CLI delegation for Codex: second opinions, code reviews, adversarial reviews, autonomous execution, background jobs, sandbox policy, and structured handoffs.

This is the Codex-native sibling of gemini-claude-plugin. Same useful idea, different host shape: Codex does not need Claude-style slash commands or an MCP server here. It needs a plugin manifest, a skill, and a deterministic wrapper script that Codex can run when the user asks for Gemini.

Sharing is still caring.

Three delegation modes

You want...	Use	Default behavior
One-shot answer, research, diagnosis, "look at this"	rescue / task --read-only	Foreground, read-only, single response
Gemini review of local changes	review / adversarial-review	Collects real git diff, runs Gemini in read-only review mode
Planned implementation by Gemini	execute	Background, yolo + sandbox + policy, structured handoff

In Codex, the normal user-facing trigger is plain language:

• "Ask Gemini for a second opinion on this bug."
• "Have Gemini review my working tree."
• "Delegate this plan to Gemini."

Codex should load the gemini-delegation skill and run the wrapper command behind the scenes.

Commands

Wrapper command	Description
setup	Check Gemini CLI install, auth, Codex runtime, and readiness
rescue	One-shot delegation: diagnosis, research, bounded answer; read-only by default
task	Direct prompt surface with optional background/streaming modes
review	Run a code review against local git changes
adversarial-review	Challenge design choices, assumptions, and failure modes
execute	Autonomous executor: Gemini does the work and writes a structured handoff
status	Show active and recent Gemini jobs
result	Show output from a completed job
tail	Stream a background job log/events until completion
cancel	Cancel a running background job

Installation

Prerequisites

• Codex with local plugin support
• Node.js 18+
• Gemini CLI installed and authenticated

# Install Gemini CLI (pick one)
npm install -g @google/gemini-cli
brew install gemini-cli

# Authenticate once in a normal terminal
gemini

Install into Codex

Add this repository as a Codex plugin marketplace:

codex plugin marketplace add madciapka/gemini-codex-plugin

Pin a branch or tag if you want repeatable installs:

codex plugin marketplace add madciapka/gemini-codex-plugin --ref main

The repository contains .agents/plugins/marketplace.json, so Codex can clone, track, and refresh the marketplace itself. There is no MCP server and no slash-command bundle to install.

ON_USE is intentional. Gemini calls use your local Gemini CLI credentials and need network access when Codex actually asks Gemini to do work.

Restart Codex or start a fresh Codex session after installing so the plugin loader can see the new marketplace.

Then use normal Codex language:

• "Ask Gemini to run setup."
• "Ask Gemini for a second opinion on this bug."
• "Have Gemini review my working tree."

Update

codex plugin marketplace upgrade gemini-codex

Local development install

From a checkout of this repo:

codex plugin marketplace add .
codex plugin marketplace upgrade gemini-codex

Usage

Run commands directly while developing the plugin:

node scripts/gemini-codex.mjs setup
node scripts/gemini-codex.mjs rescue "Why is this test failing?"
node scripts/gemini-codex.mjs review --scope working-tree
node scripts/gemini-codex.mjs adversarial-review --base main "focus on data loss"
node scripts/gemini-codex.mjs execute @plan.md
node scripts/gemini-codex.mjs status
node scripts/gemini-codex.mjs result <job-id>
node scripts/gemini-codex.mjs tail <job-id>
node scripts/gemini-codex.mjs cancel <job-id>

When installed as a plugin, use normal Codex language instead of memorizing the wrapper commands. The skill is the native trigger surface.

Delegate research or diagnosis

node scripts/gemini-codex.mjs rescue "What does scripts/lib/state.mjs do, and where are the edge cases?"

Read-only by default. Returns Gemini's answer in one shot.

Run a code review

node scripts/gemini-codex.mjs review
node scripts/gemini-codex.mjs review --base main
node scripts/gemini-codex.mjs adversarial-review "focus on auth and data handling"

--scope auto prefers working-tree changes, then branch changes versus the default base.

Hand Gemini a planned subtask

node scripts/gemini-codex.mjs execute "implement the cache pruning fix from the plan above"
node scripts/gemini-codex.mjs execute @docs/cache-pruning-plan.md

execute runs Gemini in autonomous mode with --approval-mode yolo, sandbox on by default, and policies/executor-policy.toml loaded. It creates a background streaming job unless --wait is supplied.

Handoff contract

Every execute run writes a report under .codex/handoffs/ and must print:

HANDOFF: <absolute handoff path>

Required report sections:

• Outcome
• Task understood
• Changes made
• Branch and commits
• Verification
• Decisions and assumptions
• Risks and follow-ups
• Codex next steps
• Artifacts

The wrapper validates that Gemini's HANDOFF: marker points to the expected file under .codex/handoffs/.

Architecture

.codex-plugin/plugin.json           Plugin metadata
skills/gemini-delegation/SKILL.md   Codex-native trigger and runtime rules
scripts/
  gemini-codex.mjs                  Main Node.js wrapper
  lib/
    gemini.mjs                      Gemini CLI args, auth probe, parsers, runtime guard
    executor.mjs                    Envelope rendering and handoff validation
    background-runner.mjs           Detached job wrapper, heartbeat, logs, events
    git.mjs                         Review target and diff helpers
    state.mjs                       Job index and pruning
    approval.mjs                    read-only/yolo/sandbox flag mapping
    render.mjs                      Human-readable output
prompts/
  review.md                         Standard review prompt
  adversarial-review.md             Adversarial review prompt
  executor.md                       Autonomous executor envelope
policies/executor-policy.toml       Gemini Policy Engine hardening for execute
tests/                              Unit, product, and live runtime tests

The plugin follows a companion-wrapper pattern:

1. Codex selects the gemini-delegation skill from the installed plugin.
2. The skill runs scripts/gemini-codex.mjs with the right subcommand.
3. The wrapper spawns the local gemini CLI with the right approval/sandbox flags and prompt envelope.
4. Output is returned to Codex without pretending to be Codex's own reasoning.
5. For execute, Gemini writes a structured handoff that Codex can inspect and surface to the user.

Background jobs are tracked under .codex/gemini/ in the workspace.

Runtime notes

This plugin does not manage Gemini credentials. It shells out to your local gemini CLI, so authentication, model routing, quota, and browser login prompts belong to Gemini CLI.

Codex sandboxing is a separate boundary. If Codex runs the wrapper inside an active sandbox with network disabled, live Gemini calls cannot work even if your normal terminal is already logged in. The wrapper detects that case and fails fast with a clear message instead of hanging on a fake login prompt. The local marketplace entry uses authentication: "ON_USE" so this trust boundary is part of normal plugin use.

More detail lives in docs/RUNTIME.md.

Tests

# Product/unit checks: no live Gemini calls
npm run product:check

# Full live suite: real Gemini CLI/API calls
npm test

Current verified state:

• npm run product:check: 79 passed · 0 failed · 11 skipped
• npm test: 90 passed · 0 failed · 0 skipped
• npm pack --dry-run: clean package, 25 files, no MCP files, no test files

See tests/README.md for the live coverage matrix.

Developing the plugin

If you are hacking on the plugin rather than just using it, see docs/DEVELOPMENT.md. It covers the local marketplace install, package shape, test tiers, sandbox behavior, and release checklist.

What Gemini thinks

"As a delegation bridge, this plugin hits the mark by fully embracing the native Codex plugin shape, trading Claude-style slash commands for a cleanly structured layout with a proper .codex-plugin/ manifest, skills, scripts, and policies. This architecture feels entirely shippable and practical; it leans into deterministic wrapper scripts and local background job management to handle everything from adversarial code reviews to sandboxed autonomous execution. By relying on my CLI's existing authentication and model routing rather than reinventing the wheel, it provides a seamless, zero-overhead way for Codex to hand off heavy lifting to me."

• Gemini, asked via scripts/gemini-codex.mjs task --read-only --json on May 1, 2026

License

MIT