# ๐ Claude-Gemini Multimodal Bridge
### *Unifying the Power of AI.*
**An MCP bridge that seamlessly integrates Claude Code, Antigravity CLI, and Google AI Studio**
[๐ฏ๐ต ๆฅๆฌ่ช็](README_JP.md) โข [๐ฆ NPM](https://www.npmjs.com/package/claude-gemini-multimodal-bridge) โข [๐ Issues](https://github.com/goodaymmm/claude-gemini-multimodal-bridge/issues)
---
[](https://www.npmjs.com/package/claude-gemini-multimodal-bridge)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](https://ai.google.dev/)
[](https://www.anthropic.com/)
[](https://github.com/sponsors/goodaymmm)
[](#-windows-environment)
[](#-quick-start)
[](#-quick-start)
---
## ๐ค 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
```mermaid
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
```bash
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:
```bash
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:
```bash
# 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:
```bash
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**:
```bash
# ๐จ 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
```bash
# 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:
```bash
# ";" 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:
```bash
# 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 |
```powershell
# 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 |
```bash
# 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.
```bash
cd /mnt//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
```bash
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](https://ai.google.dev/pricing)
---
## ๐ 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](https://github.com/goodaymmm/claude-gemini-multimodal-bridge)
- [NPM](https://www.npmjs.com/package/claude-gemini-multimodal-bridge)
- [Issues](https://github.com/goodaymmm/claude-gemini-multimodal-bridge/issues)
|
### ๐ง Related Tools
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
- [Antigravity CLI](https://antigravity.google/docs/cli)
- [Google AI Studio](https://aistudio.google.com/)
- [MCP](https://modelcontextprotocol.io/)
|
### ๐ Terms of Service
- [Google AI Studio](https://ai.google.dev/gemini-api/terms)
- [Claude](https://www.anthropic.com/terms)
- [Gemini API](https://ai.google.dev/gemini-api/docs/safety-guidance)
|
---
## ๐ 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](LICENSE)
---
**Made with โค๏ธ by [goodaymmm](https://github.com/goodaymmm)**
*โญ If this project helped you, please give it a star!*
[](https://github.com/sponsors/goodaymmm)