ccgx-workflow — Claude × Codex × Gemini Multi-Model Collaboration

Project Lineage

ccgx-workflow is a deep rewrite of ccg-workflow v3.x.
The original project went unmaintained after 2026-05 (the original author's
GitHub homepage went offline), leaving its multi-model collaboration users
exposed to drift. This project re-architected from v4.0 onward:
fresh-context subagent protocols, Plan-Critic-Verify quality tiers,
OS-level three-layer process isolation, broker tx_id anti-drift,
and 8 plugin patches with a one-shot repatch script.

The /ccg:* slash command palette is gesture-compatible with the
original — but the underlying architecture has been completely replaced.
Original copyright is preserved under MIT, see LICENSE.

What Is It

A multi-model collaboration system where Claude Code orchestrates Codex (backend) and Gemini (frontend). Frontend tasks auto-route to Gemini, backend tasks to Codex, Claude handles orchestration and code review.

External models have no write access — they only return patches; Claude reviews before applying.

Claude Code (Orchestrator)
       │
   ┌───┴───┐
   ↓       ↓
Codex   Gemini
(Backend) (Frontend)
   │       │
   └───┬───┘
       ↓
  Unified Patch

Core Features

• Zero-config model routing — Frontend → Gemini / Backend → Codex, dispatched by phase frontmatter Type: field. No manual switching.
• ~30 /ccg:* slash commands — Planning, execution, git workflow, code review, autonomous long-runs, async job triplet.
• Three-tier quality gates — --quality=fast|triple|debate toggles Plan-Critic-Verify collaboration depth.
• Fresh-context subagent protocol — phase-runner / code-fixer / debug-session-manager keep main-thread context ≤15%; the orchestrator only consumes ≤200-token summaries.
• OS-level three-layer process isolation — Bash(claude -p --agent ccg/phase-runner) replaces in-process sidechain; treats main-process RSS leak.
• OPSX spec-driven — Integrates OPSX to convert vague requirements into verifiable constraints, eliminating AI improvisation.
• Plugin-first with wrapper fallback — Uses official codex/gemini plugins when available; falls back to codeagent-wrapper.

Quick Start

Prerequisites

Installation

npx ccgx-workflow

First run prompts for language (English / Chinese), API provider, MCP tooling — all interactive. CLI command name remains ccg (preserves muscle memory for legacy users).

Install jq

# macOS
brew install jq

# Linux (Debian/Ubuntu)
sudo apt install jq

# Linux (RHEL/CentOS)
sudo yum install jq

# Windows
choco install jq   # or: scoop install jq

Install Claude Code

npx ccgx-workflow menu  # Select "Install Claude Code"

Supports npm / homebrew / curl / powershell / cmd.

Enabling Multi-Model Collaboration (codex / gemini plugins)

ccgx-workflow calls codex and gemini through Claude Code's official plugin mechanism, no longer relying on the legacy codeagent-wrapper binary. Install plugins to unlock full dual-model parallel capability.

Install (run inside Claude Code)

/plugin install codex@openai-codex
/plugin install gemini@google-gemini

The @ suffix is the marketplace identifier. If a marketplace isn't configured, run /help plugin inside Claude Code to see local marketplace management commands, or refer to Claude Code plugin docs.

Upstream plugin repos (for troubleshooting / issue reports):

• codex: openai-codex marketplace (Claude Code official)
• gemini: sakibsadmanshajib/gemini-plugin-cc

Verify

ls ~/.claude/plugins/cache/openai-codex/codex/
ls ~/.claude/plugins/cache/google-gemini/gemini/
# Should show version directories (e.g. 1.0.4 / 1.0.1)

⚠️ Gemini plugin Windows Known Issues (patch strongly recommended)

gemini@google-gemini v1.0.1 has 8 spawn sites missing windowsHide: true on Windows, causing:

• Brief cmd black flashes that steal application focus on every plugin call (high-frequency)
• ENOENT errors when ACP broker spawns gemini.cmd (serialized as [object Object] by plugin error handlers)
• Flashes during broker daemon startup, gemini --version health checks, taskkill, where gemini, etc.

ccgx-workflow ships a one-shot repatch script (idempotent, re-runnable):

node ~/.claude/.ccg/scripts/repatch-gemini-plugin.mjs

Behavior:

1. Auto-locates plugin version directory
2. Probes each patch site (string match)
3. Already-patched sites: [SKIP]; unpatched sites: [APPLY]
4. Prints broker-daemon-restart command on completion

⚠️ Important: After every claude plugin update gemini@google-gemini, the plugin update overwrites cache — rerun the patch script.

⚠️ Restart broker daemon after patching (old daemon still runs unpatched code):

# Windows PowerShell
Get-CimInstance Win32_Process -Filter "Name='node.exe'" |
  Where-Object { $_.CommandLine -match 'acp-broker' } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force }

Or simpler: /plugin disable gemini@google-gemini then /plugin enable gemini@google-gemini.

Root causes, temporary patches, and upstream paths for all 8 issues are documented in .ccg-migration/PLUGIN-PATCHES.md. Upstream PR is in progress; once merged, the patch becomes a no-op.

Relationship to ccg-workflow

ccgx-workflow is not a fork. The upstream ccg-workflow public release line stopped at v3.x and has been unmaintained since 2026-05. ccgx-workflow v1.0 was redesigned from scratch on top of v3.x (~3 days / 92 commits / 1141 new tests of dense iteration before stabilization).

