Collaborating with Gemini

Use Gemini CLI as a collaborator while Codex remains the primary implementer.

The bridge script (scripts/gemini_bridge.py) wraps gemini -p (headless mode), returns structured JSON, and manages session continuity via SESSION_ID.

Safety

Gemini can read and write files in the workspace by default. The bridge does not restrict this.

To limit what Gemini can do:

• --sandbox — blocks shell commands and file writes. Recommended for review/consultation tasks.
• Include OUTPUT: Unified Diff Patch ONLY. Do not modify any files. in your prompt when requesting code changes. This is a convention, not enforced.

⚠️ --approval-mode plan does NOT reliably prevent writes — Gemini may self-approve plans and use shell commands to bypass file-write restrictions. Do not rely on it for safety.

When to use

• Second opinion on design tradeoffs, edge cases, or test gaps.
• Web search and research (Gemini has built-in grounding).
• Reviewing a diff or proposing changes as unified diff.
• Screenshot / image analysis.

When not to use

• Trivial one-shot tasks — do them in Codex directly.
• Tasks requiring file edits — Codex edits, Gemini advises.
• Anything involving secrets, private keys, or prod data.

Quick start

⚠️ Backticks in prompts trigger shell command substitution — use a heredoc. See references/shell-quoting.md.

PROMPT="$(cat <<'EOF'
Review src/auth.py around login() and propose fixes.
OUTPUT: Unified Diff Patch ONLY.
EOF
)"
python3 .codex/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
  --cd "." --PROMPT "$PROMPT"

Returns: { "success": true, "SESSION_ID": "...", "agent_messages": "..." }

Multi-turn sessions

Capture SESSION_ID from the first call and pass it back:

# Turn 1
python3 .codex/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
  --cd "." --PROMPT "Analyze the bug in foo()."

# Turn 2 — resume
python3 .codex/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
  --cd "." --SESSION_ID "<id>" --PROMPT "Propose a fix as unified diff."

Sessions are persisted by the Gemini CLI at ~/.gemini/tmp/<project>/chats/. The bridge captures and returns the ID — the caller is responsible for storing and reusing it.

Bridge flags

Default timeout: set timeout_ms to 600000 (10 min) when invoking via Codex command runner.

Prompting patterns

Use assets/prompt-template.md for structured starters. Key principles:

• Point, don't paste — give file paths and line numbers, not code blocks.
• One objective per prompt — multiple competing goals produce noisy output.
• Enforce output format — append OUTPUT: Unified Diff Patch ONLY. for code changes.
• Leverage grounding — Gemini can search the web; ask for research when needed.

Screenshots

Gemini can only read files inside the workspace. Copy clipboard PNGs into .codex_uploads/ first:

mkdir -p .codex_uploads && cp "${TMPDIR:-/tmp}"/codex-clipboard-*.png .codex_uploads/

Do not add .codex_uploads/ to .gitignore — Gemini refuses to read ignored paths. Delete screenshots when done.

Verification

• Smoke test: python3 .codex/skills/collaborating-with-gemini/scripts/gemini_bridge.py --help
• Session test: run one prompt, confirm JSON contains success: true and a SESSION_ID.

Collaboration State Capsule

Keep this block updated while collaborating:

[Gemini Capsule] Goal: | SID: | Files: | Last: | Next:

References

• Prompt template — structured prompt patterns
• Shell quoting — heredoc quoting for backticks