🤖 Research Agentic CLI Integration

A comprehensive integration framework for using Gemini CLI and GitHub Copilot CLI as collaborative agents with Claude Code. This project enables multi-AI perspectives, consensus-based decision making, and specialized expertise for development tasks, code reviews, data analysis, and research.

🤖 Research Agentic CLI Integration

📋 Overview

This project integrates two powerful agentic CLI tools:

🔍 Gemini CLI - Development guidance, code reviews, and best practices analysis
📊 GitHub Copilot CLI - Data analysis, experiment design, and GitHub workflow automation

These tools work alongside Claude Code to provide:

🎯 Multiple AI perspectives on complex decisions
🧠 Specialized expertise for different domains
🤝 Consensus-building for high-confidence recommendations
🔄 Automated workflows and research assistance

⚠️ Important: Before You Begin

⚡ Critical Prerequisites:

Before using any agents in this project, you MUST complete the following steps:

🔐 1. Install CLI Tools

Both Gemini CLI and Copilot CLI must be installed globally on your system:

# Install Gemini CLI
npm install -g gemini-cli

# Install Copilot CLI
npm install -g @github/copilot

# Verify installations
gemini --version
copilot --version

🔑 2. Complete Authentication Flow

Each tool requires authentication before use:

Gemini CLI Authentication

# Option 1: Using API Key (Free Tier / Personal Use)
export GOOGLE_API_KEY="your-api-key-here"

# Option 2: Using PRO Subscription
gemini
# Inside Gemini prompt, authenticate:
/auth
# Follow the authentication flow

Get your API key: Google AI Studio

Copilot CLI Authentication

# Login with GitHub account (requires active Copilot subscription)
copilot auth login

# Verify authentication
copilot -p "Test authentication" --allow-all-tools

Subscription required: GitHub Copilot

✅ 3. Verify Setup

Test both tools before using the agents:

# Test Gemini CLI
gemini "Hello, can you confirm you're working?"

# Test Copilot CLI
copilot -p "Hello, can you confirm you're working?" --allow-all-tools

🚨 If either test fails, DO NOT proceed with agent usage. Complete the installation and authentication steps first.

✨ Features

🎯 Multi-Agent Coordination: Research orchestrator that coordinates Gemini and Copilot agents
🧠 Specialized Agents: Focused expertise in code review, data analysis, experiment design
📝 Reusable Templates: 50+ context templates for common tasks
📚 Comprehensive Documentation: Setup guides, usage examples, best practices
🔌 Flexible Integration: Works seamlessly with Claude Code's Bash and Task tools
🤖 Multi-Model Support: Leverage Claude Sonnet 4.5, GPT-5, or Gemini 2.5 Pro based on task requirements

🚀 Quick Start

📦 Prerequisites

✅ Node.js 22.x or higher
✅ npm 10.x or higher
✅ Claude Code environment
🔑 Google API key or Vertex AI credentials (for Gemini CLI)
💳 GitHub Copilot subscription (for Copilot CLI)

⚙️ Installation

📥 Install Tools

# Install Gemini CLI
npm install -g gemini-cli

# Install Copilot CLI
npm install -g @github/copilot

🔐 Authenticate

# Gemini CLI - Set API key
export GOOGLE_API_KEY="your-api-key-here"

# or use your PRO subscription credentials
gemini
# inside Gemini prompt, follow instructions to authenticate
/auth

# Copilot CLI - Login with GitHub
copilot auth login

✅ Verify Installation

# Test Gemini CLI
gemini "Hello, can you confirm you're working?"

# Test Copilot CLI
copilot -p "Hello, can you confirm you're working?" --allow-all-tools

For detailed setup instructions, see:

📖 Gemini CLI Setup Guide
📖 Copilot CLI Setup Guide

📁 Project Structure

research-agentic-cli-integration/
├── agents/                          # 🎭 Agent definition files
│   ├── gemini-integration.md        # 🔍 Gemini CLI integration agent
│   ├── copilot-integration.md       # 📊 Copilot CLI integration agent
│   └── research-orchestrator.md     # 🎯 Multi-agent orchestration
├── gemini-cli/                      # 🔍 Gemini CLI resources
│   ├── context-templates/           # 📝 Reusable prompt templates
│   │   ├── code-review-context.md
│   │   ├── best-practices-context.md
│   │   └── development-guidance-context.md
│   └── SETUP.md                     # ⚙️ Installation & configuration guide
├── copilot-cli/                     # 📊 Copilot CLI resources
│   ├── context-templates/           # 📝 Reusable prompt templates
│   │   ├── data-analysis-context.md
│   │   └── experiment-design-context.md
│   └── SETUP.md                     # ⚙️ Installation & configuration guide
├── todos/                           # 📋 Task tracking and improvements
├── IDEA.md                          # 💡 Project vision and concept
├── PLAN.md                          # 📅 Implementation milestones
└── README.md                        # 📄 This file

