🌉 Claude-Gemini Multimodal Bridge

Unifying the Power of AI.

An MCP bridge that seamlessly integrates Claude Code, Antigravity CLI, and Google AI Studio

🇯🇵 日本語版 • 📦 NPM • 🐛 Issues

🤔 Why CGMB?

🔄 Multi-Model Orchestration

Optimally integrates Claude's reasoning power, Antigravity CLI's search capabilities, and AI Studio's generation power. Ahead of the 2026 AI trend: "Specialized AI Collaboration"

⚡ One Install, Two Setup Steps

npm install -g wires up the MCP integration. You then install agy and add an AI Studio API key

🎯 MCP Standard Compliant

Follows the Anthropic Model Context Protocol. 179 tests run on Linux, Windows and macOS in CI on every push

✨ What's New in v1.2.2

Housekeeping. Nothing users can reach behaves differently — the code removed could not be reached at all.

| Change | Description | |--------|-------------| | 🧹 Four dead call paths removed | The layer asked the MCP server for tools it has never implemented. Unreachable today, but that is what --script was too | | 🗑️ 740 lines of unused modules removed | PromptOptimizer and quotaMonitor had no reference anywhere and were still being shipped | | 🔒 The layer and its server are now checked against each other | A test starts the server, asks what it implements, and fails if the layer can name anything else |

Previously, in v1.2.1

| Fix | Description | |-----|-------------| | 🎯 Answers reach the caller who asked | Concurrent AI Studio requests took each other's replies; each now gets its own | | 🚪 cgmb exits when it is done | The shared MCP server is ended rather than left running | | 🔑 .env stays in your project | Installation directories and ~/.cgmb are opt-in via CGMB_ENV_PATH, not read by default | | 🔍 Search cache answers the question asked | Different years and different models are no longer treated as one entry | | 🧩 Workflow steps see their inputs | Parallel steps publish output; hybrid runs honour dependsOn |

Previously, in v1.2.0

| Feature | Description | |---------|-------------| | 🔄 Antigravity CLI | The search layer moved off the discontinued Gemini CLI to agy | | 🖥️ Three-OS Support | Linux, Windows and macOS verified in CI on every push | | 🚀 Updated Models | gemini-3-pro-image, gemini-3.1-flash-tts-preview; the retired gemini-2.0-flash-exp is gone | | 🎯 targetLayer Honoured | Naming a layer routes there — including claude | | 🔧 CLAUDE_CODE_PATH | Now reaches the executable search, as documented | | 🪟 Full Windows Support | Native support for both CLI and MCP (since v1.1.0) | | 🔐 OAuth Authentication | OS keyring for agy; file-based auth for Claude Code | | 📊 Smart Routing | PDF URLs to AI Studio, web pages to Antigravity CLI |

🏗️ Architecture

flowchart TD
    A[Claude Code] --> B[CGMB]

    B --> C[Antigravity CLI]
    B --> D[Claude Code]
    B --> E[AI Studio]

| Layer | Specialization | Timeout | |:-----:|:---------------|:-------:| | 🔍 Antigravity CLI (agy) | Web search, real-time information | 90s | | 🧠 Claude Code | Complex reasoning, code analysis | 300s | | 🎨 AI Studio | Image generation, audio synthesis, OCR | 300s |

🚀 Quick Start

📋 Prerequisites

• Node.js ≥ 22.0.0
• Claude Code CLI installed
• Antigravity CLI (agy) ≥ 1.1.7 — installed separately, see below

📦 Installation

npm install -g claude-gemini-multimodal-bridge

💡 The postinstall script automatically:

• Checks for the Antigravity CLI and prints install instructions if missing
• Sets up Claude Code MCP integration
• Creates .env template
• Verifies system requirements

🔑 Environment Setup

Create a .env file in your working directory:

AI_STUDIO_API_KEY=your_api_key_here

🔗 Get API key: https://aistudio.google.com/app/apikey

🎯 Antigravity CLI Setup

Google discontinued Gemini CLI for individual accounts on 2026-06-18. The search layer now runs on its successor, the Antigravity CLI (agy), which is not distributed on npm and must be installed separately:

# Windows (PowerShell)
irm https://antigravity.google/cli/install.ps1 | iex

# macOS / Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash

Then sign in once — this opens a browser and stores the OAuth token in your OS keyring. There is no API key and no agy auth subcommand:

agy

Verify with agy models; CGMB requires agy 1.1.7 or newer (earlier builds print nothing when stdout is not a terminal).

💬 Get Started with Claude Code

I installed CGMB via NPM. Please check my current environment for the cgmb command and help me use it.

💡 Usage Examples

