Gemini CLI Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Gemini CLI Integration in the Everything Claude Code (ECC) project provides a robust framework for utilizing Google's Gemini models within multi-model collaborative workflows. This integration allows the system to delegate specific tasks—particularly frontend UI/UX design, visual analysis, and accessibility reviews—to Gemini as a "Frontend Orchestrator" or specialist model while maintaining Claude as the primary orchestrator and filesystem writer.
The integration is built upon the ccg-workflow runtime and utilizes a dedicated wrapper (codeagent-wrapper) to bridge the communication between Claude and the Gemini API. It supports session persistence, role-based prompting through markdown files, and specialized handling of frontend-focused development tasks.
Sources: commands/multi-frontend.md:1-20, commands/multi-workflow.md:1-30
Architecture and Components
The Gemini integration operates as part of a larger multi-model ecosystem. It relies on a specific external runtime and a standardized calling specification to ensure consistent behavior across different development phases.
The ccg-workflow Runtime
Gemini integration requires the ccg-workflow runtime, which is provisioned via npx ccg-workflow. This setup initializes the ~/.claude/bin/codeagent-wrapper and the necessary role prompt files located in ~/.claude/.ccg/prompts/gemini/.
Sources: commands/multi-frontend.md:11-15, commands/multi-plan.md:11-15
Collaborative Roles
In multi-model workflows, Gemini is assigned specific trust levels and authorities:
- Frontend Authority: Gemini is considered the primary design authority. Its opinions on CSS, React, Vue, and visual consistency are highly trustworthy.
- Auxiliary Backend Reference: While Gemini can provide backend opinions, they are treated as "for reference only," with Codex serving as the backend logic authority.
Sources: commands/multi-frontend.md:25-30, commands/multi-backend.md:135-138
Component Relationship Diagram
The following diagram illustrates how the Gemini CLI integration fits into the broader ECC workflow:
The diagram shows that external models like Gemini have zero filesystem write access; Claude handles all file operations based on model outputs.
Sources: commands/multi-execute.md:215-220, commands/multi-workflow.md:155-160
Call Specification and Session Management
Integration with Gemini is performed via the Bash tool calling the codeagent-wrapper. The integration supports both fresh session initialization and session resumption to maintain context across different phases.
Interaction Syntax
Calls to Gemini must specify the backend, the model version (e.g., gemini-3-pro-preview), and a role file.
| Parameter | Description | Required |
|---|---|---|
--backend | Set to gemini | Yes |
--gemini-model | Specifies the model version (e.g., gemini-3-pro-preview) | Yes |
resume <ID> | Resumes a previously saved session context | Optional |
ROLE_FILE | Path to the markdown role prompt (e.g., analyzer.md) | Yes |
Sources: commands/multi-frontend.md:40-70, commands/multi-plan.md:25-45
Session Reuse Workflow
Every call to Gemini returns a SESSION_ID. This ID must be saved (e.g., as GEMINI_SESSION) and passed to the resume subcommand in subsequent phases (such as Planning or Optimization) to ensure the model retains state.
Agent Adaptation and Tool Mapping
Because standard agent definitions in ECC may use naming conventions incompatible with the Gemini CLI, the project includes an adaptation script to rewrite agent frontmatter.
The gemini-adapt-agents.js Script
This utility scans agent markdown files and performs the following transformations:
- Tool Mapping: Maps generic ECC tool names to Gemini-compatible internal tool names.
- Metadata Cleaning: Removes unsupported fields like
color:. - MCP Handling: Formats Model Context Protocol (MCP) tool names using underscores (e.g.,
mcp__tool__cmdbecomesmcp_tool_cmd).
Sources: scripts/gemini-adapt-agents.js:7-15, scripts/gemini-adapt-agents.js:68-85
Tool Name Mapping Table
The following table shows the static mapping used during adaptation:
| ECC Tool Name | Gemini CLI Name |
|---|---|
Read | read_file |
Write | write_file |
Edit | replace |
Bash | run_shell_command |
Grep | grep_search |
Glob | glob |
WebSearch | google_web_search |
WebFetch | web_fetch |
Sources: scripts/gemini-adapt-agents.js:7-16
Workflow Integration Phases
Gemini is utilized throughout the 6-phase development workflow, particularly when the task is identified as frontend-related.
Phase-Specific Roles
Gemini's role changes based on the phase of the workflow, using different role prompts:
- Analysis:
~/.claude/.ccg/prompts/gemini/analyzer.md— Focuses on UI feasibility and UX evaluation. - Planning:
~/.claude/.ccg/prompts/gemini/architect.md— Focuses on component structure and styling approach. - Implementation:
~/.claude/.ccg/prompts/gemini/frontend.md— Generates visual baselines and prototypes. - Review/Optimization:
~/.claude/.ccg/prompts/gemini/reviewer.md— Checks for accessibility, responsiveness, and design consistency.
Sources: commands/multi-frontend.md:75-80, commands/multi-execute.md:85-95, commands/multi-workflow.md:55-65
Frontend-Focused Execution Logic
When a workflow enters the implementation phase for a frontend task:
- Claude retrieves context (using
ace-toolorGlob/Grep). - Claude calls Gemini for a Prototype Acquisition.
- Gemini returns a
Unified Diff Patch. - Claude refactors the "dirty prototype" into production-grade code and applies changes to the filesystem.
Sources: commands/multi-execute.md:140-160, commands/multi-execute.md:175-200
Conclusion
The Gemini CLI Integration enables a specialized "Frontend Orchestrator" mode within ECC. By delegating UI and UX analysis to Gemini while retaining Claude for filesystem management and orchestration, the project achieves a high degree of specialization. The use of the ccg-workflow runtime and the gemini-adapt-agents.js utility ensures that Gemini can effectively participate in complex, multi-stage development tasks while remaining compatible with the project's overall toolset.
Sources: commands/multi-frontend.md:20-35, scripts/gemini-adapt-agents.js:1-5