Llama-Bridge — Local LLM Delegation Server

An MCP server that lets your cloud model (Gemini / Claude) delegate implementation work to a local llama.cpp server, preserving precious cloud-model usage limits while maintaining high code quality through AI-powered code review.

Cloud Model → Plans & Reviews
     ↕ MCP
Local Model → Writes Code

Quick Start

1. Prerequisites

Python 3.11+
uv (recommended) or pip
A running llama.cpp server (see below)

2. Start your local llama.cpp server

# Example with llama-server
./llama-server -m your-model.gguf --port 8080

# Or with llama-cpp-python
pip install llama-cpp-python[server]
python -m llama_cpp.server --model your-model.gguf --port 8080

3. Run the Automated Installer

We provide an automated installer script that creates a virtual environment, installs the package and its dependencies, and automatically configures llama-bridge in your global Antigravity/Gemini configuration directory (~/.gemini/config/mcp_config.json on Linux/macOS):

python install.py

4. Configure Global Model Instructions (Required)

To enable the cloud model to automatically use the local Llama-Bridge delegation tools across all workspaces:

Open the project-scoped .agents/AGENTS.md file.
Copy its entire content.
Paste the content into your global GEMINI.md instructions file located at ~/.gemini/GEMINI.md.

5. Custom Configuration (Optional)

The installer will set the default local server URL to http://localhost:8080. If you need to customize this, or set a custom API key, you can add environment variables to the "env" block in your global mcp_config.json or create a .env file in the project directory:

# Example .env settings:
LLAMA_BASE_URL=http://localhost:8080
LLAMA_REQUEST_TIMEOUT=120

6. Verify

Restart Antigravity IDE. The cloud model should now have access to:

implement_code
generate_tests
refactor_code
fix_code
generate_docs
check_local_model_health

Available Tools

Tool	Purpose	Inputs
implement_code	Generate implementation from a spec	task_description, language, context, constraints
generate_tests	Generate test code	code, language, framework, requirements
refactor_code	Apply a specific refactor	code, language, refactor_description, constraints
fix_code	Fix bugs from errors/feedback	code, language, errors, review_comments
generate_docs	Generate documentation	code, language, style
check_local_model_health	Check server availability	(none)

Every code tool returns a consistent ToolResponse:

{
  "success": true,
  "code": "def hello(): ...",
  "error": null,
  "metadata": {
    "tool": "implement_code",
    "elapsed_seconds": 3.42,
    "usage": {"prompt_tokens": 150, "completion_tokens": 89},
    "warnings": []
  }
}

Configuration

All settings are configured via environment variables or a .env file:

Variable	Default	Description
`LLAMA_BASE_URL`	`http://localhost:8080`	llama.cpp server URL
`LLAMA_REQUEST_TIMEOUT`	`120`	Timeout in seconds
`LLAMA_DEFAULT_TEMPERATURE`	`None` (Uses server default)	Default sampling temperature
`LLAMA_DEFAULT_MAX_TOKENS`	`131072`	Default token budget
`LLAMA_MODEL_NAME`	`local-model`	Model identifier (usually ignored)

Running Tests

uv run pytest tests/ -v

How It Works

The cloud model (Gemini/Claude in Antigravity IDE) acts as a senior engineer — it plans, delegates, and reviews. The local model acts as a fast junior engineer — it writes code quickly. The MCP server is the bridge between them.

Cloud model receives a user request
Cloud model breaks it into implementation tasks
Cloud model calls MCP tools to delegate coding
Local model generates implementation
Cloud model reviews the code
If issues found → calls fix_code with feedback
Repeat until code meets quality standards
Cloud model presents the final, reviewed code

This gives you practically unlimited coding capacity from the local model, with cloud-grade quality assurance from the review loop.

Llama-Bridge