💻 Usage

Using Individual Agents

🔍 Gemini CLI - Code Review

# From Claude Code, using Bash tool
# ⚠️ IMPORTANT: Always include --include-directories flag
nvm use 22 && gemini --include-directories /work/agents -o json "Review @src/auth/login.ts for security vulnerabilities"

📊 Copilot CLI - Data Analysis

# From Claude Code, using Bash tool
nvm use 22 && copilot --model claude-sonnet-4.5 -p "Analyze user engagement trends in @data/metrics.csv" --allow-tool 'read'

🎯 Using the Research Orchestrator

The research orchestrator coordinates both agents for comprehensive analysis:

# Claude Code invokes orchestrator agent
# Orchestrator determines which tool(s) to use
# Results are consolidated into unified recommendations

Example scenarios:

🔍 Code + Data Analysis: Gemini reviews code quality, Copilot analyzes performance logs
🏗️ Architecture Decisions: Both agents provide perspectives, Claude synthesizes consensus
🧪 Experiment Design + Validation: Copilot designs experiment, Gemini validates technical feasibility

Common Workflows

1. Comprehensive Code Review

# Step 1: Gemini reviews code quality (note --include-directories flag)
nvm use 22 && gemini --include-directories $(pwd) -o json "Review @src/auth/*.ts for security and best practices" > gemini-review.json

# Step 2: Claude Code parses results and presents findings

2. Data-Driven Decision Making

# Step 1: Copilot analyzes data
nvm use 22 && copilot --model claude-sonnet-4.5 -p "Analyze performance metrics in @data/api-logs.csv. Identify optimization opportunities." --allow-tool 'read' > analysis.txt

# Step 2: Gemini reviews code for optimization (include workspace directory)
nvm use 22 && gemini --include-directories $(pwd) -o json "Review @src/api/*.ts for performance bottlenecks identified in analysis.txt" > gemini-perf.json

# Step 3: Claude Code consolidates and prioritizes recommendations

3. Multi-Model Consensus

# Get perspectives from different models on same question
nvm use 22 && copilot --model claude-sonnet-4.5 -p "Should we use microservices or monolith? @docs/requirements.md" --allow-all-tools > claude-perspective.txt

nvm use 22 && copilot --model gpt-5 -p "Should we use microservices or monolith? @docs/requirements.md" --allow-all-tools > gpt-perspective.txt

nvm use 22 && gemini --include-directories $(pwd) "Should we use microservices or monolith? @docs/requirements.md" > gemini-perspective.txt

# Claude Code compares all three perspectives and builds consensus

🎭 Agent Descriptions

🔍 Gemini Integration Agent

Purpose: Development guidance, code reviews, best practices analysis

Best For:

🔒 Security audits
✅ Code quality reviews
📋 Best practices validation
🏗️ Architectural decisions
💡 Development guidance

Invocation Example:

nvm use 22 && gemini --include-directories $(pwd) -o json "Audit @src/auth/ for OWASP Top 10 vulnerabilities"

See agents/gemini-integration.md for full documentation.

📊 Copilot Integration Agent

Purpose: Data analysis, experiment design, GitHub automation

Best For:

📈 Statistical analysis
🧪 Experiment design and A/B testing
🐙 GitHub repository operations
🤖 Multi-model perspectives
📊 Data visualization recommendations

Invocation Example:

nvm use 22 && copilot --model claude-sonnet-4.5 -p "Analyze @data/sales.csv for trends and seasonality" --allow-tool 'read'

See agents/copilot-integration.md for full documentation.

🎯 Research Orchestrator Agent

Purpose: Coordinate multiple agents for comprehensive analysis

Best For:

🎭 Complex decisions requiring multiple perspectives
🏗️ High-stakes architectural choices
📊 Comprehensive project analysis
🤝 Consensus-building workflows

