Gemini CLI Orchestrator MCP

# How It Works: Gemini CLI Orchestrator ## Table of Contents 1. [Core Architecture](#core-architecture) 2. [The Pure Metaprompting Philosophy](#the-pure-metaprompting-philosophy) 3. [Tool Flow and Integration](#tool-flow-and-integration) 4. [MCP Integration](#mcp-integration) 5. [Real-World Usage Patterns](#real-world-usage-patterns) 6. [Technical Implementation](#technical-implementation) 7. [User Journey](#user-journey) 8. [Design Decisions and Trade-offs](#design-decisions-and-trade-offs) ## Core Architecture ### Overview The Gemini CLI Orchestrator is a **pure metaprompting system** built on the Model Context Protocol (MCP). Unlike traditional tools that execute commands or perform analysis directly, it operates as an intelligent **teacher model** that guides users through systematic collaboration with Google's Gemini AI. ### System Components ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ MCP Client │───▶│ Orchestrator │───▶│ User + Bash │ │ (Claude Code) │ │ (Teacher) │ │ + Gemini CLI │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────────┐ │ Metaprompts │ │ (Guidance) │ └──────────────────┘ ``` **Key Principle**: The orchestrator contains **zero execution logic**. It only returns structured guidance that teaches users how to collaborate effectively with Gemini CLI. ## The Pure Metaprompting Philosophy ### Core Tenet > **"Don't build intelligence into the system. Build prompts that elicit intelligence from the agent."** ### What This Means **Traditional Approach (What We DON'T Do):** ```javascript // Traditional wrapper approach function analyzeCode(filePath) { const content = fs.readFileSync(filePath); const result = await geminiAPI.analyze(content); return processResult(result); } ``` **Pure Metaprompting Approach (What We DO):** ```javascript // Pure metaprompting approach function craftPromptGuidance(stepDescription, context) { return ` Use this command pattern: gemini -m gemini-2.5-flash -p "@${suggestedFiles} ${stepDescription}" Consider these aspects: [detailed guidance] Next steps: [workflow guidance] `; } ``` ### Why This Matters 1. **User Empowerment**: Users understand and control every step 2. **Flexibility**: Can adapt to any project structure or analysis need 3. **Transparency**: No black-box processing or hidden logic 4. **Portability**: Works anywhere the user has bash and Gemini CLI 5. **Security**: No file access, no command execution, no state storage ## Tool Flow and Integration ### The Four Core Tools The orchestrator provides four metaprompting tools that work together in a natural workflow: #### 1. `gemini_plan_analysis` **Purpose**: Breaks down complex analysis goals into manageable steps **Output**: Sequential workflow framework with stage-by-stage guidance **When to Use**: Starting any complex, multi-faceted analysis ```bash # Example usage gemini_plan_analysis goal="Audit authentication system for security vulnerabilities" # Returns: 5-stage analysis plan with specific gemini commands for each stage ``` #### 2. `gemini_craft_prompt` **Purpose**: Optimizes individual analysis steps for maximum Gemini effectiveness **Output**: Context-optimized gemini commands and prompt strategies **When to Use**: For each planned step or when you need focused analysis ```bash # Example usage gemini_craft_prompt step_description="Analyze JWT token handling" context="Found 3 auth endpoints" # Returns: Optimized gemini command with file selection and prompt structure ``` #### 3. `gemini_iterate_analysis` **Purpose**: Guides iterative investigation using ReAct (Reasoning-Acting) loops **Output**: Structured approach for dynamic, adaptive analysis **When to Use**: When initial analysis reveals complexity requiring deeper investigation ```bash # Example usage gemini_iterate_analysis current_understanding="JWT uses HS256" iteration_goal="Check for timing attacks" # Returns: ReAct loop guidance for systematic investigation ``` #### 4. `gemini_synthesize_findings` **Purpose**: Combines insights from multiple analysis steps into comprehensive understanding **Output**: Synthesis strategies and comprehensive analysis frameworks **When to Use**: After completing multiple analysis steps to create final insights ```bash # Example usage gemini_synthesize_findings steps_summary="Analyzed 5 components, found 3 issues" synthesis_goal="Security audit report" # Returns: Multi-perspective synthesis guidance and reporting strategies ``` ### Typical Workflow Pattern ``` Start: Complex Goal ↓ ┌─────────────────────┐ │ gemini_plan_analysis │ → Breaks goal into steps └─────────────────────┘ ↓ ┌─────────────────────┐ │ gemini_craft_prompt │ → Optimizes each step └─────────────────────┘ ↓ Execute Gemini ↓ ┌─────────┐ │ Need │ Yes ┌─────────────────────────┐ │ deeper │────→ │ gemini_iterate_analysis │ │ analysis│ └─────────────────────────┘ └─────────┘ ↓ │ No Execute + Iterate ↓ ↓ ┌────────────────────────┐ │ │ gemini_synthesize_ │ ←──┘ │ findings │ └────────────────────────┘ ↓ Final Insights ``` ## MCP Integration ### Model Context Protocol (MCP) The orchestrator implements the MCP standard, making it compatible with various AI development environments: - **Claude Code CLI**: Primary target environment - **Claude Desktop**: Full-featured desktop integration - **Cursor IDE**: Developer-focused code editor - **Windsurf IDE**: Modern development environment ### Server Architecture ```javascript // Core MCP server structure const server = new Server({ name: 'gemini-collaboration-guide', version: '2.1.0' }); // Tool registration server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [/* four metaprompting tools */] }; }); // Pure metaprompting response server.setRequestHandler(CallToolRequestSchema, async (request) => { // Returns structured guidance text, never executes commands return { content: [{ type: 'text', text: metapromptGuidance }] }; }); ``` ### Security Model - **No file system access**: Server never reads or writes files - **No command execution**: Server never runs shell commands - **No network requests**: Server makes no external API calls - **No state storage**: Server maintains no persistent data - **No authentication required**: Server handles no credentials ## Real-World Usage Patterns ### Security Audit Workflow ```bash # 1. Plan the audit gemini_plan_analysis goal="Comprehensive security audit of payment processing system" # 2. Analyze authentication layer gemini_craft_prompt step_description="Audit authentication mechanisms" context="Payment system security review" # Execute: gemini -m gemini-2.5-flash -p "@src/auth/ @middleware/ Analyze authentication..." # 3. Deep dive on findings gemini_iterate_analysis current_understanding="Found JWT with HS256" iteration_goal="Investigate potential vulnerabilities" # Execute iterative analysis based on guidance # 4. Synthesize security report gemini_synthesize_findings steps_summary="Audited auth, payment, session management" synthesis_goal="Executive security report" ``` ### Architecture Analysis Workflow ```bash # 1. Understand overall structure gemini_plan_analysis goal="Document microservices architecture for new team members" # 2. Analyze service boundaries gemini_craft_prompt step_description="Map service dependencies" context="Microservices documentation" # Execute: gemini --all_files -p "Map the service architecture..." # 3. Investigate communication patterns gemini_iterate_analysis current_understanding="12 services identified" iteration_goal="Understand data flow patterns" # 4. Create comprehensive documentation gemini_synthesize_findings steps_summary="Mapped services, APIs, data flows" synthesis_goal="Architecture documentation" ``` ### Performance Investigation Workflow ```bash # 1. Plan performance analysis gemini_plan_analysis goal="Identify and resolve application performance bottlenecks" # 2. Analyze hotspots gemini_craft_prompt step_description="Identify performance bottlenecks" context="Response times degraded" # Execute: gemini -p "@src/ @config/ Find performance issues..." # 3. Investigate root causes gemini_iterate_analysis current_understanding="Database queries slow" iteration_goal="Find inefficient queries" # 4. Optimize and document gemini_synthesize_findings steps_summary="Found N+1 queries, missing indexes" synthesis_goal="Performance optimization plan" ``` ## Technical Implementation ### Pure Metaprompting Design The core innovation is the **complete separation of guidance from execution**: ```javascript // Instead of this (execution logic): async function analyzeAuth(files) { const content = await readFiles(files); const analysis = await callGemini(content); return processResults(analysis); } // We do this (pure guidance): function craftAuthAnalysisGuidance(context) { return ` # Authentication Analysis Guidance ## Recommended Command: gemini -m gemini-2.5-flash -p "@src/auth/ @middleware/auth* Analyze authentication implementation..." ## Key Focus Areas: - Input validation and sanitization - Session management security - Password handling best practices ## Next Steps: After reviewing results, consider using gemini_iterate_analysis if issues found. `; } ``` ### Context Window Optimization The orchestrator teaches users to leverage Gemini's massive 1M+ token context window: ```bash # Traditional approach (limited context) cat auth.js | gemini -p "analyze this file" # Orchestrator-guided approach (full context) gemini -p "@src/auth/ @middleware/auth* @tests/auth* Comprehensive auth analysis" ``` ### Cognitive Framework Integration The system embeds proven cognitive frameworks: 1. **ReAct Loops**: Thought → Action → Observation → Reflection 2. **Sequential Thinking**: 5-stage progressive analysis 3. **Systems Thinking**: Multi-perspective synthesis 4. **Pattern Recognition**: Cross-cutting analysis techniques ## User Journey ### Phase 1: Installation and Setup (5 minutes) ```bash # Install Gemini CLI npm install -g @google/gemini-cli # Authenticate gemini auth login # Add to Claude Code claude mcp add gemini-collaboration-guide node /path/to/gemini-collaboration-guide.mjs # Verify /mcp # Should show available tools ``` ### Phase 2: First Analysis (15 minutes) ```bash # Start with simple goal gemini_plan_analysis goal="Understand this project's main dependencies" # Follow the guidance step by step gemini_craft_prompt step_description="Analyze package.json" context="New project exploration" # Execute the suggested command gemini -p "@package.json @README.md Explain the project dependencies and purpose" ``` ### Phase 3: Advanced Workflows (Ongoing) Users gradually learn to: - Chain multiple tools together - Use iterative analysis for complex problems - Synthesize insights across multiple investigation streams - Adapt the guidance to their specific project needs ### Phase 4: Mastery (Expert Usage) Expert users can: - Quickly identify which tool is needed for any analysis task - Customize the guidance patterns for their domain - Combine orchestrator guidance with their domain expertise - Mentor others using the systematic approaches learned ## Design Decisions and Trade-offs ### Why Pure Metaprompting? **Decision**: No execution logic in the orchestrator **Trade-off**: Requires users to execute commands manually **Benefit**: Maximum flexibility, transparency, and user control ### Why MCP Architecture? **Decision**: Built on Model Context Protocol **Trade-off**: Requires MCP-compatible clients **Benefit**: Broad compatibility with AI development tools ### Why Four Specific Tools? **Decision**: `plan_analysis`, `craft_prompt`, `iterate_analysis`, `synthesize_findings` **Trade-off**: Could have more specialized tools **Benefit**: Covers complete analysis lifecycle while remaining simple ### Why Stateless Design? **Decision**: No persistent storage or session management **Trade-off**: Users must manually track analysis state **Benefit**: Simplicity, security, and portability ### Why Focus on Gemini CLI? **Decision**: Optimize specifically for Gemini's capabilities **Trade-off**: Not generic across all AI models **Benefit**: Leverages Gemini's unique strengths (massive context, @ syntax) ## Conclusion The Gemini CLI Orchestrator represents a fundamental shift from **wrapper-based AI tools** to **intelligence-amplifying guidance systems**. By maintaining strict adherence to pure metaprompting principles, it empowers users to become more effective analysts while preserving complete transparency and control over the analysis process. The system's strength lies not in what it executes, but in what it teaches—transforming users into more systematic, strategic thinkers who can leverage AI capabilities more effectively than any automated wrapper could provide.