How It Works: Gemini CLI Orchestrator

July 8, 2025 · View on GitHub

Table of Contents

  1. Core Architecture
  2. The Pure Metaprompting Philosophy
  3. Tool Flow and Integration
  4. MCP Integration
  5. Real-World Usage Patterns
  6. Technical Implementation
  7. User Journey
  8. 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):

// 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):

// 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

# 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

# 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

# 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

# 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

// 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

# 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

# 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

# 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:

// 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:

# 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)

# 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)

# 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.