8000 gemini-bridge/CLAUDE.md at v1.2.0 · eLyiN/gemini-bridge · GitHub
[go: up one dir, main page]

Skip to content

Latest commit

 

History

History
269 lines (214 loc) · 10.3 KB

CLAUDE.md

File metadata and controls

269 lines (214 loc) · 10.3 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Gemini Bridge is a lightweight MCP (Model Context Protocol) server that enables Claude Code to interact with Google's Gemini AI through the official CLI. The project follows extreme simplicity principles from Carmack and Torvalds - doing ONE thing well: bridging Claude to Gemini CLI.

Key Characteristics:

  • Zero API costs (uses free Gemini CLI)
  • Stateless architecture with no session management
  • Direct subprocess integration for optimal performance
  • Inline file guardrails with optional delegation to Gemini CLI's @path expansion
  • Production-ready with professional CI/CD automation

Development Commands

Prerequisites

  • Gemini CLI: npm install -g @google/gemini-cli
  • Authentication: gemini auth login
  • Verify: gemini --version

Installation & Setup

Development Mode:

# Clone and install in development mode
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge
pip install -e .

# Run directly from source
python -m src

Production Installation:

# Install from PyPI
pip install gemini-bridge

# Or use uvx (recommended)
uvx gemini-bridge

Claude Code Integration:

# Production installation (recommended)
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

# Development mode (from local source)
claude mcp add gemini-bridge -s user -- python -m src

Testing & Verification

# Test CLI availability
gemini --version

# Test basic functionality
python -c "from src.mcp_server import execute_gemini_simple; print(execute_gemini_simple('Hello', '.'))"

# Test package installation
python -c "import src; print(f'Gemini Bridge v{src.__version__}')"

# Run automated tests
pytest

Build & Distribution

# Clean build
rm -rf dist/ build/ *.egg-info

# Build package
uvx --from build pyproject-build

