# 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](https://docs.astral.sh/uv/)** (recommended) or pip
- A running **llama.cpp server** (see below)

### 2. Start your local llama.cpp server

```bash
# 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):

```bash
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://./.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:

```bash
# 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`:

```json
{
  "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

```bash
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.