Content
Coder-Codexini (CCG)
<div align="center">
[](README_EN.md)
aude + Coder + Codex + Gemini Multi-Model Collaboration Framework**
Let **Claude/Sisyphus** act as the architect to dispatch **Coder** to execute code tasks, **Codex** to review code quality, and **Gemini** to provide expert consultation,<br>forming an **automated multi-party collaboration loop**.
**Supports Claude Code (MCP) and OpenCode (Oh-MyCode) two operating environments**
[Quick Start](#-quick-start) • [Core Features](#-core-features) • [Architecture](#-architecture) • [Tool Details](#️-tool-details) • [OpenCode Configuration](#-opencode-configuration)
</div>
---
## Features
CCG efficient, low-cost, and high-quality code generation and review pipeline by connecting multiple top models:
| Value Description |
| :--- | :--- |
| **🧠 Cost Optimization** | **Claude/Sisyphus** is responsible for high-IQ thinking and scheduling but powerful), while** handles heavy code execution (large quantity and sufficient). |
| **🧩 Complementary Capabilities** | **Claude** makes up for **Coder**'s creativity shortcomings, **Codex** provides an independent third-party review perspective, and **Gemini** offers diverse expert opinions. |
| **🛡️ Quality Assurance** | Introduces a double review mechanism: **Claude's initial review** + **Codex's final review**, robustness. |
| **🔄 Fully Automated Loop** | Supports the fully automated process of `disassembly` → `execution` → `review` → `retry`, minimizing manual intervention. |
| **🔧 Flexible Architecture** | Supports **Claude Code (MCP)** and **OpenCode (Oh-My-OpenCode)** two operating environments, choose as needed. |
| **🔄 Context Persistence** | **SESSION_ID** session reuse mechanism ensures multi-round collaboration context coherence, supporting long task stable execution without information loss. |
### 🔀 Two Operating Environments
| Feature | Claude Code (MCP) | OpenCode (Oh-My-OpenCode) |
|------|-------------------|
| **Architect** | Claude |phus (Claude Opus) |
| **Tool Invocation** | MCP Protocol | Sub-agent delegation |
| **Coder** | claude CLI + configurable backend | document-writer agent |
| **Codex** | codex CLI | oracle agent |
|ini** | gemini CLI | frontend-ui-ux agent |
| Scenarios** | Claude Code users | Prefer open-source, multiple LLM providers |
| **Configuration Complexity** | Medium | High |
## 🤖 Role Division and Collaboration
In this system, each model has a clear responsibility:
* **Claude**: 👑 **Architect / Coordinator**
* Responsible for demand analysis, task disassembly, Prompt optimization, and final decision-making.
* **Coder**: 🔨 **Executor**
* Refers to those **high- strong execution capability** models (e.g., GLM-4.7, DeepSeek-V3, etc.).
* Can access **any third-party model supporting Claude Code API**, responsible for specific code generation, modification, and batch task processing.
* **Codex (OpenAI)**: ⚖️ **Reviewer / Senior Code Advisor**
* Responsible for independent code quality review, providing objective Code Review, and serving as an architecture design and complex solution consultant.
* **Gemini**: 🧠 **Multifaceted Expert (Optional)**
* AI expert at the same level as Claude, called as needed. Can act as a senior consultant, independent reviewer, or code executor.
### 📊 Measured Cases[Unit Test Batch Generation](cases/2025-01-05-unit-test-generation/README.md)** - CCG Architecture Measured Record
| Indicator | Pure Claude Solution | CCG Collaboration Solution | Description |
| :--- | :--- | :--- | :--- |
| **Task Scale** | 7,488 lines of code (481 test cases) | 7,488 lines of code (481 test cases) | Generate unit tests for a backend project |
| **Total Cost** | $3.13 | $0.55 | **Save 82%** |
| **Claude Cost** | $3.13 | $0.29 | **Save 91%** (only architecture scheduling) |
| **Coder Cost** | $0 | $0.26 | Execute heavy code generation tasks |
| **Quality Review** | ❌ No independent review | ✅ Claude's initial review + Codex's final review | Double gatekeeping, controllable code quality |
**Core Advantages**:
- 💰 **Cost Optimization**: Claude only outputs brief instructions, using cheap input prices to handle acceptance work, avoiding expensive code tokens.
- 🔄 **Context Persistence**: SESSION_ID session reuse mechanism ensures multi-round collaboration context coherence, supporting long task stable execution.
- ⚡ **Long Task Stability**: Optimized task splitting and retry strategy, ensuring (e.g., batch generation of 7,488 lines of test code) are completed stably.
- 🛡️ **Quality Assurance review mechanism (Claude's initial review + Codex's final controllable code quality.
### Collaboration Flowchart
```mermaid
flowchart TB
subgraph UserLayer ["User Layer"]
User(["👤 User Demand"])
subgraph ClaudeLayer ["Claude - Architect"]
Claude["🧠 Demand Analysis Disassembly"]
📝 Construct Precise Prompt"]
Review["🔍 Result Review & Decision"]
end
PLayer ["MCP Server"]
MCP{{"⚙️ CCG-MCP"}}
end
Layer ["Execution Layer"]
Coder["🔨 Coder Tool<br><code>claude CLI → Configurable Backend</code>sandbox: workspace-write"]
Codex["⚖️ Codex Tool<br><code>codex CLI</code><br>sandbox: read-only"]
Gemini["🧠 Gemini Tool<br><code>gemini CLI</code><br>sandbox: workspace-write"]
end
User --> Claude
Claude --> Prompt
Prompt -->|" gemini"| MCP
MCP -->|"Streaming JSON"| Coder
MCP -->|"Streaming JSON"| Gemini
Coder -->|"SESSION_ID + result"| Review
Gemini -->|"SESSION_ID + result"| Review
Review -->|"Needs Review / Expert Opinion"| MCP
MCP -->|"Streaming JSON"| Codex
Codex -->|"SESSION_ID + Review Conclusion"| Review
Review -->|"✅ Passed"| Done(["🎉 Task Completed"])
Review -->|"❌ Needs Modification"| Prompt
Review -->|"⚠️ Minor
```
**Typical Workflow**:
```
1. User proposes demand
↓
2. and disassembles tasks, constructs precise Prompts
↓
3. Calls coder gemini) executes code generation/modification
↓
4. Claude reviews results, decides whether Codex review or Gemini consultation is needed
↓
5. Calls codex gemini) tool → independent Code Review / obtains second opinions
↓
6. Based on review conclusions: pass / optimize / re-execute
```
## 🚀 Quick Start
### 1. Pre-requisites
Before starting, ensure you have installed the following tools:
* **uv**: Fast Python package manager ([Installation Guide](https://docs.astral.sh/uv/))
* Windows: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`
* macOS/Linux: `curlSf https://.sh/ | sh`
* **Claude Code**: Version **≥ v2.0.56** ([Installation Guide](https://code.claude.com/docs))
* **Codex CLI**: Version **≥ v0.61.0** ([Installation Guide](https://developers.openai.com/codex/quickstart))
* **Gemini (optional): If you need to use GeminiInstallation Guide](https://github.com/google-gemini/gemini-cli))
* **Coder Backend**: Need to configure yourself, recommend using GLM.7 as case, obtain from [Zhip](open.bigmodel.cn).
> **⚠️ Important Note: Fees and Permissions**
> * **Tool Authorization**: `claude`, `codex`, and `gemini` CLI tools need to be authorized locally.
> * **Fee Description**: The use of these tools usually involves official subscription fees or API usage fees.
> * **Claude Code**: Requires Anthropic account and corresponding billing settings. (or third-party access)
> * **Codex CLI**: Requires OpenAI account or API quota.
> * **Gemini CLI**: Defaults to calling `gemini-3-pro-preview` model (may involve Google AI subscription or API call limits).
> * **Coder API**: Need to bear API call fees of the model (., Zhipu AI, Deep etc.).
> * Please ensure all tools are logged in and have resources before formal use.
### ⚡ One-Click Configuration (Recommended)
We provide a one-click configuration script to automatically complete all setup steps:
**Windows (double-click to run or execute in terminal)**
```powershell
git clone https://github.com/FredericMN/Coder-Codex-Gemini.git
cd Coder-Codex-Gemini
.\setup.bat
```
**macOS/Linux**
```bash
git clone https://github.com/FredericMN/Coder-Codex-Gemini.git
cd Coder-Codex-Gemini
chmod +x setup.sh && ./setup.sh
```
**Script Execution Process**:
1. **Check and install uv** - If not installed, automatically download and install.
2. **Check Claude CLI** - Verify if installed.
3Install project dependencies**uv sync`.
4. **Register MCP Server** - Automatically configure to user level.
5. **** - Copy workflow guidance to `~/.claude/skills/`.
6. **Configure Global Prompt** append to `~/.claude/CLA`.
7. **Configure Coder** - Interactive input API Token, Base URL Model.
**🔐 Security Note**:
- API Token input will not be displayed on the screen.
- Configuration files are saved in `~/.ccg-mcp/config.toml`, with permissions set to only readable and writable by the current user.
- Token is only stored locally, not uploaded or shared.
> 💡 **Tip**: After one-click configuration is complete, please restart Claude Code CLI to make the configuration take effect.
### Windows User Precautions
When using CCG-MCP on Windows, ensure CLI tools are correctly added to the system PATH:
| Tool | Verification Command | Common Installation Location |
|------|----------|--------------|
| `claude` | `where claude` | `%APPDATA%\npm\claude.cmd` or installed globally via npm |
| `codex` | `where codex` | `%APPDATA%\npm\codex.cmd` globally via npm |
| `gemini` | `where` | `%APPDATA%\npm\gemini.cmd` or installed globally via npm |
| `uv` | `where uv` | `%USERPROFILE%\.local\bin\uv.exe` |
**Method to Add to PATH**:
1. Open "System Properties" → "Advanced" → "Environment Variables".
2. Find `Path` in "User click "Edit".
3. Add the directory (e.g., `%APPDATA%\npm`).
4. Restart the terminal to make the configuration take effect.
**Verify Installation**:
```powershell
# Check if all tools are available
claude --version
codex --version
gemini --version # Optional
uv --version
```
> **Tip**: If you encounter "command not found" errors, check if the PATH configuration is correct.
### 2. Install MCP Server
#### (Recommended)
The one-click script uses remote installation by default, no additional operation is required. For manual installation:
```bash
claude mcp add ccg -s user --transport stdio -- uvx --refresh --from git+https://github.com/FredericMN/Coder-Codex-Gemini.git ccg-mcp
```
#### Local Installation (Only for Development and Debugging)
If you need to source code or debug, use local installation:
```# Enter the project directory
path/to/Cx-Gemini
# Install dependencies
uv# Register MCP Server (using local path)
# Windows
claude mcp add ccg -s user --transport stdio -- uv run --directory $pwd ccg-mcp
# macOS/Linuxaude mcp add ccg -s user --transport stdio -- uv run --directory $(pwdg-mcp
```
#### Remote Installation vs Local| Feature | Remote Installation (Recommended Local Installation |
|------|-----------------|---------|
| **Stability** | ✅ Each time independently pulled, no file locking issues | ⚠️ Multiple terminal concurrent access may conflict |
| **Applicable Scenarios** | Daily use | Development and debugging |
| **Skills Support** | Need to manually install to `~/.claude/skills/` | Need to manually install (or-click script) **Update Method** | Automatically obtain the latest version | Need to manually `git pull` |
Dependency Requirements** | Requires `git` Only requires `uv> **⚠️ Note**: When locally installed, if multiple terminals concurrently call it may cause "MCP unresponsive" due to file locking. It is recommended to use remote installation for daily use.
**Uninstall MCP```bash
claude mcp remove ccg -s user
```
### 3. Configure
It is recommended to use a ** for management.
> **Configurable Backend**: Coder tool calls the backend model through Claude Code CLI. need to configure it themselves**, and it is recommended to use GLM-4.7 as a reference case. You can other models that support Claude Code API (e.g., Minim DeepSeek, etc.).
**Create configuration directory**:
```bash
# Windows
mkdir %USERPROFILE%\.ccg-mcp
#/Linux
mkdir -p ~/.ccg-mcp
```
**Create configuration file** `~/.ccg-mcp/config.toml`:
```toml
[coder]
api_token = "your-api-token" # Required
base_url = "https://open.bigmodel.cn/api/anthropic" # Example: GLM API
model = "glm-4.7" # Example: GLM-4.7, can be replaced with other models
[coder.env]
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
```
### 4. InstallRecommended Skills layer provides workflow guidance to ensure Claude correctly uses MCP tools.
```bash
# Windows (PowerShell (!(Test-Path "$env:USERPROFILE\.claude\skills")) { mkdir "$env:\.claude\skills" }
xcopy /E "skills\ccg-workflow" "$envPROFILE\.claude\skills\ccg-workflow"
# Optional: Install Gemini collaboration Skill
xcopy /E /I "skillsini-collaboration" "$env:USERPROFILE\.claude\skills\gemini-collaboration"
# macOS/Linux
mkdir -p ~/.claude/skills
cp -r skills/ccg-workflow ~/.claude/skills/
# Optional: Install Gemini collaboration Skill
cp -r skills/gemaboration ~/./skills/
```
### 5. Configure Global Prompt (Recommended)
Add mandatory rules~/.claude/CLAUDE.md` to ensure Claude follows the collaboration process:
```markdown
# Global Protocol
## Mandatory Rules
- **Default Collaboration**: All code/document modification tasks **must** be delegated to Coder for execution, and **must** be reviewed by Codex after completion of each stage.
- **Skip Confirmation**: If it is determined that collaboration is not required, the task **must be paused immediately** and reported:
> "This is a simple [description] task, and I have determined that it does not require Coder/Codex. Do you agree? Waiting for your confirmation."
- **Violation Terminates**: Skipping Coder execution or Codex review without confirmation = **Process Violation**.
- **Session Reuse**: The received `SESSION_ID` **must be saved** and always carried in the request parameters to maintain context.
- **SESSION_ID Management**: SESSION_IDs for each role (Coder/Codex/Gemini) are independent, and **must use the actual SESSION_ID values** returned by MCP tools, strictly prohibiting self-created IDs or mixed use of IDs for different roles.
## ⚠️ Skill Reading Prerequisites (Mandatory)
**Before calling any CCG MCP tools, you must execute the corresponding Skill to obtain best practice guidance:**
| MCP Tool | Preceding Skill | Execution Method |
|----------|---------------|---------------|
| `mcp__ccg__coder` | `/ccg-workflow` | Must be executed first |
| `mcp__ccg__codex` | `/ccg-workflow` | Must be executed first |
| `mcp__ccg__gemini` | `/gemini-collaboration` | Must be executed first |
**Execution Process**:
1. User requests use of Coder/Codex/Gemini
2. **Immediately execute the corresponding Skill** (e.g., `/ccg-workflow`, `/gemini-collaboration`)
3. Read the guidance content returned by the Skill
4. Call the MCP tool according to the guidance
**Prohibited Behavior**:
- ❌ Skip Skill and directly call MCP tools
- ❌ Assume best practices are understood without executing the Skill
---
# AI Collaboration System
**Claude is the final decision-maker**, and all AI opinions are for reference only, requiring critical thinking before making optimal decisions.
## Role Division
| Role | Positioning | Purpose | sandbox | Retries |
|------|------------|--------|---------|------|
| **Coder** | Code Executor | Generate/modify code, batch tasks | workspace-write | Default no retries |
| **Codex** | Code Reviewer/Senior Consultant | Architecture design, quality control, review | read-only | Default 1 retry |
| **Gemini** | Senior Consultant (as needed) | Architecture design, second opinions, frontend/UI | workspace-write (yolo) | Default 1 retry |
## Core Process
1. **Coder Execution**: All modification tasks are delegated to Coder for processing
2. **Claude Acceptance**: After Coder completes, quickly check for errors; if there are errors, Claude fixes them
3. **Codex Review**: After stage development is completed, call review; if there are errors, delegate Coder to fix, and iteratively update until passing
## Task Splitting Principles (distributed to Coder)
> ⚠️ **One call, one goal**. Prohibited to pile multiple unrelated demands on Coder.
- **Precise Prompt**: Clear goals, sufficient context, and clear acceptance criteria
- **Split by Module**: Related modifications can be merged, and independent modules are separated
- **Stage Review**: Each module undergoes Claude acceptance, and Codex reviews after milestones
## Pre-coding Preparation (complex tasks)
1. Search for affected symbols/entry points
2. List files that need modification
3. For complex issues, communicate solutions with Codex or Gemini first
## Gemini Trigger Scenarios
- **User Explicit Request**: User specifies using Gemini
- **Claude Autonomous Call**: Design frontend/UI, need second opinions or independent perspectives
> **Note**: Pure MCP can work, but Skills + global Prompt configuration is recommended for the best experience.
### 6. Verify Installation
Run the following command to check the MCP server status:
```bash
claude mcp list
```
✅ Seeing the following output indicates successful installation:
```text
ccg: ... - ✓ Connected
```
### 7. (Optional) Permission Configuration
For a smoother experience, add automatic authorization in `~/.claude/settings.json`:
```json
{
"permissions": {
"allow": [
"mcp__ccg__coder",
"mcp__ccg__codex",
"mcp__ccg__gemini"
]
}
}
```
## 🛠️ Tool Details
### `coder` - Code Executor
Invoke configurable backend models to execute specific code generation or modification tasks.
> **Backend configurable**: Coder tools call backend models through Claude Code CLI. **User configuration required**, recommended to use GLM-4.7 as a reference case; you can also choose other models supporting Claude Code API (e.g., Minimax, DeepSeek).
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :---: | :--- | :--- |
| `PROMPT` | string | ✅ | - | Specific task instructions and code requirements |
| `cd` | Path | ✅ | - | Target working directory |
| `sandbox` | string | - | `workspace-write` | Sandbox policy, default allows writing |
| `SESSION_ID` | string | - | `""` | Session ID, used to maintain multi-turn dialogue context |
| `return_all_messages` | bool | - | `false` | Whether to return complete dialogue history (for debugging) |
| `return_metrics` | bool | - | `false` | Whether to include metrics like time consumption in the return value |
| `timeout` | int | - | `300` | Idle timeout (seconds), output exceeding this time triggers timeout |
| `max_duration` | int | - | `1800` | Total duration hard upper limit (seconds), default 30 minutes, 0 means no limit |
| `max_retries` | int | - | `0` | Maximum retries (Coder defaults to no retries) |
| `log_metrics` | bool | - | `false` | Whether to output metrics to stderr |
### `codex` - Code Reviewer
Invoke Codex for independent and strict code review.
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :---: | :--- | :--- |
| `PROMPT` | string | ✅ | - | Review task description |
| `cd` | Path | ✅ | - | Target working directory |
| `sandbox` | string | - | `read-only` | **Mandatory read-only**, reviewers are strictly prohibited from modifying code |
| `SESSION_ID` | string | - | `""` | Session ID |
| `skip_git_repo_check` | bool | - | `true` | Whether to allow running in non-Git repositories |
| `return_all_messages` | bool | - | `false` | Whether to return complete dialogue history (for debugging) |
| `image` | List[Path]| - | `[]` | Additional image list (for UI review, etc.) |
| `model` | string | - | `""` | Specify model, default using Codex's own configuration |
| `return_metrics` | bool | - | `false` | Whether to include metrics like time consumption in the return value |
| `timeout` | int | - | `300` | Idle timeout (seconds), output exceeding this time triggers timeout |
| `max_duration` | int | - | `1800` | Total duration hard upper limit (seconds), default 30 minutes, 0 means no limit |
| `max_retries` | int | - | `1` | Maximum retries (Codex defaults to 1 retry) |
| `log_metrics` | bool | - | `false` | Whether to output metrics to stderr |
| `yolo` | bool | - | `false` | No approval required to run all commands (skip sandbox) |
| `profile` | string | - | `""` | Configuration file name loaded from ~/.codex/config.toml |
### `gemini` - Polymath Expert (optional)
Invoke Gemini CLI for code execution, technical consultation, or code review. Top-tier AI experts at the same level as Claude.
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :---: | :--- | :--- |
| `PROMPT` | string | ✅ | - | Task instructions, providing sufficient background information |
| `cd` | Path | ✅ | - | Working directory |
| `sandbox` | string | - | `workspace-write` | Sandbox policy, default allows writing (flexible control) |
| `yolo` | bool | - | `true` | Skip approval, default enabled |
| `SESSION_ID` | string | - | `""` | Session ID for multi-turn dialogue |
| `model` | string | - | `gemini-3-pro-preview` | Specify model version |
| `return_all_messages` | bool | - | `false` | Whether to return complete dialogue history |
| `return_metrics` | bool | - | `false` | Whether to include metrics like time consumption in the return value |
| `timeout` | int | - | `300` | Idle timeout (seconds) |
| `max_duration` | int | - | `1800` | Total duration hard upper limit (seconds) |
| `max_retries` | int | - | `1` | Maximum retries |
| `log_metrics` | bool | - | `false` | Whether to output metrics to stderr |
**Role Positioning**:
- 🧠 **Senior Consultant**: Architecture design, technical selection, complex scheme discussion
- ⚖️ **Independent Review**: Code review, scheme evaluation, quality control
- 🔨 **Code Execution**: Prototype development, functional implementation (especially proficient in frontend/UI)
**Trigger Scenarios**:
- User explicitly requests using Gemini
- Claude needs a second opinion or independent perspective
### Timeout Mechanism
This project adopts a **dual timeout protection** mechanism:
| Timeout Type | Parameter | Default | Description |
|----------|------|--------|------|
| **Idle Timeout** | `timeout` | 300s | Output exceeding this time triggers timeout, output resets timer |
| **Total Duration Hard Upper Limit** | `max_duration` | 1800s | From start timing, regardless of output, exceeding this time forces termination |
**Error Type Distinction**:
- `idle_timeout`: Idle timeout (no output)
- `timeout`: Total duration timeout
### Return Value Structure
```json
// Success (default behavior, return_metrics=false)
{
"success": true,
"tool": "coder",
"SESSION_ID": "uuid-string",
"result": "reply content"
}
// Success (enable metrics, return_metrics=true)
{
"success": true,
"tool": "coder",
"SESSION_ID": "uuid-string",
"result": "reply content",
"metrics": {
"ts_start": "2026-01-02T10:00:00.000Z",
"ts_end": "2026-01-02T10:00:05.123Z",
"duration_ms": 5123,
"tool": "coder",
"sandbox": "workspace-write",
"success": true,
"retries": 0,
"exit_code": 0,
"prompt_chars": 256,
"prompt_lines": 10,
"result_chars": 1024,
"result_lines": 50,
"raw_output_lines": 60,
"json_decode_errors": 0
}
}
// Failure (structured error, default behavior)
{
"success": false,
"tool": "coder",
"error": "error summary",
"error_kind": "idle_timeout | timeout | upstream_error | ...",
"error_detail": {
"message": "error description",
"exit_code": 1,
"last_lines": ["last 20 lines of output..."],
"idle_timeout_s": 300,
"max_duration_s": 1800
// "retries": 1 // Only returned when retries > 0
}
}
// Failure (enable metrics, return_metrics=true)
{
"success": false,
"tool": "coder",
"error": "error summary",
"error_kind": "idle_timeout | timeout | upstream_error | ...",
"error_detail": {
"message": "error description",
"exit_code": 1,
"last_lines": ["last 20 lines of output..."],
"idle_timeout_s": 300,
"max_duration_s": 1800
// "retries": 1 // Only returned when retries > 0
},
"metrics": {
"ts_start": "2026-01-02T10:00:00.000Z",
"ts_end": "2026-01-02T10:00:05.123Z",
"duration_ms": 5123,
"tool": "coder",
"sandbox": "workspace-write",
"success": false,
"retries": 0,
"exit_code": 1,
"prompt_chars": 256,
"prompt_lines": 10,
"json_decode_errors": 0
}
}
```
## 📚 Architecture Description
### Three-layer Configuration Architecture (Claude Code)
This project adopts a **MCP + Skills + Global Prompt** hybrid architecture under the Claude Code environment, with clear responsibilities for each layer:
| Level | Responsibility | Token Consumption | Necessity |
|------|------------|-----------|--------|
| **MCP Layer** | Tool implementation (type safety, structured error, retries, metrics) | Fixed (tool schema) | **Required** |
| **Skills Layer** | Workflow guidance (trigger conditions, process, templates) | Loaded as needed | Recommended |
| **Global Prompt Layer** | Mandatory rules (ensuring Claude compliance with collaboration process) | Fixed (about 20 lines) | Recommended |
**Why recommend complete configuration?**
- **Pure MCP**: Tools available, but Claude may not understand when/how to use
- **+ Skills**: Claude learns workflow, knows when to trigger collaboration
- **+ Global Prompt**: Mandatory rules ensure Claude always follows collaboration discipline
**Token Optimization**: Skills loaded on demand, non-code tasks do not load workflow guidance, can significantly save tokens
---
## 🔄 OpenCode Configuration
> **OpenCode** is an open-source alternative to Claude Code, and with the **Oh-My-OpenCode** plugin, it can achieve similar multi-agent orchestration effects. No additional MCP and SKILLS support required.
### Applicable Scenarios
- Want to use multiple LLM providers (Claude, GPT, Gemini)
- Need multi-agent parallel collaboration
- Want to see the real-time activity process of each sub-agent
- Prefer open-source tools
### 🆕 New User vs. Installed User
| User Type | Recommended Method | Description |
|----------|----------|------|
| **Not Installed OpenCode** | One-click script | Automatically complete all installation and configuration |
| **Installed OpenCode + Oh-My-OpenCode** | Manual configuration | Reference template files, merge configurations as needed |
> ⚠️ **Installed users note**: One-click script will detect existing configuration files and ask if they should be overwritten. If you choose to overwrite, the original file will be automatically backed up. It is recommended to choose skip, then manually merge the required configuration.
### ⚡ One-click Configuration (recommended for new users - users who have not installed OpenCode)
**Windows (double-click run or terminal execution)**
```powershell
git clone https://github.com/FredericMN/Coder-Codex-Gemini.git
cd Coder-Codex-Gemini
.\setup-opencode.bat
```
**macOS/Linux**
```bash
git clone https://github.com/FredericMN/Coder-Codex-Gemini.git
cd Coder-Codex-Gemini
chmod +x setup-opencode.sh && ./setup-opencode.sh
```
**Script execution process**:
1. **Check and install dependencies** - bun, opencode CLI
2. **Install Oh-My-OpenCode** - interactive selection of subscription status
3. **Configure opencode.json** - model definition and API configuration
4. **Configure oh-my-opencode.json** - CCG agent role definition
5. **Configure AGENTS.md** - collaboration protocol
### 📝 Manual Configuration (recommended for installed users)
If you have installed OpenCode and Oh-My-OpenCode, it is recommended to refer to the following template files for manual configuration:
| Template File | Target Location | Description |
|----------|----------|------|
| [`templates/opencode/opencode.json`](templates/opencode/opencode.json) | `~/.config/opencode/opencode.json` | Model and API configuration |
| [`templates/opencode/oh-my-opencode.json`](templates/opencode/oh-my-opencode.json) | `~/.config/opencode/oh-my-opencode.json` | Agent role definition |
| [`templates/opencode/AGENTS.md`](templates/opencode/AGENTS.md) | `~/.config/opencode/AGENTS.md` | Collaboration protocol |
#### Core Configuration Items
**1. `oh-my-opencode.json` - Agent Role Definition (Key Points)**
The main configurations required are `prompt_append` and `model` for each agent:
> 💡 **About `prompt_append`**: This is an "appended prompt" that adds CCG collaboration rules to the existing Oh-My-OpenCode prompts without overriding them, ensuring maximum compatibility.
```json
{
"agents": {
"Sisyphus": {
"model": "anthropic/claude-opus-4-5-20251101",
"prompt_append": "## CCG Collaboration Rules\n\nYou are an architect..."
},
"document-writer": {
"model": "zhipuai-coding-plan/glm-4.7",
"prompt_append": "## ⚠️ Identity Confirmation: You are a Coder sub-agent..."
},
"oracle": {
"model": "openai/gpt-5.1-codex-mini",
"prompt_append": "## ⚠️ Identity Confirmation: You are a Codex sub-agent..."
},
"frontend-ui-ux-engineer": {
"model": "google/antigravity-gemini-3-pro-high",
"prompt_append": "## ⚠️ Identity Confirmation: You are a Gemini sub-agent..."
}
}
}
```
- **`prompt_append`**: Defines the role behavior specifications for each agent, which is the core of CCG collaboration.
- **`model`**: Can be adjusted according to your subscribed models.
**2. `opencode.json` - Model and API Configuration**
In my personal usage scenario, most models (OpenAI, Google, Zhipu) are subscribed through OAuth or official API authentication, and no additional URL/API configuration is required.
**Cases requiring third-party proxy configuration** (applicable to OpenAI, Claude, and other models):
```json
{
"provider": {
"anthropic": {
"options": {
"baseURL": "https://your-proxy-api.com/v1",
"apiKey": "your-api-key"
},
"models": {
"claude-opus-4-5-20251101": { "name": "claude-opus-4-5-20251101" }
}
}
}
}
```
#### ⚠️ Third-Party API Proxy Precautions
When using third-party API proxies, **the model name key must exactly match the model name supported by the proxy**:
```json
// ✅ Correct: The key name matches the model name supported by the proxy
"models": {
"claude-opus-4-5-20251101": { "name": "claude-opus-4-5-20251101" }
}
// ❌ Incorrect: The key name does not match the proxy, leading to call failure
"models": {
"my-custom-name": { "name": "claude-opus-4-5-20251101" }
}
```
**Before configuring**:
1. Confirm which model names your proxy supports.
2. Set the key name under `models` to the exact name supported by the proxy.
3. Use the `provider/model-key` format when referencing in `oh-my-opencode.json` (e.g., `anthropic/claude-opus-4-5-20251101`).
### Agent Role Mapping (Template Configuration, Specific Models Can Be Freely Replaced)
| CCG Role | OpenCode Agent | Model | Responsibilities |
|----------|---------------|------|------|
| **Architect** | Sisyphus | Claude Opus 4.5 | Demand Analysis, Task Decomposition, Final Decision |
| **Coder** | document-writer | GLM-4.7 | Code Generation, Document Modification, Batch Tasks |
| **Codex** | oracle | GPT-5.1 Codex Mini | Code Review, Architecture Consultation, Quality Control |
| **Gemini** | frontend-ui-ux-engineer | Gemini 3 Pro High | Front-end/UI, Second Opinion, Independent Perspective |
### Authentication Configuration
After installation, authentication is required for each provider:
```bash
# 1. Anthropic (Claude)
opencode auth login
# → Select: Anthropic → Claude Pro/Max
# 2. OpenAI (ChatGPT/Codex)
opencode auth login
# → Select: OpenAI → ChatGPT Plus/Pro (Codex Subscription)
# 3. Google (Gemini)
opencode auth login
# → Select: Google → OAuth with Google (Antigravity)
```
> ⚠️ **Important**: When using the Antigravity plugin, you must set `"google_auth": false` in `oh-my-opencode.json`.
### Shortcuts
| Shortcut | Function |
|:-------|:-----|
| `Tab` | Switch build/plan mode |
| `Ctrl+X` then `B` | Switch Sidebar |
| `Ctrl+X` then `→/←` | Switch sub-tasks |
| `Ctrl+X` then `↑` | Return to main task |
| `Ctrl+P` | Command Panel |
---
## 🧑💻 Development and Contribution
Feel free to submit issues and pull requests!
```bash
# 1. Clone the repository
git clone https://github.com/FredericMN/Coder-Codex-Gemini.git
cd Coder-Codex-Gemini
# 2. Install dependencies (using uv)
uv sync
# 3. Local debugging and running
uv run ccg-mcp
```
## 📚 Reference Resources
- **FastMCP**: [GitHub](https://github.com/jlowin/fastmcp) - Efficient MCP Framework
- **GLM API**: [Zhipu AI](https://open.bigmodel.cn) - Powerful Domestic Large Model (Recommended as Coder Backend)
- **Claude Code**: [Documentation](https://docs.anthropic.com/en/docs/claude-code)
- **OpenCode**: [Official Documentation](https://opencode.ai/docs) - Open-Source AI Coding Agent
- **Oh-My-OpenCode**: [GitHub](https://github.com/code-yeongyu/oh-my-opencode) - OpenCode Multi-Agent Orchestration Plugin
## 📄 License
MIT
