Overview

GemKit's provider-agnostic architecture allows you to use either Gemini or Claude as the underlying AI engine. This flexibility lets you choose the best model for each task, compare provider performance, or leverage existing Claude investments while gaining GemKit's agent orchestration capabilities. Whether you're experimenting with dual-provider setups or migrating between ecosystems, this guide covers everything you need to know.

Why Use Claude with GemKit?

Use Cases for Dual-Provider Workflows

1. Model Strengths Optimization

Gemini Flash: Fast research and simple code generation
Claude Sonnet: Complex reasoning and architectural design
Gemini Pro: Cost-effective general implementation
Claude Opus: Critical systems requiring highest quality

2. Cost Optimization

Route expensive tasks to Claude only when necessary
Use Gemini for high-volume, low-complexity tasks
Compare costs across providers for your specific use case

3. Redundancy and Reliability

Fallback to alternative provider during outages
A/B test provider performance on same tasks
Avoid vendor lock-in

4. Best-of-Both-Worlds

Leverage Claude's strength in complex reasoning
Utilize Gemini's cost-effectiveness for scale
Access both ecosystems' unique capabilities

Provider Architecture

GemKit abstracts AI providers behind a unified interface:

markdown

User Prompt
    ↓
GemKit Agent System
    ↓
┌───────────────┬───────────────┐
│ Gemini CLI    │ Claude CLI    │
├───────────────┼───────────────┤
│ .gemini/      │ .claude/      │
│ agents/       │ agents/       │
│ extensions/   │ skills/       │
└───────────────┴───────────────┘
    ↓               ↓
Gemini API      Claude API

Key points:

Same agent definitions work with both providers
Automatic tool mapping between ecosystems
Unified session management and analytics
Model equivalence mapping built-in

Prerequisites

Required Software

bash

# 1. GemKit CLI (already installed)
npm list -g gemkit-cli

# 2. Claude CLI
npm install -g @anthropic-ai/claude-cli

# 3. Verify installations
gk --version
claude --version

API Keys

bash

# Gemini API Key
export GEMINI_API_KEY=AIza...
# Get from: https://makersuite.google.com/app/apikey

# Anthropic API Key
export ANTHROPIC_API_KEY=sk-ant-...
# Get from: https://console.anthropic.com/

Make permanent:

bash

# Add to ~/.bashrc or ~/.zshrc
echo 'export GEMINI_API_KEY=AIza...' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc
source ~/.bashrc

Verify Setup

bash

# Run GemKit doctor
gk doctor

# Should show:
# ✓ @google/gemini-cli installed
# ✓ @anthropic-ai/claude-cli installed
# ✓ GEMINI_API_KEY configured
# ✓ ANTHROPIC_API_KEY configured

Configuration

Directory Structure

GemKit maintains parallel directory structures for each provider:

markdown

project/
├── .gemini/                  # Gemini provider
│   ├── agents/
│   │   ├── code-executor/
│   │   ├── researcher/
│   │   └── tester/
│   └── extensions/
│       ├── frontend-development/
│       ├── backend-development/
│       └── testing/
│
├── .claude/                  # Claude provider (optional)
│   ├── agents/
│   │   ├── code-executor/   # Converted or custom
│   │   ├── researcher/
│   │   └── tester/
│   └── skills/
│       ├── frontend-development/
│       ├── backend-development/
│       └── testing/
│
└── .gk.json                  # GemKit configuration

Best practice: Start with .gemini/ agents and convert to .claude/ as needed.

.gk.json Configuration

json

{
  "version": "1.0.0",
  "providers": {
    "gemini": {
      "enabled": true,
      "apiKey": "${GEMINI_API_KEY}",
      "defaultModel": "gemini-2.0-flash",
      "agentsPath": ".gemini/agents",
      "extensionsPath": ".gemini/extensions"
    },
    "claude": {
      "enabled": true,
      "apiKey": "${ANTHROPIC_API_KEY}",
      "defaultModel": "claude-3-sonnet",
      "agentsPath": ".claude/agents",
      "skillsPath": ".claude/skills"
    }
  },
  "defaultProvider": "gemini",
  "modelMapping": {
    "gemini-2.0-flash": "claude-3-haiku",
    "gemini-2.0-pro": "claude-3-sonnet",
    "gemini-2.5-pro": "claude-3-opus"
  }
}

Spawning Agents with Claude

Basic Usage: The --cli Flag

bash

# Use Gemini (default)
gk agent spawn --agent researcher --prompt "Research AI trends"

# Use Claude explicitly
gk agent spawn --cli claude --agent researcher --prompt "Research AI trends"

The --cli flag tells GemKit which provider to use for that specific invocation.

Model Selection

bash