What's New (vs v3.x)

🆕 New Commands

🚀 Enhanced Commands

🤖 New Agents (vs v3.x's 7)

Fresh-context protocol group (4 agents; main thread receives ≤200-token summary):

Specialist matrix (8 agents, role × layer 2D dispatch):

Plus the 7 core agents inherited from v3.x design (planner / ui-ux-designer / init-architect / get-current-datetime / team-architect / team-qa / team-reviewer), ccgx-workflow has 19 sub-agents total.

🔧 New Mechanisms / Infrastructure

📦 Skill Ecosystem

ccgx-workflow inherits the Skill Registry mechanism (frontmatter-driven auto command generation) with:

• Quality gates — 4: verify-{change, quality, security, module} (still callable as skills after merging into /ccg:verify)
• Tool skills — 6: gen-docs / health / map-codebase / extract-learnings / forensics / override-refusal
• Domain knowledge bundles — 10 categories, ~21 SKILL.md (security / architecture / devops / ai / development / frontend-design, etc.; all user-invocable: false, keyword-routed auto-Read)
• Impeccable UI/UX toolkit — 20 (adapt / animate / arrange / audit / bolder / clarify / colorize / critique / delight / distill / extract / harden / normalize / onboard / optimize / overdrive / polish / quieter / typeset, etc.; optional install)
• scrapling: web scraping with Cloudflare / WAF bypass
• orchestration/multi-agent: coordination SKILL

Total: 47 SKILL.md files + 50+ supporting markdowns = 100+ skill files.

Comparison Table

Core differences at a glance:

Migration

See MIGRATION-FROM-CCG-WORKFLOW.md. One-liner:

npm uninstall -g ccg-workflow            # if installed globally
npx ccgx-workflow                        # reinitialize

/ccg:* commands, .context/ state, .ccg/roadmap.md are all preserved — no code changes or project state rebuild required.

Commands

Development Workflow

Analysis & Quality

Async Job Triplet

OPSX Spec-Driven

Agent Teams

Prerequisite: Enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json.

Git Tools

Project Setup

Configuration

Directory Layout

~/.claude/
├── commands/ccg/       # ~30 slash commands
├── agents/ccg/         # 19 sub-agents
├── skills/ccg/         # Quality gates + 10 domain bundles + impeccable + orchestration
├── bin/codeagent-wrapper  # Fallback path (when plugins absent)
└── .ccg/
    ├── config.toml
    ├── scripts/
    │   └── repatch-gemini-plugin.mjs   # ⭐ one-shot patch
    └── prompts/
        ├── codex/      # 6 Codex expert prompts
        └── gemini/     # 7 Gemini expert prompts

Environment Variables

In ~/.claude/settings.json under "env":

MCP

npx ccgx-workflow menu  # Select "Configure MCP"

Code retrieval (pick one):

• fast-context (recommended) — Windsurf Fast Context, AI-powered, no full-repo indexing
• ace-tool — search_context (official / community proxy)
• ContextWeaver — Local hybrid search, requires SiliconFlow API Key (free)

Optional: Context7 (auto-installed, library docs) / Playwright / DeepWiki / Exa.

Update / Uninstall

# Update
npx ccgx-workflow@latest             # npx users
npm install -g ccgx-workflow@latest  # global npm users

# Uninstall
npx ccgx-workflow                    # select "Uninstall"
npm uninstall -g ccgx-workflow       # global npm users need this extra step

FAQ

Codex CLI 0.80.0 process does not exit

In --json mode, Codex doesn't auto-exit after output completion.

Fix: Set CODEAGENT_POST_MESSAGE_DELAY=1.

I'm coming from ccg-workflow — does ccgx-workflow drop in?

Yes. /ccg:* palette is fully compatible. .context/ state and .ccg/roadmap.md are preserved. See MIGRATION-FROM-CCG-WORKFLOW.md.

Why is the CLI command ccg and not ccgx?

Preserving ccg keeps legacy aliases, scripts, and docs working with zero changes — /ccg:* palette and the ccg CLI are both muscle memory. The package name ccgx-workflow exists to disambiguate the npm namespace; the CLI binary remains ccg.

What happens to the Gemini patch when upstream fixes it?

ccgx-workflow tracks upstream plugin versions. Once fixes land upstream, the repatch script auto-skips already-fixed sites via probe detection ([SKIP]) — no side effects. A ccgx-workflow release will mark "upstream fixed, patch is now a no-op" at that point.

Contributing

PRs and issues welcome. This project is MIT-licensed; submitting code constitutes consent to release under MIT.

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Credits

ccgx-workflow stands on the shoulders of ccg-workflow. Thanks to fengshao1227 and the original contributors.

• ccg-workflow v1.x – v3.x — original project (fengshao1227)
• gsd-build/get-shit-done — fresh-context subagent protocol, context monitor, code-fixer worktree closed loop, debug session manager — multiple architectural inspirations
• cexll/myclaude — codeagent-wrapper inspiration
• UfoMiao/zcf — git tooling inspiration
• GuDaStudio/skills — routing design

License

MIT — see LICENSE (dual copyright: original author fengshao1227 + maintainer wangzy).

v1.0.0 | Issues | Migration from ccg-workflow