claude-codex-gemini

Multi-AI Development Pipeline

A cross-platform development pipeline orchestrating Gemini, Claude, and Codex for autonomous planning, implementation, and review.

Installation

Quick Start (Recommended)

In your existing project:

bunx claude-codex-gemini init
# or with npm
npx claude-codex-gemini init

This creates:

• .multi-ai-pipeline/ - Pipeline orchestration files
• Updates GEMINI.md - Adds pipeline reference
• Updates .gitignore - Adds .task/
• Creates .task/ - Pipeline state directory

Manual Installation

Clone the repo and copy the necessary files manually:

git clone https://github.com/Z-M-Huang/claude-codex-gemini.git

Architecture

• Gemini - Orchestrator (makes decisions, delegates work)
• Claude Code - Agent executor (requirements, planning, implementation)
• Codex - Final gate reviewer (independent quality assurance)
• Bun + TypeScript - Cross-platform, no external dependencies, works on Windows/macOS/Linux

Quick Start

Prerequisites

• Bun - Runtime for TypeScript scripts Install from https://bun.sh (see site for platform-specific instructions)

• Claude CLI - AI agent executor

  # Install from https://claude.com/claude-code
  npm install -g @anthropic-ai/claude-cli
  claude auth
  

• Codex CLI - Final review gate

  # Install from https://codex.openai.com
  npm install -g @openai/codex-cli
  codex auth
  

• Gemini CLI - Orchestrator

  # Available at https://ai.google.dev/gemini-api/docs/cli
  

Usage

• Tell Gemini what you want:

  "Add authentication to the API"
  

• Gemini orchestrates the pipeline:

  • Requirements gathering (Opus)
  • Planning (Opus)
  • Sequential plan reviews (Sonnet → Opus → Codex)
  • Implementation (Sonnet)
  • Sequential code reviews (Sonnet → Opus → Codex)

• Review results: All outputs are in .task/ directory as JSON files.

Pipeline Phases

The pipeline auto-detects the current phase by checking which .task/*.json files exist:

Requirements → Planning → Plan Review → Implementation → Code Review → Complete
                             ↓                              ↓
                 (Sonnet → Opus → Codex)       (Sonnet → Opus → Codex)

Phase Detection

File Missing	Phase	Agent
user-story.json	Requirements	requirements-gatherer (Opus)
plan-refined.json	Planning	planner (Opus)
review-sonnet.json	Plan Review (Sonnet)	plan-reviewer (Sonnet)
review-opus.json	Plan Review (Opus)	plan-reviewer (Opus)
review-codex.json	Plan Review (Codex)	codex-reviewer
impl-result.json	Implementation	implementer (Sonnet)
code-review-sonnet.json	Code Review (Sonnet)	code-reviewer (Sonnet)
code-review-opus.json	Code Review (Opus)	code-reviewer (Opus)
code-review-codex.json	Code Review (Codex)	codex-reviewer

Cross-Platform Scripts

All operations use these 3 TypeScript scripts (Windows/macOS/Linux):

1. json-tool.ts

Cross-platform JSON operations for state management:

bun scripts/json-tool.ts get .task/state.json .status
bun scripts/json-tool.ts set .task/state.json status=implementing
bun scripts/json-tool.ts set .task/state.json +iterations.plan_review_sonnet

2. run-claude-code.ts

Spawns Claude CLI with agent context:

bun scripts/run-claude-code.ts \
  --agent-file agents/planner.md \
  --output .task/plan-refined.json \
  --model opus \
  --instructions "Create implementation plan"

Features:

• Automatic standards injection
• Platform-aware spawning (shell: true on Windows, false on Unix)
• Output validation

3. run-codex.ts

Wraps Codex CLI for reviews:

bun scripts/run-codex.ts --type plan
bun scripts/run-codex.ts --type code --timeout 1800

Features:

• Type-scoped session management (.codex-session-plan, .codex-session-code)
• Auto-retry on session expiry
• Schema validation

Review Chain

Reviews happen sequentially (NOT parallel) for quality gates:

Plan Review: Sonnet → Opus → Codex Code Review: Sonnet → Opus → Codex

Each reviewer must approve before proceeding. If needs_changes, Gemini fixes and re-reviews (max 10 iterations per reviewer).

Review Statuses

• approved - No blocking issues, proceed
• needs_changes - Issues found, must fix
• needs_clarification - Ask user for clarification
• rejected - Fundamental flaws (Codex only, terminal for plans)

Custom Agents

6 specialized agents in agents/ directory:

Agent	Model	Purpose
requirements-gatherer	Opus	Gather user requirements
planner	Opus	Create implementation plans
plan-reviewer	Sonnet/Opus	Review plans
implementer	Sonnet	Implement plans
code-reviewer	Sonnet/Opus	Review code
codex-reviewer	Codex	Final gate reviews

State Management

All pipeline state lives in .task/:

.task/
├── state.json                   # Pipeline state, iteration counters
├── user-story.json             # Requirements
├── plan-refined.json           # Implementation plan
├── review-sonnet.json          # Sonnet's plan review
├── review-opus.json            # Opus's plan review
├── review-codex.json           # Codex's plan review
├── impl-result.json            # Implementation results
├── code-review-sonnet.json     # Sonnet's code review
├── code-review-opus.json       # Opus's code review
├── code-review-codex.json      # Codex's code review
├── .codex-session-plan         # Codex plan review session marker
└── .codex-session-code         # Codex code review session marker

Iteration Tracking

Gemini tracks iterations in .task/state.json to prevent infinite loops:

{
  "iterations": {
    "plan_review_sonnet": 2,
    "plan_review_opus": 1,
    "plan_review_codex": 3,
    "code_review_sonnet": 0,
    "code_review_opus": 0,
    "code_review_codex": 0
  }
}

Max iterations: 10 per reviewer

If a reviewer hits 10 iterations, Gemini escalates to user (likely conflicting requirements).

Documentation

• GEMINI.md - Orchestrator instructions (Gemini reads this)
• CLAUDE.md - Agent context (Claude reads this)
• AGENTS.md - Final gate reviewer context (Codex reads this)
• docs/standards.md - Review criteria (OWASP, error handling, quality)
• docs/workflow.md - Detailed architecture
• agents/*.md - Agent behavior definitions

Session Management

Codex sessions are automatically managed per review type:

• .task/.codex-session-plan - Plan review sessions
• .task/.codex-session-code - Code review sessions

Benefits:

• First review: Fresh Codex session
• Subsequent reviews: Automatic resume with context
• Session expired: Auto-retry without resume
• Type-scoped: Plan sessions don't affect code sessions

Differences from V0

• No bash scripts - All TypeScript, cross-platform
• No external JSON tools - json-tool.ts handles all JSON operations natively
• Sequential reviews - Quality gates instead of parallel (Sonnet → Opus → Codex)
• File-system-as-state - Phase detection via file existence
• Type-scoped sessions - Separate Codex sessions for plan vs code reviews
• Unified agent files - All agent behavior in agents/ directory
• Needs clarification - Reviewers can pause to ask user questions

Note: The previous bash-based V0 version is available in the archive-v0 branch.

Contributing

When contributing:

• Use path.join() for all file paths (never string concat with '/')
• Test on Windows, macOS, and Linux
• Follow docs/standards.md for code quality
• Ensure scripts work with Bun runtime

License

GPL-3.0 — see LICENSE for details.

Links

• Upstream Project: claude-codex - Codex CLI wrapper plugin
• Claude CLI: https://claude.com/claude-code
• Codex CLI: https://codex.openai.com
• Bun Runtime: https://bun.sh