local-delegate

Delega tareas mecánicas texto→texto a un LLM local para conservar la cuota de tu suscripción de Claude. Un servidor MCP (stdio o daemon HTTP compartido) que es cliente genérico de cualquier endpoint OpenAI-compatible — llama-swap, Ollama, LM Studio, vLLM.

Demo

Dashboard embebido (datos de ejemplo): estado del backend local (modelos montados, delegación en curso con su progreso por trozos, tools MCP), RAM/VRAM del sistema con consumo por proceso, tokens de contexto conservados, ahorro por herramienta y modelo, dónde corrió el cómputo —esta máquina o un backend remoto— y actividad reciente paginada en tu hora local. Se sirve en http://127.0.0.1:9393.

¿Por qué?

Cuando Claude tiene que resumir un log enorme, clasificar, extraer campos o generar boilerplate, gasta cuota de tu suscripción en trabajo mecánico. local-delegate expone esas tareas como tools MCP que corren en un LLM local: pasas path en vez de text y el archivo se lee del lado del servidor, así el contenido grande nunca entra al contexto de Claude. Solo vuelve el resultado corto — cuota que no gastaste.

Instalación rápida

Con uv no hay nada que instalar: uvx baja y ejecuta el paquete aislado.

Añádelo a tu config de MCP (Claude Desktop / Claude Code) en modo compatible stdio:

{
  "mcpServers": {
    "local-delegate": {
      "command": "uvx",
      "args": ["local-delegate-mcp"]
    }
  }
}

Ver plantillas completas en examples/.

O deja que el paquete lo configure todo por ti —entrada MCP, hooks, skill y la regla de delegación en tu CLAUDE.md/AGENTS.md global— con un solo comando:

uvx local-delegate-mcp install --dry-run   # muestra exactamente qué tocaría
uvx local-delegate-mcp install             # aplica

Es idempotente, deja .bak de lo que edita, no toca configuración ajena y se revierte con local-delegate uninstall. Detalle y opciones en Instalación de la integración.

Si usas varias sesiones o varios clientes en la misma máquina, se recomienda un solo daemon:

uvx local-delegate-mcp serve

El daemon sirve MCP en http://127.0.0.1:9393/mcp y el dashboard en http://127.0.0.1:9393/. Codex, Claude Code y cualquier cliente compatible con Streamable HTTP pueden compartir esa URL sin levantar procesos MCP duplicados. Guía completa: Daemon compartido.

Para usar la GPU de otra máquina manteniendo los paths locales del cliente, usa un MCP local que apunte al backend remoto. La versión estable recomendada para el rollout es uvx --from local-delegate-mcp==0.11.0 local-delegate-mcp: guía Mac → PC y recipe técnica completa.

En Windows, si lo registras como tarea al iniciar sesión, ejecuta el pythonw.exe del entorno donde instalaste el paquete con -m local_delegate serve --log-level warning. pythonw no crea consola ni botón en la barra de tareas. La tarea pertenece al usuario de Windows, no a Codex ni a Claude: cualquier cliente local comparte el mismo daemon. El dashboard identifica ese único proceso con la insignia DAEMON MCP; las sesiones conectadas son clientes HTTP, no procesos MCP adicionales.

Requisitos