# Use specific Claude model
gk agent spawn --cli claude --model claude-3-opus --agent code-executor \
  --prompt "Design a distributed caching system"

# Use specific Gemini model
gk agent spawn --cli gemini --model gemini-2.5-pro --agent researcher \
  --prompt "Research database sharding strategies"

With Context and Skills

bash

# Claude with context
gk agent spawn --cli claude --agent code-executor \
  --context src/services/auth.ts,src/types/user.ts \
  --skills "backend-development" \
  --prompt "Add OAuth 2.1 authentication"

# Gemini with context (comparison)
gk agent spawn --cli gemini --agent code-executor \
  --context src/services/auth.ts,src/types/user.ts \
  --skills "backend-development" \
  --prompt "Add OAuth 2.1 authentication"

Model Mapping Reference

GemKit automatically maps equivalent models between providers:

Gemini Model	Claude Equivalent	Use Case	Cost
gemini-2.0-flash	claude-3-haiku	Fast tasks, high volume	$
gemini-2.0-pro	claude-3-sonnet	Balanced performance	$$
gemini-2.5-pro	claude-3-opus	Complex reasoning	$$$
gemini-2.0-flash-8b	claude-3-haiku	Ultra-fast simple tasks	$

Customizing Model Mapping

Edit .gk.json to define custom mappings:

json

{
  "modelMapping": {
    "gemini-2.0-flash": "claude-3-haiku",
    "gemini-2.0-pro": "claude-3.5-sonnet",
    "gemini-2.5-pro": "claude-3-opus"
  }
}

Dual-Provider Workflows

Pattern 1: Research with Gemini, Implement with Claude

bash

# Phase 1: Fast research with Gemini Flash
gk agent spawn --cli gemini --model gemini-2.0-flash \
  --agent researcher \
  --prompt "Research best practices for React Server Components"

# Output saved to: research-results.md

# Phase 2: Implementation with Claude Sonnet (better code quality)
gk agent spawn --cli claude --model claude-3-sonnet \
  --agent code-executor \
  --context research-results.md,src/components/ \
  --skills "frontend-development" \
  --prompt "Implement Server Components based on research findings"

Why this works:

Gemini Flash is 3x cheaper and faster for research
Claude Sonnet excels at complex implementation
Total cost optimized while maintaining quality

Pattern 2: Parallel Implementation Comparison

bash

# Spawn same task on both providers
gk agent spawn --cli gemini --agent code-executor \
  --prompt "Implement caching layer for API" &

gk agent spawn --cli claude --agent code-executor \
  --prompt "Implement caching layer for API" &

# Wait for both to complete
wait

# Compare results and choose the best implementation

Pattern 3: Cost-Optimized Feature Development

bash

#!/bin/bash
# smart-implementation.sh

TASK="$1"
COMPLEXITY="$2"  # simple, medium, complex

case $COMPLEXITY in
  simple)
    # Use cheap Gemini Flash
    gk agent spawn --cli gemini --model gemini-2.0-flash \
      --agent code-executor --prompt "$TASK"
    ;;
  medium)
    # Use Gemini Pro (balanced)
    gk agent spawn --cli gemini --model gemini-2.0-pro \
      --agent code-executor --prompt "$TASK"
    ;;
  complex)
    # Use Claude Opus (highest quality)
    gk agent spawn --cli claude --model claude-3-opus \
      --agent code-executor --prompt "$TASK"
    ;;
esac

Usage:

bash

./smart-implementation.sh "Add contact form" simple
./smart-implementation.sh "Implement GraphQL subscriptions" complex

Pattern 4: Fallback on Provider Error

bash

#!/bin/bash
# agent-with-fallback.sh

AGENT="$1"
PROMPT="$2"

# Try Gemini first
if ! gk agent spawn --cli gemini --agent "$AGENT" --prompt "$PROMPT"; then
  echo "Gemini failed, falling back to Claude..."
  gk agent spawn --cli claude --agent "$AGENT" --prompt "$PROMPT"
fi

Converting Agents Between Providers

Gemini to Claude

bash

# Convert existing Gemini agents for use with Claude
gk convert gemini-agent .gemini/agents/code-executor \
  --output .claude/agents/

# Now available for Claude spawning
gk agent spawn --cli claude --agent code-executor --prompt "Test"

Claude to Gemini

bash

# If you have existing Claude agents
gk convert claude-agent .claude/agents/reviewer \
  --output .gemini/agents/

# Now available for Gemini spawning
gk agent spawn --cli gemini --agent reviewer --prompt "Test"

See also: gk convert documentation

Tool Mapping

GemKit automatically maps tools between providers:

Tool Function	Gemini Tool	Claude Tool
Read files	`read_file`	`Read`
Write files	`write_file`	`Write`
Edit files	`replace`	`Edit`
Run commands	`run_shell_command`	`Bash`
Search code	`search_file_content`	`Grep`
List files	`glob`	`Glob`
Web search	`google_web_search`	`WebSearch`

