We've transformed Gemini Oddity into an enterprise-ready solution with comprehensive OAuth 2.0 authentication, replacing simple API keys with a secure, token-based authentication system that follows industry best practices.

• 🔐 Full OAuth 2.0 Implementation: Authorization code flow with PKCE
• 🔄 Automatic Token Management: Seamless refresh with encrypted storage
• 🛡️ Strong Encryption: AES-256-CBC for sensitive data
• 🎨 Interactive Setup Wizard: ANSI-colored terminal onboarding
• 🧪 Comprehensive Tests: 85%+ coverage with security & perf checks
• 📚 Enterprise Docs: Setup, migration, and security guides
• 🏭 CI/CD: Automated tests across OSes and Bash versions

Gemini Oddity automatically delegates complex code analysis tasks from Claude Code to Google Gemini, combining Claude's reasoning capabilities with Gemini's large context processing power. Now with OAuth 2.0, it's secure enough for enterprise deployment.

graph TB
    subgraph "Claude Code"
        CC[Claude Code CLI]
        TC[Tool Call]
    end
    
    subgraph "OAuth-Enhanced Bridge"
        HS[Hook System]
        DE[Decision Engine]
        OM[🔐 OAuth Manager]
        EM[🔒 Encryption Module]
        PC[Path Converter]
        CH[Cache Layer]
    end
    
    subgraph "External APIs"
        GA[Google OAuth]
        GC[Gemini CLI]
        GM[Gemini API]
    end
    
    CC -->|PreToolUse Hook| HS
    HS --> PC
    PC --> DE
    DE -->|Needs Auth| OM
    OM -->|Secure Token| EM
    EM -->|Encrypted Storage| OM
    OM <-->|OAuth Flow| GA
    DE -->|Delegate?| CH
    CH -->|Authorized| GC
    GC --> GM
    GM -->|Analysis| CH
    CH -->|Response| HS
    HS -->|Result| CC
    
    style OM fill:#4CAF50
    style EM fill:#FF9800
    style GA fill:#2196F3

• Token Limit: Content exceeds ~50k tokens (~200KB)
• Multi-File Tasks: ≥3 files for Task operations
• Safety Limits: Content ≤10MB and ≤800k tokens for Gemini
• Security: Automatic exclusion of sensitive files (*.secret, *.key, *.env)

• Claude Code CLI installed
• Google Gemini CLI v1.0.0+
• Bash 4.0+ (macOS/Linux)
• jq, curl, openssl (installed automatically if missing)

# Clone the repository
git clone https://github.com/good-night-oppie/gemini-oddity
cd gemini-oddity

# Run the interactive setup wizard
./setup/interactive-setup.sh

# The colorful wizard will guide you through:
# 1. Choosing OAuth authentication (recommended)
# 2. Setting up Google OAuth credentials
# 3. Configuring encryption password
# 4. Completing OAuth authorization
# 5. Validating your setup

# Test the installation
./test/test-runner.sh

# Use Claude Code normally - OAuth is handled automatically!
claude "analyze all Python files in this project"

Upgrading from v1.x? We've got you covered:

# Automatic migration with backup
./setup/interactive-setup.sh --migrate

# Your config is backed up to config.backup.json
# The wizard handles the entire OAuth setup

See Migration Guide for detailed instructions.

Our OAuth implementation is enterprise-ready:

• Authorization Code Flow with PKCE: Maximum security for token exchange
• Automatic Token Refresh: Tokens refresh 5 minutes before expiration
• Encrypted Token Storage: AES-256-CBC encryption at rest
• Session Management: Intelligent session handling with recovery
• Multi-Provider Support: Easy integration with various OAuth providers

# Check authentication status
./hooks/lib/oauth-handler.sh status

# Manual token refresh (usually automatic)
./hooks/lib/oauth-handler.sh refresh

# View token expiration
cat ~/.gemini-oddity/tokens/token_info.json | jq .expires_at

Military-grade security throughout:

• AES-256-CBC Encryption: All tokens and sensitive data encrypted
• XDG Compliance: Proper directory permissions (700/600)
• Secret Redaction: Automatic removal from logs
• Security Audits: Built-in vulnerability scanning
• Rate Limiting: Automatic handling of API limits

# Run security audit
./test/security/test-security-audit.sh

# Test encryption
./hooks/lib/encryption-core.sh test

# Check file permissions
./test/security/test-security-audit.sh | grep permissions

Professional testing at every level:

# Run full test suite with coverage
./test/run-all-tests.sh --coverage

# Run specific test types
./test/run-all-tests.sh --unit-only
./test/run-all-tests.sh --security-only
./test/performance/test-performance-benchmarks.sh

Beautiful terminal UI with ANSI colors:

╔════════════════════════════════════════════╗
║        Gemini Oddity Setup Wizard          ║
╠════════════════════════════════════════════╣
║                                            ║
║  Welcome! Let's configure your bridge.    ║
║                                            ║
║  Authentication Method:                    ║
║    [1] OAuth 2.0 (Recommended) ✓          ║
║    [2] API Key (Legacy)                   ║
║                                            ║
║  Please select [1-2]: _                   ║
║                                            ║
╚════════════════════════════════════════════╝