Un endpoint OpenAI-compatible ya corriendo, accesible en LOCAL_DELEGATE_BASE_URL (default http://127.0.0.1:9292/v1). Cualquiera sirve:

• llama-swap — ver recipe con GPU Blackwell.
• Ollama — http://127.0.0.1:11434/v1.
• LM Studio, vLLM, o cualquier servidor que hable la API de OpenAI.

El paquete no arranca ningún backend por defecto (LOCAL_DELEGATE_AUTOSTART=0). El auto-arranque de llama-swap es opt-in (ver tabla de configuración).

¿Qué versiones de llama-server/llama-swap usar y cómo disponer el workspace? Ver Versiones del backend y workspace de referencia (sugerencia probada, no requisito). local-delegate doctor compara tu instalación contra esas versiones.

Tools

Pasar path (en vez de text) hace que el MCP lea el archivo server-side → ahorro real de cuota.

Los modelos locales no usan tool-calling: el server arma el prompt + guardrails, hace POST al endpoint y devuelve solo texto.

Documentos largos. local_translate (y local_delegate con entradas largas) parten el texto por límites naturales —headers Markdown, párrafos, líneas— y procesan un trozo por llamada respetando el techo de max_tokens, concatenando las salidas en orden y conservando el formato en las costuras. Un documento de 20 000+ caracteres vuelve completo en vez de cortado a mitad. El log registra chunks: N y el dashboard muestra el progreso (trozo 3/7) mientras corre.

Resúmenes de documentos enormes. local_summarize y local_lint_summary hacen map-reduce cuando la entrada no cabe en el modelo: resumen cada parte y luego resumen los resúmenes, por niveles si hace falta. Antes truncaban —de un log de CI enorme se resumía el principio y el resto se descartaba en silencio, que es justo donde suelen estar los errores— y ahora se lee entero. local_extract sigue truncando a propósito: fusionar el JSON de varios trozos no tiene una respuesta única y adivinarla sería peor que avisar.

local_summarize y local_lint_summary tampoco truncan ya: cuando el documento no cabe en el modelo lo resumen por partes y luego resumen los resúmenes (map-reduce, jerárquico si hace falta). Importa sobre todo en logs de CI, donde los errores interesantes suelen estar al final —que era justo lo que se descartaba al cortar por el techo del modelo.

Configuración

Todo por variables de entorno; nada hardcodeado. Los ids de modelo default son solo eso — cámbialos por los de tu backend.

La métrica de ahorro

El MCP registra cada llamada en un log rotado por mes y sirve un dashboard en http://127.0.0.1:9393, con selector de rango y visibilidad de delegaciones en curso. El ahorro de contexto = caracteres de entrada leídos server-side (llamadas con source=path) ÷ 4 (o los tokens reales del backend, cuando los da) ≈ tokens que nunca entraron al contexto de Claude. Detalle en la wiki.

Los rangos, los días del gráfico y las horas de la tabla usan tu zona horaria (el log se escribe en UTC, que es un instante sin ambigüedad; la conversión es de presentación). El dashboard también separa dónde corrió el cómputo: local si el backend escucha en loopback, remote si la inferencia se fue a otra máquina —por ejemplo esta Mac usando la GPU de la PC—. Los eventos anteriores a la v0.11.0 no traen el campo y aparecen como n/d.

Alcance / no-objetivos

local-delegate es deliberadamente texto/imagen→texto: arma el prompt (o el payload multimodal), hace POST a /chat/completions y devuelve solo texto. Cosas que no hace a propósito:

• Tool-calling local. Los modelos locales no invocan herramientas ni ejecutan código; eso lo sigue haciendo Claude. Añadirlo convertiría este paquete en un orquestador paralelo, que no es el objetivo.
• Generación o edición de imágenes. local_describe_image es solo imagen→texto (describir, leer texto visible, responder una pregunta puntual); nada de generar ni editar imágenes.
• Audio. Para transcripción usa el companion whisper-transcribe-mcp en vez de intentar meter audio aquí.
• Sustituir la suscripción. El objetivo es conservar cuota delegando pasos mecánicos acotados, no enrutar todo el trabajo a modelos locales.

Integración con el cliente: hooks, skill y memoria

local-delegate install deja lista la integración completa en tu HOME:

Cada pieza se puede excluir (--no-hooks, --no-skill, --no-memory, --no-mcp) y elegir cliente con --target claude|codex. Los hooks recomendados tras el piloto A/B son UserPromptSubmit (intenciones mecánicas) y PreToolUse/Bash (salidas largas de lint/tests); el experimento PreToolUse/Read queda apagado salvo --enable-read-hook. Ver Instalación de la integración y docs/recipes/claude-code-hooks.md.

Groups de llama-swap (opcional)

Con pip install "local-delegate-mcp[llamaswap]" quedan disponibles dos CLIs para gestionar groups de llama-swap (un modelo residente siempre cargado + un pool que se turna) con guardrail de VRAM y RAM de sistema incorporado (--ram-gb es opcional: llama-server mapea el GGUF también en RAM aunque el cómputo sea 100% GPU, así que un catálogo que cabe en VRAM puede igual agotar la RAM en máquinas con menos de 32 GB):

local-delegate check-llamaswap --config config.yaml --vram-gb 16 --ram-gb 32
local-delegate init-llamaswap --config config.yaml --resident gemma3-4b --swap llama31-8b,qwen25-coder-14b --vram-gb 16 --ram-gb 32

El paquete nunca toca tu config.yaml por su cuenta — estos comandos solo corren si vos los invocás. init-llamaswap corre el/los guardrail(es) antes de escribir (no escribe nada si no cabe en VRAM o, si pasaste --ram-gb, en RAM) y nunca sobreescribe sin --force (dejando .bak). Detalle completo, semántica de groups verificada contra el código de llama-swap, y ritual de aplicación en docs/recipes/llama-swap-groups.md.

Enlaces

• Wiki · Recipes
• CONTRIBUTING · CODE OF CONDUCT · CHANGELOG
• Licencia MIT