Features:

🎯 Task routing (determines which agent(s) to invoke)
⚡ Parallel or sequential invocation
📦 Output consolidation
🤝 Consensus analysis (agreement vs divergent perspectives)

See agents/research-orchestrator.md for full documentation.

📝 Context Templates

Reusable prompt templates for common tasks:

Gemini CLI Templates

🔍 Code Review - Comprehensive code quality, security, and performance reviews
✅ Best Practices - Language and framework best practices audits
💡 Development Guidance - Architectural decisions and technical guidance

Located in: gemini-cli/context-templates/

Copilot CLI Templates

📊 Data Analysis - Statistical analysis, trend detection, anomaly identification
🧪 Experiment Design - A/B testing, experimental methodology, sample size calculation

Located in: copilot-cli/context-templates/

Each template includes:

📋 Template structure
💡 10+ detailed examples
📖 Usage patterns
✅ Best practices
📝 Notes and tips

🔧 Advanced Usage

Custom Gemini Commands

Create reusable commands in .gemini/commands/:

# .gemini/commands/security-audit.toml
[command]
name = "security-audit"
description = "Security audit of codebase"
prompt = """
Perform security audit of @src/ for OWASP Top 10:
1. Injection vulnerabilities
2. Authentication flaws
3. Sensitive data exposure
4. XXE
5. Broken access control
...

Output: JSON with severity levels
"""
output_format = "json"

Usage: gemini security-audit

Custom Copilot Agents

Create specialized agents in AGENTS.md:

## data-scientist

You are a data scientist specializing in statistical analysis.

### Focus
- Statistical significance testing
- Confidence intervals
- P-values
- Visualization recommendations

### Output
- Summary statistics
- Statistical tests
- Recommendations

Usage: copilot --agent data-scientist -p "Analyze @data/experiment.csv"

MCP Server Integration

Extend capabilities with Model Context Protocol servers:

// ~/.copilot/mcp-config.json
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://..."
      }
    }
  }
}

💡 Best Practices

📊 Use JSON Output: For Gemini CLI, use -o json for structured parsing
🤖 Specify Models: For Copilot CLI, choose model based on task (Claude for analysis, GPT for creativity)
🔒 Tool Permissions: Use minimal permissions, expand as needed
📁 Context Management: Use @file syntax explicitly for precise context
💰 Cost Awareness: Monitor API usage, especially with auto-approval modes
✅ Validate Results: Cross-check AI recommendations, especially for critical decisions
📝 Document Interactions: Track agent invocations and outcomes in todos/

🔧 Troubleshooting

Gemini CLI Issues

"API key not found"

export GOOGLE_API_KEY="your-key"
echo $GOOGLE_API_KEY  # Verify it's set

"Context too large"

Use specific file references with @file
Leverage .geminiignore
Break analysis into smaller chunks

Copilot CLI Issues

"Not authenticated"

copilot auth login

"Tool blocked by permissions"

copilot --allow-tool 'read' -p "Your prompt"
# Or for all tools:
copilot --allow-all-tools -p "Your prompt"

See setup guides for comprehensive troubleshooting:

📖 Gemini CLI Setup
📖 Copilot CLI Setup

📚 Documentation

💡 IDEA.md - Project vision and concept
📅 PLAN.md - Implementation milestones and timeline
⚙️ Gemini CLI Setup - Installation and configuration
⚙️ Copilot CLI Setup - Installation and configuration
🎭 Agent Definitions - Detailed agent documentation
📝 Context Templates - Reusable prompts
✅ TESTING-RESULTS.md - Validation results and findings

💼 Examples

Example 1: Security Audit Workflow

# 1. Gemini performs security audit (include workspace directory)
nvm use 22 && gemini --include-directories $(pwd) -o json "Audit @src/auth/ @src/api/ for security vulnerabilities. Focus on OWASP Top 10. Output JSON." > security-audit.json

# 2. Claude Code parses and categorizes findings
# 3. Presents prioritized list with file:line references

Example 2: A/B Test Analysis

# 1. Copilot designs experiment
nvm use 22 && copilot --model gpt-5 -p "Design A/B test for new checkout flow. Current conversion: 3.5%, Target: 5%, Duration: 2 weeks. Include sample size calc." --allow-all-tools > experiment-design.txt