• Color-coded prompts for clarity
• Progress indicators
• Intelligent validation
• Automatic dependency installation
• Migration support

Built for speed and efficiency:

// ~/.gemini-oddity/config.json
{
  "auth_type": "oauth",
  "provider": "gemini",
  "oauth": {
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "auth_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
    "token_endpoint": "https://oauth2.googleapis.com/token",
    "redirect_uri": "http://localhost:8080/callback",
    "scope": "https://www.googleapis.com/auth/generative-language.retriever",
    "auto_refresh": true,
    "pkce_enabled": true
  },
  "encryption": {
    "enabled": true,
    "algorithm": "aes-256-cbc"
  }
}

# hooks/config/debug.conf
MIN_FILES_FOR_GEMINI=3          # Delegate Task with ≥3 files
CLAUDE_TOKEN_LIMIT=50000        # ~200KB before delegation
GEMINI_TOKEN_LIMIT=800000       # Gemini's max capacity
MAX_TOTAL_SIZE_FOR_GEMINI=10485760  # 10MB safety limit

# OAuth Security
OAUTH_TOKEN_REFRESH_MARGIN=300  # Refresh 5min before expiry
OAUTH_ENCRYPTION_ENABLED=true   # Encrypt stored tokens
OAUTH_AUTO_REFRESH=true         # Auto-refresh expired tokens

• OAuth Setup Guide - Complete OAuth configuration
• Migration Guide - Upgrade from API keys
• Troubleshooting - Common issues and solutions

• Security Guide - Security implementation details
• API Reference - Provider API documentation
• Contributing - Development guidelines

Our GitHub Actions pipeline ensures quality:

# .github/workflows/test.yml
- Unit Tests (Bash 4.4, 5.0, 5.1)
- Integration Tests with Mock OAuth
- Security Vulnerability Scanning
- Performance Benchmarks
- E2E User Journey Tests
- Cross-platform (Ubuntu, macOS)

# Full test suite
./test/run-all-tests.sh --coverage

# Security audit
./test/security/test-security-audit.sh

# Performance benchmarks
./test/performance/test-performance-benchmarks.sh

# OAuth integration tests
./test/integration/test-oauth-flow.sh

# Check status
./hooks/lib/oauth-handler.sh status

# Verify config
cat ~/.gemini-oddity/config.json | jq '.oauth'

# Force refresh
./hooks/lib/oauth-handler.sh refresh --force

# Re-run setup
./setup/interactive-setup.sh --reconfigure

# Check expiry
cat ~/.gemini-oddity/tokens/token_info.json | jq .expires_at

# Clear tokens
rm -rf ~/.gemini-oddity/tokens/*

# Re-authenticate
./setup/interactive-setup.sh --reauth

# Test encryption
./hooks/lib/encryption-core.sh test

# Reset encryption
export OAUTH_ENCRYPTION_PASSWORD="new-password"
./setup/interactive-setup.sh --reset-encryption

See Troubleshooting Guide for more solutions.

# Watch OAuth operations live
tail -f logs/debug/$(date +%Y%m%d).log | grep -i oauth

# Monitor Gemini delegations
tail -f logs/debug/$(date +%Y%m%d).log | grep -i gemini

# Check performance metrics
grep "execution_time" logs/debug/$(date +%Y%m%d).log | awk '{print $NF}'

# Set debug level (0=off, 1=basic, 2=verbose, 3=trace)
echo "DEBUG_LEVEL=3" >> hooks/config/debug.conf

# Enable dry run (no API calls)
echo "DRY_RUN=true" >> hooks/config/debug.conf

# Capture all inputs for debugging
echo "CAPTURE_INPUTS=true" >> hooks/config/debug.conf

We welcome contributions! See Contributing Guidelines.

# Fork and clone
git clone https://github.com/good-night-oppie/gemini-oddity
cd gemini-oddity

# Create feature branch
git checkout -b feature/your-feature

# Run tests before committing
./test/run-all-tests.sh

# Submit PR with test coverage

• OAuth Provider Plugins - Third-party provider support
• Token Vault Integration - HashiCorp Vault support
• Multi-User Support - Team collaboration
• Web Dashboard - OAuth management UI
• Audit Logging - Compliance-ready trails

• GraphQL API support
• Kubernetes deployment
• Docker containerization
• Terraform modules
• Prometheus metrics

Gemini Oddity v2.0 implements enterprise-grade security:

• OAuth 2.0 with PKCE: Industry-standard authentication
• AES-256-CBC Encryption: Military-grade encryption
• Token Rotation: Automatic refresh before expiration
• Secret Redaction: No secrets in logs
• Security Audits: Built-in vulnerability scanning
• File Exclusions: Automatic sensitive file filtering

Report security issues to [email protected]

MIT License - see LICENSE file

Built on the original Gemini Oddity architecture with major enhancements:

• v1.0: Original bridge concept and implementation
• v2.0: Complete OAuth 2.0 system, enterprise security, comprehensive testing

Special thanks to:

• Reddit user for the original Claude-Gemini integration idea
• Claude Code team for the excellent hook system
• Google for Gemini API and CLI tools
• Open source community for testing and feedback