Llama Bridge

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:

1. Open the project-scoped .agents/AGENTS.md file.
2. Copy its entire content.
3. 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.

1. Cloud model receives a user request
2. Cloud model breaks it into implementation tasks
3. Cloud model calls MCP tools to delegate coding
4. Local model generates implementation
5. Cloud model reviews the code
6. If issues found → calls fix_code with feedback
7. Repeat until code meets quality standards
8. 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.