# 2. Gemini validates technical implementation (include workspace)
nvm use 22 && gemini --include-directories $(pwd) "Review experiment design in experiment-design.txt. Assess technical feasibility for NestJS app in @src/checkout/. Flag risks." > feasibility.txt

# 3. Copilot analyzes test results (after test runs)
nvm use 22 && copilot --model claude-sonnet-4.5 -p "Analyze A/B test results @data/ab-test.csv. Calculate statistical significance, confidence intervals, recommendation." --allow-tool 'read' > results-analysis.txt

# 4. Claude Code consolidates into comprehensive report

Example 3: Architecture Decision

# Parallel invocation for multiple perspectives
nvm use 22 && gemini --include-directories $(pwd) "Analyze @src/ and recommend architecture: microservices vs modular monolith vs serverless. Context: 5-dev team, 50k users, growth to 200k in 12mo." > gemini-arch.txt &

nvm use 22 && copilot --model claude-sonnet-4.5 -p "Recommend architecture for growing NestJS app: microservices vs modular monolith. Team: 5 devs, Users: 50k->200k. Research industry trends." --allow-all-tools > copilot-arch.txt &

nvm use 22 && copilot --model gpt-5 -p "Suggest creative hybrid architecture approaches between microservices and monolith for 5-dev team with growth trajectory." --allow-all-tools > gpt-arch.txt &

wait

# Claude Code compares all three perspectives and synthesizes recommendation

🤝 Contributing

This is a research project for integrating agentic CLI tools with Claude Code. Contributions welcome:

📝 New Context Templates: Add templates for additional use cases
⚙️ Custom Commands: Share useful Gemini commands in .gemini/commands/
🎭 Custom Agents: Share Copilot agent configurations
🔄 Integration Patterns: Document successful workflows
🐛 Bug Reports: Report issues in todos/

🚀 Future Enhancements

Short-term

📝 Additional domain-specific context templates
⚙️ Custom commands library for common tasks
🔄 CI/CD integration patterns
💰 Cost tracking and optimization

Medium-term

🤖 Automated agent selection based on task classification
🗳️ Multi-agent voting system
📊 Performance analytics dashboard
💾 Caching strategies for cost optimization

Long-term

🧠 ML-based task routing
👥 Team collaboration features
🔌 Integration with additional agentic tools
🏢 Enterprise deployment guides

See PLAN.md for detailed roadmap.

📖 Resources

📄 License

This project is part of the broader agents repository. See repository root for license information.

💬 Support

For issues and questions:

📝 Internal: Document in todos/ directory
🔍 Gemini CLI: https://github.com/google-gemini/gemini-cli/issues
📊 Copilot CLI: https://github.com/cli/cli/issues
🤖 Claude Code: https://github.com/anthropics/claude-code/issues

Status: ✅ Infrastructure complete | 🧪 Testing phase complete | 🚀 Ready for production
Last Updated: 2025-11-20
Version: 1.0.0

weorbitant/claude-code-agentic-research-orchestrator

🤖 Research Agentic CLI Integration

📋 Overview

⚠️ Important: Before You Begin

🔐 1. Install CLI Tools

🔑 2. Complete Authentication Flow

Gemini CLI Authentication

Copilot CLI Authentication

✅ 3. Verify Setup

✨ Features

🚀 Quick Start

📦 Prerequisites

⚙️ Installation

📁 Project Structure

💻 Usage

Using Individual Agents

🔍 Gemini CLI - Code Review

📊 Copilot CLI - Data Analysis

🎯 Using the Research Orchestrator

Common Workflows

1. Comprehensive Code Review

2. Data-Driven Decision Making

3. Multi-Model Consensus

🎭 Agent Descriptions

🔍 Gemini Integration Agent

📊 Copilot Integration Agent

🎯 Research Orchestrator Agent

📝 Context Templates

Gemini CLI Templates

Copilot CLI Templates

🔧 Advanced Usage

Custom Gemini Commands

Custom Copilot Agents

MCP Server Integration

💡 Best Practices

🔧 Troubleshooting

Gemini CLI Issues

Copilot CLI Issues

📚 Documentation

💼 Examples

Example 1: Security Audit Workflow

Example 2: A/B Test Analysis

Example 3: Architecture Decision

🤝 Contributing

🚀 Future Enhancements

Short-term

Medium-term

Long-term

📖 Resources

Gemini CLI

Copilot CLI

Claude Code

📄 License

💬 Support

On this page

Contributors