# Verify build
pip install dist/*.whl
python -c "import src; print('Package works!')"

Architecture

Core Design Principles

  • CLI-First: Direct subprocess calls to gemini command
  • Stateless: Each tool call is independent with no session state
  • Adaptive Timeout: Defaults to 60 seconds; override via env var or timeout_seconds
  • Attachment Guardrails: Inline mode enforces byte/quantity caps; at_command mode lets Gemini CLI manage files
  • Fail-Fast: Clear error messages with simple error handling
  • Zero Dependencies: Only mcp>=1.0.0 and external Gemini CLI

Key Components

src/mcp_server.py - Main server implementation

  • consult_gemini(query, directory, model, timeout_seconds) - Simple CLI bridge
  • consult_gemini_with_files(query, directory, files, model, timeout_seconds, mode) - File-attachment support with inline/@ toggle
  • _normalize_model_name() - Model name normalization (flash/pro)
  • _prepare_inline_payload() / _prepare_at_command_prompt() - File preprocessing helpers with safeguards
  • execute_gemini_simple() / execute_gemini_with_files() - Core CLI execution with per-call timeout overrides

Model Support:

  • Default: gemini-2.5-flash (optimal performance/cost)
  • Available: flash, pro (auto-normalized to full names)
  • Custom models accepted if prefixed with gemini-

File Structure

gemini-bridge/
├── src/
│   ├── __init__.py              # Package entry point and version
│   ├── __main__.py              # Module execution entry point  
│   └── mcp_server.py            # Main MCP server implementation
├── .github/                     # GitHub templates and workflows
├── pyproject.toml               # Python package configuration
├── README.md                    # Main documentation
├── CONTRIBUTING.md              # Development guidelines
├── SECURITY.md                  # Security policy
├── CHANGELOG.md                 # Release history
└── LICENSE                      # MIT license

MCP Tools Available

consult_gemini

  • Purpose: Direct CLI bridge for simple queries
  • Parameters:
    • query (required): The question or prompt to send to Gemini
    • directory (required): Working directory for the query
    • model (optional): Model name (flash, pro, or custom)
    • timeout_seconds (optional): Override execution timeout for this call
  • Use Case: General questions, code analysis without file attachments
  • Example: General programming questions, code explanations

consult_gemini_with_files

  • Purpose: CLI bridge with file attachments for detailed analysis
  • Parameters:
    • query (required): The question or prompt to send to Gemini
    • directory (required): Working directory for the query
    • files (required list): List of file paths to attach
    • model (optional): Model name (flash, pro, or custom)
    • timeout_seconds (optional): Override execution timeout for this call
    • mode (optional): "inline" (default) or "at_command" to delegate @path expansion
  • Use Case: File-specific analysis, multi-file comparisons, code reviews
  • File Handling: Inline mode streams truncated snippets with warnings; at_command mode passes @ directives for Gemini CLI to resolve
  • Example: Code reviews, debugging specific files, analyzing project structure

Error Handling & Troubleshooting

Common Error Patterns

  • "CLI not available": Gemini CLI not installed or not in PATH
    • Solution: npm install -g @google/gemini-cli
  • "Authentication required": Not logged into Gemini
    • Solution: gemini auth login
  • "Timeout after X seconds": Query too complex or large files
    • Solution: Increase timeout via GEMINI_BRIDGE_TIMEOUT or timeout_seconds
    • Alternative: Switch to mode="at_command" or break into smaller batches
  • "Directory does not exist": Invalid directory parameter
    • Solution: Use absolute paths or verify directory exists
  • "No files provided": Missing files parameter for file-attachment mode
    • Solution: Provide at least one valid file path
  • Warnings about truncation or limits: Inline guardrails trimmed content
    • Solution: Review the warning text, rerun with mode="at_command", or adjust the GEMINI_BRIDGE_MAX_INLINE_* environment variables

Debugging Steps

  1. Verify Gemini CLI: gemini --version
  2. Test Authentication: gemini "Hello"
  3. Check Package: python -c "import src; print('OK')"
  4. Test MCP Tools: Use simple queries first, then add complexity

Development Guidelines

Code Standards

  • Python 3.9+ Compatibility: Use modern Python features responsibly
  • Type Hints: Include type a 7F3D nnotations for all functions
  • Error Handling: Explicit error messages with actionable solutions
  • Documentation: Keep CLAUDE.md, README.md, and code comments in sync

Testing Requirements

  • Manual Testing: Verify both MCP tools work with various queries
  • Automated Tests: Run pytest to cover helper logic and CLI interactions
  • Integration Testing: Test with Claude Code in development
  • Cross-Platform: Ensure compatibility across Python versions (3.9-3.12)
  • CI/CD Verification: All GitHub Actions must pass

Performance Characteristics

  • Startup Time: Near-instant MCP server startup
  • Memory Usage: Minimal memory footprint (~10MB)
  • Execution Time: Limited by configurable timeout (default: 60 seconds)
  • Scalability: Stateless design allows multiple concurrent requests

Package Information

Dependencies

  • Required: mcp>=1.0.0
  • External: Gemini CLI (npm package @google/gemini-cli)
  • Python: Compatible with Python 3.9+

Installation Details

  • Package Name: gemini-bridge
  • PyPI: Available as pip install gemini-bridge
  • Entry Point: gemini-bridge = "src:main"
  • Module Execution: python -m src

Configuration

  • Default Model: gemini-2.5-flash for optimal performance
  • Timeout: Configurable via GEMINI_BRIDGE_TIMEOUT environment variable (default: 60 seconds)
  • Working Directory: Configurable per request
  • File Encoding: UTF-8 with error handling

Timeout Configuration

Set the GEMINI_BRIDGE_TIMEOUT environment variable to customize execution timeout:

# Example: 2-minute timeout for large file analysis
claude mcp add gemini-bridge -s user --env GEMINI_BRIDGE_TIMEOUT=120 -- uvx gemini-bridge

Valid Values:

  • Positive integers (seconds)
  • Default: 60 seconds if not set or invalid
  • Recommended: 120-300 seconds for large files or complex queries

Security Considerations

Secure Practices

  • Input Validation: Basic validation for file paths and queries
  • Process Isolation: Subprocess execution for CLI calls
  • No Network Exposure: All network requests handled by Gemini CLI
  • Minimal Attack Surface: Simple, stateless architecture

Best Practices

  • Keep Gemini CLI updated: npm update -g @google/gemini-cli
  • Use absolute paths for file operations
  • Validate directory permissions before operations
  • Monitor for unusual CLI behavior or errors

Release & Deployment

Version Management

  • Semantic Versioning: MAJOR.MINOR.PATCH format
  • Current Version: 1.0.5 (check src/__init__.py)
  • Release Tags: Git tags trigger automated PyPI publishing

Deployment Options

  1. PyPI + uvx (Recommended): uvx gemini-bridge
  2. PyPI + pip: pip install gemini-bridge
  3. Development: python -m src from source

CI/CD Pipeline

  • GitHub Actions: Automated testing on Python 3.9-3.12
  • PyPI Publishing: Triggered by version tags (v*.*)
  • Quality Gates: Build verification, import testing, package validation

Support & Community

Getting Help

Contributing

  • Guidelines: See CONTRIBUTING.md for detailed development setup
  • Code Style: Follow PEP 8, use type hints, include docstrings
  • Testing: Manual testing required, automated CI verification
  • Community: Respectful, constructive feedback welcome

This CLAUDE.md file serves as the authoritative development guide for the Gemini Bridge project. Keep it updated as the project evolves, ensuring consistency with README.md, CONTRIBUTING.md, and actual implementation.

0