CGMB integrates seamlessly with Claude Code. Just use the "CGMB" keyword:

# 🎨 Image generation
"CGMB generate an image of a futuristic city"

# 📄 Document analysis (use absolute paths)
"CGMB analyze the document at /full/path/to/report.pdf"

# 🌐 URL analysis
"CGMB analyze https://example.com/document.pdf"

# 🔍 Web search
"CGMB search for the latest AI news"

# 🎵 Audio generation
"CGMB create audio saying 'Welcome to our podcast'"

# 📝 OCR-enabled PDF analysis
"CGMB analyze this scanned PDF document with OCR"

🔄 Automatic Routing

1. Include "CGMB" in your Claude Code request
2. CGMB automatically routes to the optimal AI layer:
   • 🔍 Antigravity CLI: Web search, latest information
   • 🎨 AI Studio: Images, audio, file processing
   • 🧠 Claude Code: Complex reasoning, code analysis

🤖 Models Used

| Purpose | Model ID | Layer | |:-------:|:---------|:-----:| | 🔍 Web Search | gemini-3.6-flash-low | Antigravity CLI | | 🎨 Image Generation | gemini-2.5-flash-image | AI Studio | | 🖼️ Image Generation (high quality) | gemini-3-pro-image | AI Studio | | 🎵 Audio Generation | gemini-3.1-flash-tts-preview | AI Studio | | 📄 Document Processing | gemini-2.5-flash | AI Studio | | 📝 OCR/Text Extraction | gemini-2.5-flash | AI Studio | | 🔮 General Multimodal | gemini-2.5-flash | AI Studio |

Antigravity model IDs must appear in agy models; AI Studio IDs live in AI_MODELS in src/core/types.ts.

📈 Performance

What the implementation actually does, rather than a benchmark:

| Mechanism | Where it applies | Tunable with | |-----------|------------------|--------------| | Search result cache | Repeated web-search prompts | ENABLE_CACHING, CACHE_TTL, MAX_CACHE_ENTRIES | | Authentication cache | agy and Claude Code probes, cached for hours rather than per call | — | | Lazy layer initialisation | A layer is started on first use, not at startup | — | | Retry with exponential backoff | Transient API and CLI failures | MAX_RETRIES, RETRY_DELAY |

Throughput depends on which layer answers and on the upstream API, so no fixed numbers are quoted here.

📄 PDF Processing & OCR

✨ OCR Features

• ✅ Supports both text-based and scanned PDFs
• ✅ Automatic OCR detection
• ✅ Native OCR processing via Gemini File API
• ✅ Multi-language support

📋 Processing Workflow

PDF Input → Upload → OCR Processing → Content Analysis → Output Results

📁 Supported Formats

• Text-based PDFs
• Scanned PDFs (OCR processing)
• Image-based PDFs (OCR conversion)
• Mixed content
• Complex layouts (tables, charts, formatted content)

📂 File Organization

Generated content is automatically organized:

output/
├── images/     # 🎨 Generated images
├── audio/      # 🎵 Generated audio files
└── documents/  # 📄 Processed documents

Files are written to these directories under the working directory you ran CGMB from, and the path of each generated file is returned in the response.

The MCP tools CGMB exposes to Claude Code are cgmb, cgmb_get_layer_requirements, cgmb_document_analysis, cgmb_multimodal_process and cgmb_workflow_orchestration.

🔧 Configuration

Environment Variables

# Required
AI_STUDIO_API_KEY=your_api_key_here

# Search layer (Antigravity CLI)
ANTIGRAVITY_MODEL=gemini-3.6-flash-low   # must appear in `agy models`
ANTIGRAVITY_TIMEOUT=90000                # per-call budget, ms
ANTIGRAVITY_CLI_PATH=                    # unset = auto-detect

# Claude layer
CLAUDE_CODE_PATH=/usr/local/bin/claude   # for installs outside the defaults

# Caching and logging
ENABLE_CACHING=true
CACHE_TTL=3600
LOG_LEVEL=info

# Deprecated fallback for AI_STUDIO_API_KEY -- prefer the latter
GEMINI_API_KEY=your_api_key_here

🔐 Which files may be sent to Google

The AI Studio layer uploads file contents to Google, so it only reads from the directory CGMB was started in. To analyse files kept elsewhere, list those directories explicitly:

# ";" separated on Windows, ":" elsewhere
CGMB_ALLOWED_ROOTS=C:\Users\me\Documents;D:\shared

📍 Where .env is read from

CGMB reads .env from the directory you run it in. Up to 1.2.0 it also read CGMB's own installation directory, the global npm directory and ~/.cgmb, so a file left in any of those was picked up by every project on the machine — along with its AI_STUDIO_API_KEY and its CGMB_ALLOWED_ROOTS, which is what decides the boundary above. Since 1.2.1 those locations have to be named:

# A file, or the directory holding one. Consulted before the working directory.
CGMB_ENV_PATH=/home/me/.cgmb/.env

Upgrading from 1.2.0 or earlier: if your key lived in one of those locations, set this to keep using it — otherwise CGMB will report the key as missing.

.env.example carries the full list, including the keys that are parsed but that nothing reads back — worth checking before assuming a setting has an effect.

MCP Integration

CGMB automatically configures Claude Code MCP integration:

• 📍 Config path: ~/.claude-code/mcp_servers.json
• ⚡ Direct Node.js execution
• 🔒 Safe merge without overwriting existing servers

🪟 Windows Environment

CGMB has fully supported Windows since v1.1.0:

| Feature | Status | |---------|:------:| | CLI | ✅ All commands work | | MCP Integration | ✅ MCP tool calls work correctly | | Path Resolution | ✅ Automatically handles C:\path\to\file format | | Antigravity CLI | ✅ Full compatibility with Windows version |

# Absolute paths recommended
cgmb analyze "C:\Users\name\Documents\report.pdf"

# Set environment variable (PowerShell)
$env:AI_STUDIO_API_KEY = "your_api_key_here"

# Set environment variable (Command Prompt)
set AI_STUDIO_API_KEY=your_api_key_here

🐧 Linux / WSL Environment

CGMB works fully on Linux and WSL:

| Feature | Status | |---------|:------:| | CLI | ✅ All commands work | | MCP Integration | ✅ MCP tool calls work correctly | | Path Resolution | ✅ Supports /mnt/ WSL paths and Unix paths | | Antigravity CLI | ✅ Full compatibility with Linux version |

# Use Unix path format
cgmb analyze /home/user/documents/report.pdf

# WSL environment example
cgmb analyze /mnt/c/Users/name/Documents/report.pdf

# Set environment variables
export AI_STUDIO_API_KEY="your_api_key_here"
export ANTIGRAVITY_MODEL="gemini-3.6-flash-low"

Running the tests under WSL

The suite is platform-aware and runs the same cases on both sides: the Windows-only cases (.cmd shim handling) have POSIX counterparts, and the POSIX-only ones (signal escalation, /mnt/c/Users discovery) are skipped on Windows.

cd /mnt/<drive>/path/to/claude-gemini-multimodal-bridge
node --version        # must satisfy engines.node (>= 22)
npm run build         # or reuse a build made on the host
node --test "tests/**/*.test.mjs"

🔍 Troubleshooting

Debug Mode

export CGMB_DEBUG=true
export LOG_LEVEL=debug
cgmb serve --debug

OCR and PDF Processing Issues

If OCR results are inaccurate:

• Use high-resolution scanned PDFs (300+ DPI)
• Ensure clear, high-contrast text
• Avoid skewed or rotated documents

If large documents timeout:

• Split large PDFs before processing (limit: 50MB, 1,000 pages)
• The AI Studio layer's 300s budget is fixed; there is no environment variable that extends it, so splitting the document is the remedy

💰 API Costs

CGMB uses pay-per-use APIs:

• 📊 Google AI Studio API Pricing Details

📁 Project Structure

src/
├── core/           # 🎯 Main MCP server and layer management
├── layers/         # 🔌 AI layer implementations
├── auth/           # 🔐 Authentication system
├── tools/          # 🛠️ Processing tools
├── utils/          # 🔧 Utilities and helpers
└── mcp-servers/    # 🌐 Custom MCP servers

🔗 Links

📦 Project

• GitHub
• NPM
• Issues

🔧 Related Tools

• Claude Code
• Antigravity CLI
• Google AI Studio
• MCP

📜 Terms of Service

• Google AI Studio
• Claude
• Gemini API

📜 Version History

v1.2.2 (2026-08-03)

Housekeeping. Nothing a user can reach behaves differently: everything removed here could not be reached at all.

• 🧹 Four dead call paths removed: the layer named nine MCP tools and the server implements eight, of which five overlapped. analyze_audio_advanced, convert_file, convert_pdf and transcribe_audio have never existed on the server, so any call to them returned MCP error -32601. Nothing could reach them — task.type is never set to 'convert' or 'audio_analysis_advanced' anywhere, taskType is not in any MCP tool's schema, and two of the methods had no callers at all. That is exactly the state generate_text was in until generate-audio --script gave it an entrance and made it a defect users hit, which is why these are removed rather than left waiting for one
• 🔒 The layer and its server are now checked against each other: a test starts the MCP server, asks it for tools/list, and fails if the layer can name a tool that is not on it. It named all four of the above before this release
• 🗑️ 740 lines of unused modules removed: PromptOptimizer and quotaMonitor had no reference outside themselves and no export from the package entry point, and were being built into dist and published
• The analyze_audio_advanced path listed as known-unfixed in 1.2.1 is resolved by the first item

