LLAMA Hot Swap

Servidor MCP para intercambio en caliente de modelos llama.cpp en Claude Code - launchctl (macOS) + systemd (Linux)

Documentación

mcp-llama-swap

Intercambia modelos de llama.cpp en caliente dentro de una sesión activa de Claude Code. Sin pérdida de contexto. Un solo comando.

Planifica con un modelo de razonamiento. Implementa con un modelo de codificación. Misma sesión, mismo contexto, cero esfuerzo manual.

Soporta macOS (launchctl) y Linux (systemd).

Por qué

Ejecutar LLMs locales significa elegir entre un modelo de razonamiento potente y un modelo de codificación rápido. No puedes cargar ambos en una sola máquina. Intercambiar modelos manualmente destruye el contexto de tu conversación y el flujo de trabajo.

mcp-llama-swap resuelve esto dándole a Claude Code una herramienta para intercambiar el modelo detrás de llama-server a través del gestor de servicios de tu sistema (launchctl en macOS, systemd en Linux), preservando el historial completo de la conversación en el lado del cliente.

Inicio Rápido

Instalación

# Option A: Run directly with uvx (no install needed)
uvx mcp-llama-swap

# Option B: Install from PyPI
pip install mcp-llama-swap

Configurar Claude Code

Añade a ~/.claude.json:

{
  "mcpServers": {
    "llama-swap": {
      "command": "uvx",
      "args": ["mcp-llama-swap"],
      "env": {
        "LLAMA_SWAP_CONFIG": "/path/to/config.json"
      }
    }
  }
}

Configurar Modelos

Crea config.json (macOS):

{
  "plists_dir": "~/.llama-plists",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "qwen35-thinking.plist",
    "coder": "qwen3-coder.plist",
    "fast": "glm-flash.plist"
  }
}

O en Linux:

{
  "services_dir": "~/.llama-services",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "llama-server-planner.service",
    "coder": "llama-server-coder.service"
  }
}

Uso

Dentro de Claude Code:

You: list models
You: swap to planner
You: <discuss architecture, define interfaces>
You: swap to coder and implement the plan

Eso es todo. El contexto se preserva entre intercambios.

También puedes generar nuevas configuraciones de modelos directamente:

You: create a model config named "reasoning" for /models/qwen3-30b.gguf with 8192 context

Cómo Funciona

Claude Code CLI
    |
    | Anthropic Messages API
    v
LiteLLM Proxy (:4000)         <-- translates Anthropic -> OpenAI format
    |
    | OpenAI Chat Completions API
    v
llama-server (:8000)          <-- model weights swapped via service manager
    ^
    |
mcp-llama-swap                <-- this project (launchctl or systemd)

Claude Code habla en formato Anthropic. LiteLLM traduce al formato OpenAI para llama-server. Este servidor MCP gestiona qué servicio de modelo está cargado mediante launchctl (macOS) o systemd (Linux).

El contexto de la conversación sobrevive a los intercambios porque Claude Code mantiene el historial completo de mensajes en el lado del cliente y lo reenvía con cada solicitud.

Configuración de Modelos

Modo Mapeado (recomendado)

Define alias para tus modelos. Solo los modelos mapeados están disponibles. Otras configuraciones de servicio en el directorio se ignoran.

macOS:

{
  "plists_dir": "~/.llama-plists",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "qwen35-35b-a3b-thinking.plist",
    "coder": "qwen3-coder.plist",
    "fast": "glm-4-7-flash.plist"
  }
}

Linux:

{
  "services_dir": "~/.llama-services",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "llama-server-planner.service",
    "coder": "llama-server-coder.service"
  }
}

Intercambia usando tus alias: "cambia a coder", "cambia a planner".

Modo Directorio

Establece "models": {} para descubrir automáticamente todas las configuraciones de servicio. Los nombres de archivo (sin extensión) se convierten en los alias.

macOS:

{
  "plists_dir": "~/.llama-plists",
  "models": {}
}

Linux:

{
  "services_dir": "~/.llama-services",
  "models": {}
}

Herramientas MCP

Herramienta	Descripción
`list_models`	Lista todos los modelos configurados con estado de carga y modo actual
`get_current_model`	Devuelve el alias del modelo actualmente cargado
`swap_model`	Descarga el modelo actual, carga el especificado y espera la verificación de salud
`create_model_config`	Genera un nuevo plist de launchd (macOS) o unidad de systemd (Linux) para un modelo

Recursos MCP

Recurso	Descripción
`llama-swap://config`	Configuración actual como JSON
`llama-swap://status`	Estado actual del modelo, salud e información de la plataforma

Prompts MCP

Prompt	Descripción
`swap-workflow`	Plantilla guiada de flujo de trabajo planificar-luego-implementar

Guía de Configuración Completa

Requisitos Previos

macOS con launchctl, o Linux con systemd
llama-server (llama.cpp) instalado
Configuraciones de modelos como archivos de servicio (plists de launchd o unidades de systemd)
Python 3.10+
CLI de Claude Code apuntando a un proxy LiteLLM

1. Instalar mcp-llama-swap

pip install mcp-llama-swap

2. Instalar e iniciar el proxy LiteLLM

pip install litellm

Crea litellm_config.yaml:

model_list:
  - model_name: "*"
    litellm_params:
      model: "openai/*"
      api_base: "http://localhost:8000/v1"
      api_key: "sk-none"

litellm_settings:
  drop_params: true
  request_timeout: 300

Inícialo:

litellm --config litellm_config.yaml --port 4000

En macOS, puedes usar el ai.litellm.proxy.plist.template incluido para ejecutarlo como un servicio persistente de launchd (consulta setup.sh).

3. Apuntar Claude Code a LiteLLM

Añade a ~/.zshrc (macOS) o ~/.bashrc (Linux):

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-none"
export ANTHROPIC_MODEL="local"

4. Añadir el servidor MCP a Claude Code

Añade a ~/.claude.json:

{
  "mcpServers": {
    "llama-swap": {
      "command": "uvx",
      "args": ["mcp-llama-swap"],
      "env": {
        "LLAMA_SWAP_CONFIG": "/absolute/path/to/config.json"
      }
    }
  }
}

5. Crear tu config.json

Copia config.example.json (macOS) o config.example.linux.json (Linux) y edítalo con tus alias de modelos y nombres de archivos de servicio.

6. Crear configuraciones de servicios de modelos

Puedes crear configuraciones de servicios manualmente, o usar la herramienta MCP create_model_config dentro de Claude Code:

You: create a model config named "coder" for /path/to/model.gguf with 8192 context

Esto genera el plist de launchd (macOS) o el archivo de unidad de systemd (Linux) apropiado en tu directorio de servicios.

Configuración Automatizada (macOS)

Si prefieres una configuración de una sola vez en macOS, clona este repositorio y ejecuta:

git clone https://github.com/oussama-kh/mcp-llama-swap.git ~/mcp-llama-swap
cd ~/mcp-llama-swap
chmod +x setup.sh
./setup.sh

El script crea un entorno virtual, instala dependencias, configura el servicio launchd de LiteLLM e imprime la configuración exacta a añadir.

Referencia de Configuración

Campos de config.json:

Campo	Predeterminado	Descripción
`services_dir`	`~/.llama-plists` (macOS) / `~/.llama-services` (Linux)	Directorio que contiene las configuraciones de servicios de modelos
`plists_dir`	—	Alias de macOS para `services_dir` (compatible con versiones anteriores)
`units_dir`	—	Alias de Linux para `services_dir`
`health_url`	`http://localhost:8000/health`	Endpoint de salud de llama-server
`health_timeout`	`30`	Segundos de espera para la verificación de salud después de cargar
`models`	`{}`	Mapa de alias a nombres de archivo. Vacío = modo directorio
`platform`	`auto`	Gestor de servicios: `auto`, `launchctl` o `systemd`
`launchctl_mode`	`legacy`	Solo macOS: `legacy` (cargar/descargar) o `modern` (bootstrap/bootout)

Anula la ruta de configuración mediante la variable de entorno LLAMA_SWAP_CONFIG.

Detalles de la Plataforma

macOS (launchctl)

Los modelos se gestionan como servicios de launchd mediante archivos plist. Hay dos modos de launchctl disponibles:

Legado (predeterminado): Usa launchctl load/unload/list. Funciona en todas las versiones de macOS.
Moderno: Usa launchctl bootstrap/bootout/print. La API oficialmente soportada en macOS más reciente. Habilítalo con "launchctl_mode": "modern" en la configuración.

Linux (systemd)

Los modelos se gestionan como servicios de usuario de systemd. Los archivos de unidad en services_dir se enlazan simbólicamente a ~/.config/systemd/user/ y se gestionan mediante systemctl --user start/stop.

Solución de Problemas

LiteLLM no traduce correctamente: Verifica /tmp/litellm.stderr.log. Confirma que llama-server está ejecutándose: curl http://localhost:8000/health.

El intercambio de modelos agota el tiempo de espera: Aumenta health_timeout en config.json. Los modelos grandes pueden necesitar más de 30 segundos para cargar los pesos en memoria.

Claude Code no puede encontrar el servidor MCP: Verifica que la ruta LLAMA_SWAP_CONFIG sea absoluta. Prueba directamente: python -m mcp_llama_swap.

Modelo mapeado no encontrado: El nombre de archivo del servicio en models debe coincidir con un archivo real en tu directorio de servicios.

El servicio de systemd no se inicia: Revisa journalctl --user -u llama-server-<name> para ver errores. Asegúrate de que llama-server esté en tu PATH.

Problemas con el modo moderno de launchctl: Si los comandos bootstrap/bootout fallan, vuelve a "launchctl_mode": "legacy" en la configuración.

Desarrollo

# Install with test dependencies
pip install -e ".[test]"

# Run tests
pytest -v

Caso de Uso

Este proyecto permite un flujo de trabajo de codificación de IA en dos fases completamente en hardware local:

Fase de planificación: Carga un modelo de razonamiento (por ejemplo, Qwen3.5-35B-A3B con pensamiento). Discute la arquitectura, define interfaces, descompón requisitos.
Fase de implementación: Cambia a un modelo de codificación (por ejemplo, Qwen3-Coder-30B). Ejecuta el plan archivo por archivo con el contexto completo de la conversación de la fase de planificación.

Sin APIs en la nube. Sin datos que salgan de tu máquina. Sin pérdida de contexto entre fases.

Licencia

Apache-2.0