gemini-bridge: Instructions file for Claude Code

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!')"