AudioAnalysisResult remains exported from core/types.js. The method that returned it is gone, but the type is part of the published surface and a patch release is the wrong place to drop it.

v1.2.1 (2026-08-02)

A fix-only release. Every change addresses a defect measured in 1.2.0; no features were added, and it touches 18 files of code and tests.

• 🎯 Concurrent AI Studio requests no longer take each other's answers: the shared MCP server got one stdout listener per call, each settling on the first reply it saw, and request ids were Date.now() — two calls in the same millisecond shared one. Answers are now routed by id, ids are monotonic, and a process replaced on its TTL cannot fail or disown its successor
• 🚪 cgmb exits after using AI Studio: nothing ever ended the shared MCP server, and its pipes kept the parent alive. It is now ended on shutdown, and spawned without a shell so that ending it ends the server rather than a wrapper
• 🔑 .env is read from your project, not from wherever CGMB is installed: the installation directory, the global npm directory and ~/.cgmb were all read by default, which meant another project's AI_STUDIO_API_KEY and — more seriously — its CGMB_ALLOWED_ROOTS, which decides what may be sent to Google. Those locations are now opt-in through CGMB_ENV_PATH, which accepts a file or a directory and takes precedence over the defaults
• 🔍 The search cache answers the question that was asked: keys folded every year from 2024–2029 together and collapsed 最新/最近/新しい, and omitted the model, so a question about 2026 could be answered from a 2024 reply, or one model's answer returned for another's question
• 🧩 Workflow steps receive their inputs: parallel steps published nothing, so downstream steps ran without the output they referenced and still reported success; hybrid runs ignored dependsOn ordering
• ⏱️ Timeouts reflect the work: the general Claude path used a fixed floor below the layer default and estimated from the wrong text
• 🔊 A discontinued model id is gone: gemini-2.0-flash was hardcoded in the audio path
• 🧪 CI runs the whole suite: the postinstall script called process.exit(0) under CI at module scope, ending whichever process imported it — five test cases vanished on GitHub Actions while the run stayed green

Removed: generate-audio --script. It offered a two-step "write a script, then read it aloud" flow whose first step requested an MCP tool named generate_text that the AI Studio server has never implemented, so it returned MCP error -32601 on every call in this and every earlier version. It appeared in --help only — never in this README or in docs/. Plain generate-audio is unaffected. Building the two-step flow properly is left to a release that can verify it.

Known, unfixed: the audio_analysis_advanced task type calls an analyze_audio_advanced tool the server does not implement. It is unreachable from the CLI and from every MCP tool, so nothing can currently invoke it.

v1.2.0 (2026-07-28)

• 🔄 Antigravity CLI Migration: Google discontinued Gemini CLI for individual accounts on 2026-06-18. The web-search layer now calls agy (Antigravity CLI, 1.1.7+), authenticated through the OS keyring rather than an API key. Layer names accept antigravity; gemini still works as an alias
• 🚀 Updated AI Studio Models: gemini-3-pro-image for high-quality image generation, gemini-3.1-flash-tts-preview for speech. The retired gemini-2.0-flash-exp is gone from all six call sites it was hardcoded at
• 🖥️ Three-OS Support: Linux, Windows and macOS verified in CI on every push
• 🎯 targetLayer Is Honoured: naming a layer now routes there. claude is selectable, and requests that named a layer are no longer silently re-routed
• 🔧 CLAUDE_CODE_PATH Works: the variable and claude.code_path now reach the executable search, so installs outside the default locations are usable
• 🧹 Dead Code Removed: 3,619 lines of unreachable workflow classes deleted; no change to the published API surface

v1.1.0 (2026-01-10)

• 🪟 Full Windows Support: Native Windows support for both CLI and MCP
• 📝 Enhanced OCR: Automatic OCR processing for image-based PDFs
• 🚀 Latest Gemini Models: Support for gemini-2.5-flash
• ⚡ Improved MCP Integration: Optimized async layer initialization
• 📈 Performance Improvements: Reduced timeouts, lazy loading, enhanced caching
• 🛡️ Error Recovery: 95% self-healing rate with exponential backoff

v1.0.4

• 🎉 Initial release
• 🏗️ 3-layer architecture implementation
• 🎨 Basic multimodal processing

📄 License

MIT - See LICENSE

Made with ❤️ by goodaymmm

⭐ If this project helped you, please give it a star!