Agent definitions are tool-agnostic - GemKit handles translation automatically.

Performance Comparison

Real-World Benchmarks

Based on internal testing with common development tasks:

Task Type	Gemini Flash	Gemini Pro	Claude Sonnet	Claude Opus
Simple CRUD	8s ($0.03)	12s ($0.08)	15s ($0.12)	22s ($0.28)
Complex algorithm	25s ($0.12)	32s ($0.22)	28s ($0.18)	35s ($0.42)
Refactoring	18s ($0.08)	24s ($0.16)	22s ($0.14)	30s ($0.35)
Test generation	12s ($0.05)	16s ($0.11)	14s ($0.09)	20s ($0.24)

Insights:

Gemini Flash: Best for speed and cost
Claude Sonnet: Best quality/cost ratio
Claude Opus: Highest quality, slowest, most expensive
Gemini Pro: Balanced option

Cost Analysis

Provider Pricing (2026)

Gemini API:

gemini-2.0-flash: $0.015/1K input, $0.025/1K output
gemini-2.0-pro: $0.025/1K input, $0.050/1K output
gemini-2.5-pro: $0.050/1K input, $0.100/1K output

Claude API:

claude-3-haiku: $0.025/1K input, $0.125/1K output
claude-3-sonnet: $0.300/1K input, $1.500/1K output
claude-3-opus: $1.500/1K input, $7.500/1K output

Cost Optimization Strategy

markdown

Development Phase          Recommended Provider
──────────────────────────────────────────────────────
Research & exploration    Gemini Flash (cheapest)
Simple implementations    Gemini Flash or Pro
Complex features          Claude Sonnet (quality)
Critical systems          Claude Opus (highest quality)
High-volume testing       Gemini Flash (cost effective)

Monitoring and Analytics

Track Usage by Provider

bash

# View all sessions
gk session list

# Filter by provider (check agent model in session details)
gk session view <session-id>

# Compare token costs
gk tokens summary --model gemini-2.0-flash
gk tokens summary --model claude-3-sonnet

Cost Comparison Report

bash

#!/bin/bash
# provider-cost-report.sh

echo "Gemini Usage:"
gk tokens summary --json | jq '.by_model | to_entries | map(select(.key | startswith("gemini")))'

echo "\nClaude Usage:"
gk tokens summary --json | jq '.by_model | to_entries | map(select(.key | startswith("claude")))'

Best Practices

Start with Gemini as default - Cheaper for most tasks, Claude when needed
Use --cli flag strategically - Be explicit about provider choice per task
Map models appropriately - Ensure quality expectations match chosen model
Monitor costs per provider - Use gk tokens to track spending patterns
Keep agents provider-agnostic - Design agents to work with both ecosystems
Test on both providers - Compare quality and cost for your specific use cases
Document provider choices - Note why specific providers chosen for tasks
Use conversion sparingly - Only convert agents when truly needed for both

Troubleshooting

"Claude CLI not found"

bash

npm install -g @anthropic-ai/claude-cli
gk doctor --check dependencies

"ANTHROPIC_API_KEY not set"

bash

export ANTHROPIC_API_KEY=sk-ant-...
gk doctor --check api

"Agent not found for Claude provider"

bash

# Convert from Gemini to Claude
gk convert gemini-agent .gemini/agents/code-executor --output .claude/agents/

"Different results between providers"

Normal - models have different strengths
Adjust prompts for each provider's style
Use more explicit instructions for consistency

gk convert - Convert agents between providers
gk agent - Agent spawning and management
gk tokens - Cost tracking across providers
Configuration Reference - Provider settings
Creating Custom Agents - Provider-agnostic agent design

Overview

Why Use Claude with GemKit?

Use Cases for Dual-Provider Workflows

Provider Architecture

Prerequisites

Required Software

API Keys

Verify Setup

Configuration

Directory Structure

.gk.json Configuration

Spawning Agents with Claude

Basic Usage: The --cli Flag

Model Selection

With Context and Skills

Model Mapping Reference

Customizing Model Mapping

Dual-Provider Workflows

Pattern 1: Research with Gemini, Implement with Claude

Pattern 2: Parallel Implementation Comparison

Pattern 3: Cost-Optimized Feature Development

Pattern 4: Fallback on Provider Error

Converting Agents Between Providers

Gemini to Claude

Claude to Gemini

Tool Mapping

Performance Comparison

Real-World Benchmarks

Cost Analysis

Provider Pricing (2026)

Cost Optimization Strategy

Monitoring and Analytics

Track Usage by Provider

Cost Comparison Report

Best Practices

Troubleshooting

Related Documentation