The io.github.ZahiriNatZuke/local-delegate MCP server delegates mechanical text-to-text tasks to a local OpenAI-compatible LLM to conserve Claude subscription quota. It acts as a generic client for any OpenAI-compatible endpoint, supporting shared local setups.
🛠️ Key Features
Delegates text→text mechanical tasks to a local LLM
Uses a generic OpenAI-compatible client
Works with OpenAI-compatible endpoints (e.g., llama-swap, Ollama, LM Studio, vLLM)
🚀 Use Cases
Reduce Claude quota usage for routine text transformations
Route mechanical writing or conversion tasks to a local model
⚡ Developer Benefits
MCP server can run via stdio or a shared daemon HTTP setup
Compatible with multiple OpenAI-compatible local inference backends
⚠️ Limitations
Requires a local OpenAI-compatible endpoint; scope is centered on text→text delegation
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.
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: el documento no ocupa tu ventana de contexto ni lo procesa Claude.
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:
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:
bash
uv tool install local-delegate-mcp # deja `local-delegate` en el PATH
local-delegate install --dry-run # muestra exactamente qué tocaría
local-delegate install # aplica
También sirve uvx local-delegate-mcp install para probarlo sin instalar nada, pero ten en cuenta
que uvx no deja el comando disponible: monta un entorno efímero y lo borra al terminar, así
que después local-delegate doctor responderá «command not found». El propio install te lo avisa
si detecta ese caso.
Es idempotente, deja .bak de lo que edita (la primera vez que lo toca; después no lo pisa), no
toca configuración ajena y se revierte con local-delegate uninstall. Desde la 0.44.0 escribe de
forma atómica, reaplica su cambio si Claude Code guarda el fichero a la vez, y si un fichero no está
en UTF-8 (cp1252, UTF-16) la acción falla sin tocarlo. Detalle y opciones en Instalación de la integración.
¿Autocompletado con Tab de subcomandos, opciones y valores? local-delegate install --shell-completion lo deja cargado en el perfil de PowerShell, zsh o bash (opt-in, reversible con
uninstall --shell-completion), y local-delegate completion powershell|zsh|bash imprime el script
por si prefieres cargarlo tú. Ver Autocompletado del shell.
Si usas varias sesiones o varios clientes en la misma máquina, se recomienda un solo daemon:
powershell
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, opencode y cualquier cliente compatible con Streamable HTTP
pueden compartir esa URL sin levantar procesos MCP duplicados. Con un llama-swap local, el extra
[llamaswap] y LLAMASWAP_CONFIG apuntando a su config.yaml, el daemon además reparte el backend por turno:
dos delegaciones cuyos modelos se desalojarían entre sí no se pisan, y la segunda espera (el panel
lo enseña como espera local). Guía completa: Daemon compartido.
Una delegación puede sumar espera de turno e inferencia, y algunos clientes cortan antes: Codex
corta toda llamada a una tool MCP a los 60 s (tool_timeout_sec en [mcp_servers.local-delegate]
de config.toml lo sube, y hay que reponerlo tras cada install/update, que reescriben ese
bloque) y Claude Code corta una llamada HTTP tras 5 min sin respuesta (la variable
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT, en ms, lo sube y sobrevive a install). Detalle en
Instalación de la integración.
Para usar la GPU de otra máquina manteniendo los paths locales del cliente, usa un MCP local que
apunte al backend remoto: guía Mac → PC y
recipe técnica completa. Las operaciones de las dos máquinas
hacen una sola cola: la que no tiene el backend pide turno al daemon de la otra, con la misma clave
del backend y solo hacia un host privado (la tailnet), y si ese daemon no está disponible sigue sin
turno, como antes (turno común PC+Mac).
No fijes una versión vieja «por estabilidad». Un pin (==X.Y.Z) congela también los rangos de
dependencias que declaraba aquel wheel, y eso envejece mal: las versiones anteriores a la 0.12.2
pedían mcpsin techo, así que hoy resuelven al SDK 2.x y mueren en el import. Si necesitas
fijar, fija la actual, y súbela cuando salga una nueva.
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.
Al actualizar en Windows, para el daemon antes de uv tool install --force. Con el daemon
corriendo, la reinstalación puede fallar a mitad (tiene abiertos ficheros del entorno) y dejarlo
roto; schtasks /End no basta porque el lanzador está desacoplado, así que para el proceso
pythonw del daemon, instala y vuelve a lanzarlo. Después, local-delegate update repone hooks,
skill y el bloque de CLAUDE.md/AGENTS.md si quedaron desfasados.
Si instalaste con una versión fija (uv tool install "local-delegate-mcp==X.Y.Z"), uv tool upgrade dice «Nothing to upgrade» y no sube nada: reinstala con
uv tool install "local-delegate-mcp[llamaswap]@latest" (con tus extras). Desde la 0.45.1,
local-delegate update y doctor lo detectan y dan ese comando.
La 0.36.0 habla en español o en inglés y sigue al idioma del sistema. Con el sistema en
inglés pasarás a ver inglés: para quedarte en español, LOCAL_DELEGATE_LANG=es local-delegate install (o update). Las claves de _local_delegate y los marcadores de las tools pasan a
inglés (cambio incompatible); la tabla está en el CHANGELOG y en
Idioma.
La 0.35.0 renombra comandos, variables, la skill y ficheros de datos a inglés. Los nombres
viejos funcionaron con aviso desde la 0.35.0 y en la 0.38.0 se retiraron: ya no
tienen efecto. local-delegate doctor nombra los que sigan puestos (hasta la 0.40.x) y
local-delegate update migra los que puede. Volver a una versión anterior no está soportado. La
tabla completa está en el CHANGELOG.
Requisitos
Python 3.11+ — con uvx no tienes que instalarlo tú, lo resuelve él; solo importa si instalas
con pip en un entorno propio.
Y un endpoint OpenAI-compatible ya corriendo, accesible en LOCAL_DELEGATE_BASE_URL
(default http://127.0.0.1:9292/v1). Cualquiera sirve:
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 y, de
paso, comprueba el resto del andamiaje —hooks, skill, memoria, entradas MCP, el daemon, que el
modelo de cada rol esté en la lista del backend y, en Codex, los hooks y el plugin— sin
escribir nada (qué mira cada check).
Tools
Pasar path (en vez de text) hace que el MCP lea el archivo server-side: el contenido no entra
al contexto de Claude, y de ahí sale el ahorro. Un fichero que no es UTF-8 (UTF-16 con BOM,
Windows-1252) se lee sin perder caracteres y la respuesta lo avisa.
Tool
Qué hace
Rol de modelo (default)
local_summarize
Resume texto o archivo; focus opcional para decir qué conservar (p. ej. «cifras de configuración»); avisa si el resumen trae siglas, palabras o cifras que la entrada no tiene
mecánico / largo (auto; una entrada pequeña con tabla va a largo)
local_classify
Devuelve UNA etiqueta de una lista
mecánico
local_extract
Extrae campos → objeto validado con exactamente las claves pedidas (las que falten o vengan como «N/A», null), no una cadena que haya que parsear; con path, números de línea reales para un campo que los pida; una entrada pequeña con tabla (HTML, ARIA, Markdown/GFM, CSV o TSV) va al modelo largo y _local_delegate.role_reason lo dice con su format; si el valor de una clave sale de la fila de otra clave pedida, avisa en cross_filled_keys, y si invierte una negación de la entrada, en polarity_flipped_keys; sobre un diff, los ficheros y sus líneas los calcula el programa (diff_files)
mecánico / largo (auto; también con tabla)
local_boilerplate
Genera código desde una spec y lo escribe en target; devuelve solo un recibo
código
local_delegate
Escape genérico texto→texto
mecánico (o el que pases)
local_lint_summary
Resume logs de lint/tests/CI; con pytest parte de los fallos reales del log y avisa si el resumen no cuadra con ellos
mecánico / largo (auto)
local_commit_msg
Mensaje de commit desde un diff; con path toma el idioma del repo y avisa si no pudo; con un diff enorme acaba a tiempo con lo leído y lo avisa; troceado, avisa y lista las condiciones cambiadas para revisarlo
código
local_translate
Traduce texto o archivo
mecánico / largo (auto)
local_explain_code
Explica código en prosa; con path y pregunta avisa de líneas citadas dudosas y de una premisa que el código no sostiene, aunque la respuesta la sitúe junto a código real
código
local_describe_image
Describe una imagen o responde una pregunta sobre ella (imagen→texto); no mide alineación, tamaños ni saltos de línea, y avisa cuando la pregunta o la respuesta hablan de eso
visión
local_status
Diagnóstico de solo lectura: backend, catálogo, log, VRAM, RAM de sistema
— (no llama al backend de chat)
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. Desde la
0.43.0, «En curso» dice también la fase: «Combinando 3 trozos…» mientras se juntan los parciales y
«Reintentando trozo n/total» cuando un trozo cortado se vuelve a partir; y la actividad separa
trozos de llamadas al backend (3 +1: tres trozos y una combinación). Desde la 0.47.2 ese caso
dice «Dividiendo trozo n/total» y, en cuanto se conocen las partes, cuánto lleva la división
sin mover el total de trozos: «Trozo 3/4 · dividido en 3 · parte 2» en el panel y
3/4 · dividido en 3 · parte 2 en la banda.
Llamadas largas y colas. Desde la 0.45.0 cada llamada viva manda progreso MCP cada 20 s con su
fase («esperando turno, puesto N», «procesando el trozo k/N»), así que Claude Code ya no corta a los
300 s una delegación que espera en la cola. El daemon pone a cada llamada un plazo propio
(LOCAL_DELEGATE_CALL_MAX_S, 1800 s) y, si la cola lleva 900 s sin avanzar, falla en el acto con
«cola saturada» en vez de colgar al cliente. Las delegaciones abortadas quedan en el log como
errores, «En curso» separa «Procesando (n)» de «En cola (m)», y cada entrada del log dice desde qué
máquina vino (host) y cuánto esperó en cada fase (concurrency). Desde la 0.46.0 una
delegación troceada larga cede el turno entre trozos a la que choca con ella
(LOCAL_DELEGATE_TURN_YIELD_S, 120 s), «En curso» agrupa en «Esperando al backend» la llamada que
espera a que llama-swap cambie de modelo, y un read_timeout nombra el modelo que lo bloqueaba.
Desde la 0.47.0 esa espera se ve como tal aunque el trozo se esté dividiendo (antes salía como
«reintentando»; desde la 0.47.2, «dividiendo»).
Ráfagas que mezclan modelos. El turno atiende por orden de llegada, así que una ráfaga que
alterna tools de modelos que no caben juntos (resumir y explicar código, por ejemplo) obliga a
cambiar de modelo en cada relevo, y la última puede esperar minutos sin que el modelo sea lento.
Claude Code pasa a segundo plano la llamada que lleva 2 min y el resultado llega igual. Si la
espera del turno pasa de LOCAL_DELEGATE_TURN_WAIT_NOTICE_S (60 s), la respuesta lleva un
aviso que dice cuánto esperó. Agrupar las llamadas por tool (primero todos los resúmenes, luego
todo el código) lo reduce.
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. Si
algún trozo se corta por max_tokens, el resultado lo avisa y el log registra finish_reason: length. Desde la 0.43.0 un parcial cortado ya no se da por bueno: se descarta, se parte el trozo
(o el grupo del reagrupado) y se reintenta, hasta dos niveles; si aun así queda alguno cortado, el
aviso dice qué trozo y sus líneas. Desde la 0.47.0 el reagrupado no repite rondas sin avanzar: si
una ronda no reduce el material al menos un 20 % y las notas siguen sin caber en el paso final, se
para y devuelve las notas agrupadas con un aviso, marcadas como truncadas (finish_reason: length, truncated_out). Y un diff unificado se resume en prosa, nunca «por secciones».
Desde la 0.36.1, con un log que no cabe en una llamada, local_lint_summary da entrada solo a los
diez ficheros más nombrados (y dice cuántos más hay), y las cifras del resumen final las pone el
programa, no el modelo.
Desde la 0.36.0 también local_commit_msg, local_explain_code (por def/class de primer
nivel, con el inventario de nombres en el paso final) y local_extract (un objeto parcial por
trozo y un paso final con schema que los combina) leen la entrada entera. Desde la 0.44.2, si tras
trocear algún campo de local_extract queda null en todos los trozos, _local_delegate.chunked
lo dice (pieces, null_fields, notice): ese null significa «no visto», no «no existe».
Desde la 0.47.0 local_explain_code con question lleva la pregunta a cada trozo y, con path,
comprueba al final las líneas que cita contra el fichero (avisa de las dudosas) y añade las
apariciones exactas de cada identificador de la pregunta.
Configuración
Todo por variables de entorno; nada hardcodeado. Los ids de modelo default son solo eso —
cámbialos por los de tu backend.
Variable
Default
Descripción
LOCAL_DELEGATE_BASE_URL
http://127.0.0.1:9292/v1
Endpoint OpenAI-compatible
LOCAL_DELEGATE_API_KEY
(vacío)
Bearer token, si tu endpoint lo exige
LOCAL_DELEGATE_BACKEND_ORIGIN
auto
local/remote fuerzan el origen del cómputo; auto lo deduce del host. Ponlo si llegas al backend por un túnel (ssh -L, port-forward): en loopback se vería como local
LOCAL_DELEGATE_TIMEOUT
180
Timeout HTTP (segundos)
LOCAL_DELEGATE_MAX_CONCURRENT_REQUESTS
2
Backpressure máximo por proceso; compartido por todos los clientes del daemon
LOCAL_DELEGATE_ASK
1
Preguntar al usuario (vía elicitation) en vez de fallar seco: backend caído, modelo fuera del catálogo, output_format vacío. 0 lo desactiva
LOCAL_DELEGATE_ASK_TIMEOUT
30
Segundos de espera por una respuesta; agotados, la tool sigue como si no hubiera preguntado
LOCAL_DELEGATE_LOG_DIR
(dir de datos de usuario)
Directorio de los usage-YYYYMM.jsonl rotados por mes y del clients.jsonl, y de project-salt, project-names.json y self-projects.json. El daemon, los hooks y los scripts tienen que resolver el mismo: si la defines en el lanzador y no en el daemon, o al revés, la sal y el mapa de nombres difieren entre filas y eventos
LOCAL_DELEGATE_LOG
(vacío = rotación activa)
Si se fija, ruta de un usage.jsonl explícito sin rotar (compatibilidad)
LOCAL_DELEGATE_MACHINE_NAME
(nombre corto del equipo)
Nombre de esta máquina en el log de uso (host) y en la cabecera X-Local-Delegate-Host que va al backend; útil si dos equipos se llaman igual
LOCAL_DELEGATE_MODEL_MECHANICAL
gemma3-4b
Modelo para clasificar/extraer/resumen corto
LOCAL_DELEGATE_MODEL_LONG
gemma4-26b-a4b
Modelo para documentos largos
LOCAL_DELEGATE_MODEL_CODE
qwen36-35b-a3b
Modelo para código
LOCAL_DELEGATE_MODEL_VISION
gemma4-12b
Modelo de visión para local_describe_image
LOCAL_DELEGATE_MAX_IMAGE_MB
8
Tope de tamaño de imagen para local_describe_image
LOCAL_DELEGATE_DUMP_CHUNK_NOTES
(vacío: apagado)
Carpeta local donde cada operación troceada deja la salida de cada paso; solo para medir, nunca sale de la máquina
LOCAL_DELEGATE_LONG_INPUT_CHARS
6000
Umbral mecánico↔largo
LOCAL_DELEGATE_EXTRACT_TABLE_LONG
1
local_extract manda al modelo largo una entrada por debajo del umbral que trae una tabla (HTML, ARIA, Markdown/GFM, CSV o TSV), y lo dice en role_reason (respuesta, con el formato, y log). Tarda más y puede cargar el modelo; 0 lo apaga
LOCAL_DELEGATE_SUMMARIZE_TABLE_LONG
1
La misma regla para local_summarize: el resumen acaba con un aviso que nombra el formato y la fila del log lleva role_reason; 0 lo apaga
LOCAL_DELEGATE_CHUNK_CHARS
3500
Tamaño de trozo al partir documentos largos (local_translate, local_delegate)
LOCAL_DELEGATE_CHUNK_MAX_TOKENS
2048
Techo de max_tokens por trozo
LOCAL_DELEGATE_CHUNK_MIN_CHARS
400
Trozo mínimo: por debajo ya no se vuelve a partir
LOCAL_DELEGATE_JSON_SCHEMA
auto
response_format con schema en local_extract: auto/on/off
LOCAL_DELEGATE_FEEDBACK
1
Línea de ahorro anexada al resultado cuando source=path (0 la apaga). En local_extract no se anexa al texto —rompería el JSON—: va dentro de _local_delegate
LOCAL_DELEGATE_ALLOWED_DIRS
(vacío = sin restricción adicional)
Raíces permitidas para path y target, separadas por ;. Las rutas protegidas (credenciales, arranque automático, configuración que ejecuta código) se rechazan siempre, con o sin esta variable: ver Configuración
LOCAL_DELEGATE_DENY_PATHS
(vacío)
Rutas extra, separadas por ;, que las tools no leen ni escriben; se suman a la lista protegida
LOCAL_DELEGATE_WEB
1
Web embebida del modo stdio (0 para desactivarla). Desde la 0.42.0 pide el token de LOCAL_DELEGATE_WEB_TOKEN si está puesto, igual que el daemon
LOCAL_DELEGATE_WEB_HOST / _PORT
127.0.0.1 / 9393
Host/puerto de la web o del daemon. Vacía cuenta como no puesta
LOCAL_DELEGATE_WEB_ALLOWED_HOSTS
(vacío)
Nombres extra que el puerto admite en la cabecera Host, separados por comas (p. ej. el de tailscale serve). Por defecto solo loopback y WEB_HOST, contra el DNS rebinding (desde la 0.42.0: sin ella, entrar por otro nombre da 421); * desactiva la comprobación
LOCAL_DELEGATE_WEB_FONTS
1
Tipografía de marca desde Google Fonts (0 = cero peticiones a terceros)
Solo si AUTOSTART=1; LLAMASWAP_CONFIG además activa el turno y la afinidad del daemon (con el extra [llamaswap]). LLAMASWAP_EXE tiene que ser una ruta absoluta a un fichero que exista (si no, avisa y no arranca); sin ella, llama-swap se busca solo en las carpetas absolutas del PATH, nunca en la carpeta actual (desde la 0.44.0)
LLAMASWAP_WATCH_CONFIG
0
1 añade -watch-config al backend autoarrancado
LOCAL_DELEGATE_FALLBACK
1
Respaldo entre modelos: si el modelo de un rol falla por su culpa, responde el siguiente de su cadena (_MAX_HOPS=2; cadenas con _<ROL>, ver la wiki). 0 lo apaga
LOCAL_DELEGATE_COOLDOWN
1
Enfriamiento por modelo: 3 fallos seguidos (_FAILURES) lo paran 120 s (_S), doblando hasta 900 s (_MAX_S). 0 lo apaga
LOCAL_DELEGATE_BACKEND_BREAKER
1
Corte por backend inalcanzable: 3 fallos de conexión seguidos (_FAILURES) hacen que las local_* respondan al momento «backend inalcanzable, hazlo tú» durante 60 s (_S), doblando hasta 600 s (_MAX_S), sin contar como delegación; al vencer, la siguiente llamada prueba. 0 lo apaga
LOCAL_DELEGATE_REMOTE_TURN_CUT
1
Corte de turno remoto (#577): con el turno de la otra máquina sin responder, las operaciones van sin turno y de una en una por proceso (Claude Code y el daemon de Desktop llevan cada uno su fila); si una agota su plazo de lectura en el backend (_FAILURES, 1; un 5xx al momento no cuenta), durante 120 s (_S, doblando hasta 600 s, _MAX_S) las que irían sin turno fallan al momento con «el turno remoto no responde; reintentar ahora no sirve». 0 lo apaga (la serie se queda)
LOCAL_DELEGATE_COST_FALLBACK
(vacío = claude-opus-5-5 en subagente)
Con qué modelo e hilo se valora una delegación sin modelo atribuido: modelo o modelo:main|subagent. Un valor inválido no rompe nada: el panel usa el declarado y lo dice
LOCAL_DELEGATE_COMMIT_LANGUAGE
(vacío = el idioma vigente)
Idioma del mensaje de local_commit_msg: es, en, fr, pt, de, it o un nombre libre. Vacío: el idioma vigente del producto; diff: el idioma predominante de los textos del diff
LOCAL_DELEGATE_OUTPUT_LANGUAGE
(vacío = el idioma vigente)
Idioma en que las tools de texto libre (local_summarize, local_lint_summary, local_explain_code, local_describe_image) piden responder al modelo: fr, pt, português… No cambia la interfaz ni local_commit_msg
LOCAL_DELEGATE_TURN_MAX_S
600
Turno del daemon entre modelos que chocan en llama-swap: si la primera de la cola lleva estos segundos esperando y el daemon lleva otros tantos sin que empiece ni termine ninguna llamada al backend, se le concede el turno igual (turn: "forced" en el log)
LOCAL_DELEGATE_TURN_YIELD_S
120
Cesión del turno entre trozos: si la primera de la cola lleva estos segundos esperando un modelo que choca con el de una operación que tiene el turno desde hace otro tanto, esa operación lo suelta antes de su siguiente trozo y vuelve al final de la cola (turn_yields en el log). Coste: como mucho una pareja de cargas de modelo cada este tiempo cuando dos operaciones largas chocan. 0 lo desactiva
LOCAL_DELEGATE_CALL_MAX_S
1800
Plazo propio del daemon para una llamada, cola incluida: al pasarlo se cancela y queda en el log como fallo (cancel_reason: "deadline"). 0 lo desactiva
LOCAL_DELEGATE_PROGRESS_INTERVAL_S
20
Cada cuántos segundos una llamada viva manda notifications/progress con su fase (puesto en la cola, plaza, trozo k/N), para que el cliente no la corte por inactividad (Claude Code: 300 s). 0 lo desactiva
LOCAL_DELEGATE_TURN_WAIT_NOTICE_S
60
Si una llamada esperó el turno al menos estos segundos, su respuesta lleva un aviso ([local-delegate warning: …]; en local_extract, _local_delegate.turn_wait) que dice cuánto esperó, que fue cola de otras delegaciones y no lentitud del modelo, y que agrupar las llamadas por tool lo reduce. No va en local_classify (etiqueta exacta) ni en una respuesta de error. 0 lo desactiva
LOCAL_DELEGATE_QUEUE_MAX_WAIT_S
900
Máximo de segundos que quien espera turno o plaza aguanta sin que la cola avance (una cola lenta que avanza no corta a nadie): al pasarlo la llamada falla en el acto con «cola saturada» (error: "queue_saturated"). 0 lo desactiva
LOCAL_DELEGATE_SLOW_THRESHOLD
0.5
Una llamada es «lenta» (slow en el log, «lento ×0,37» en el panel) si genera a menos de esta fracción de la velocidad normal de su modelo
LOCAL_DELEGATE_AFFINITY_MARGIN_S
5
Afinidad: un modelo ya cargado solo se aprovecha si le quedan al menos estos segundos de TTL
LOCAL_DELEGATE_BACKEND_PARAMS
(vacío)
Override puntual, clave a clave, de los parámetros por rol de backend-params.json (muestreo y razonamiento): rol.clave=valor;…, p. ej. code.top_k=20. Exige reiniciar el daemon; el fichero no
Los parámetros por rol que viajan en cada petición al backend (top_k, temperature,
enable_thinking con su presupuesto…) se guardan en backend-params.json y se editan con
local-delegate backend-params show|set|unset|reset; la lista cerrada de claves, la precedencia y
el razonamiento están en la wiki.
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 contexto conservado = la entrada leída server-side (llamadas con source=path que salieron
bien) menos lo que la tool te devolvió, contada una vez por delegación aunque el MCP la trocee.
Se mide en caracteres y se pasa a tokens de Claude con una tabla de densidad medida por familia
de tokenizador y tipo de contenido (prosa, código, log, datos estructurados, diff): un .md no
cuenta lo mismo que un .json, y Haiku 4.5 no cuenta como Opus 5.5. Las imágenes salen de esa
cifra —sin sus dimensiones no hay forma de saber cuántos tokens le costarían a Claude— y se enseñan
aparte. Enfrente, el coste local = los tokens que consumió de verdad tu GPU sumando todas las
llamadas: una delegación troceada repite el prompt de sistema en cada trozo, y esa diferencia es lo
que costó trocear. Ahí se usa el token real que reporta el backend; chars ÷ 4 es solo el respaldo
del modelo local cuando no lo da. Detalle en la wiki.
El panel enseña además un equivalente estimado a precio de API: lo que costaría ese mismo
contexto leído por Claude a precio de lista, entre una cota baja y una estimación que cuenta las
peticiones en las que ese contenido se habría vuelto a leer de la caché. No es dinero que hayas
ahorrado: tu suscripción es de tarifa plana. Es una estimación con supuestos a la vista (con qué
modelo se atribuye cada delegación, cuántas peticiones siguieron, qué densidad se usó) y no
descuenta las relecturas del mismo fichero. Junto a ella, un bloque de cuota que sale «sin
calibrar» hasta que hay al menos tres medidas del statusline de ventanas distintas, y nunca enseña
un porcentaje sin esa calibración. Para atribuir el histórico y alimentar esos dos bloques, lanza
de vez en cuando local-delegate recompute-cost (lee tus transcripts en local y escribe solo
agregados; desde la 0.50.0, si no puede leer uno de sus ficheros se para sin reescribirlo);
doctor avisa si hay delegaciones a punto de quedarse sin transcript.
Las pruebas no cuentan: las delegaciones del cliente mcp de los scripts, las de bancos y
las que caen en una ventana de prueba se apartan del panel y de local_status. Antes de probar
en vivo contra el MCP o el daemon, marca el intervalo y guarda el id que imprime:
bash
local-delegate test-window start --label "prueba del lunes"# imprime el id
local-delegate test-window stop <id>
local-delegate test-window list # ventanas y filas en cada una
El botón Pruebas de la barra del panel las vuelve a enseñar; su ⓘ dice cuántas quedaron fuera.
Por proyecto: cada fila del log guarda desde qué proyecto de Claude Code se pidió la delegación
(caller_project, un hash con la sal local de LOG_DIR/project-salt, nunca el nombre ni la ruta),
y cada evento de la telemetría de hooks, project. El panel enseña la tarjeta Por proyecto
(delegaciones y ahorro de cada repo, de mayor a menor) y, en la barra de filtros, un selector de
proyecto que filtra todo el panel; por defecto lo enseña todo. El nombre legible sale de un mapa
local aparte, LOG_DIR/project-names.json (hash → la última carpeta de la ruta real del proyecto,
como webshop, con la carpeta padre si dos coinciden y la ruta completa al pasar el ratón), que se
escribe al calcular el hash y nunca sale de la máquina; las filas de antes de existir el mapa se
nombran solas la primera vez que abres el panel, desde las carpetas de ~/.claude/projects. Un hash sin nombre sale como «Proyecto sin nombre» y las filas sin proyecto,
como «Sin proyecto». La tarjeta «Quién delegó» separa hilo principal, subagentes y mod. Quien tenga
el log yproject-salt puede confirmar un nombre de proyecto por fuerza bruta: no compartas ese
fichero (ni project-names.json) junto a un log. Detalle en
Savings & metrics y en
Configuration.
El panel sale en español o en inglés según el idioma de tu navegador, y el selector ES/EN de su
cabecera lo cambia (se recuerda en ese navegador). Ver
Savings & metrics.
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:
Componente
Dónde
Qué hace
Entrada MCP
config de Claude Code / ~/.codex/config.toml / ~/.config/opencode/opencode.json[c]
registra el servidor (stdio con uvx o HTTP contra el daemon)
Hooks
plugin de Claude Code local-delegate@local-delegate (o ~/.claude/hooks/local-delegate/ + settings.json)
sugieren delegar; los de lectura además pueden rechazar una lectura completa de documentación, si se enciende; uno anota qué agente pidió cada delegación
Hooks de Codex
~/.codex/hooks.json, junto a los tuyos
dos hooks consultivos (UserPromptSubmit y SubagentStart), uno que resume las lecturas grandes de prosa por shell y frena la escritura sobre lo leído solo resumido (PreToolUse sobre Bash, apply_patch y lecturas MCP) y uno que anota la sesión de cada delegación (PreToolUse sobre las tools de local-delegate), que Codex ejecuta solo cuando los apruebas en /hooks
Skill
~/.claude/skills/local-delegation/ y ~/.config/opencode/skill/local-delegation/
regla de oro y catálogo de tools
Memoria
bloque gestionado en ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md y ~/.config/opencode/AGENTS.md
la regla en una nota corta siempre cargada
Por defecto se configuran solo los clientes que tengas instalados; se elige a mano con
--clients claude|codex|opencode. Los hooks son de Claude Code y, desde la 0.53.0, también
de Codex: cuatro en ~/.codex/hooks.json (dos consultivos, uno que resume las lecturas grandes de
prosa por shell y frena la escritura sobre lo leído solo resumido, y uno que anota de qué sesión
viene cada delegación), que no tocan ni mueven los tuyos y que no corren hasta que los apruebas en
/hooks. Ver
Hooks de Codex. opencode extiende con
plugins en TypeScript, que es otra superficie, y Claude Desktop no tiene hooks en absoluto. El
plugin de Claude Code no sirve en Codex: Codex 0.169 rechaza su hooks/hooks.json entero (por
el modules del mod) con solo un aviso al arrancar. Si lo importaste a mano, local-delegate doctor lo dice y da codex plugin remove local-delegate@<marketplace>, que deja intacta la entrada
MCP. Cada pieza se puede excluir (--no-hooks, --no-skill, --no-memory, --no-mcp).
Todo sale en español o en inglés. install y update guardan el idioma de la sesión en
que corren (LOCAL_DELEGATE_LANG=es|en, o el del sistema) en language.json, para que el
daemon y los hooks lo usen también, y escriben la skill, el bloque de memoria y el catálogo de
los subagentes en ese idioma. Precedencia y cómo volver a seguir al sistema:
Idioma.
Actúan solos tres hooks: UserPromptSubmit (intenciones mecánicas), SubagentStart (le recuerda
a cada subagente cargar las tools local_* y leer por rangos) y record_call.py
(PreToolUse sobre las tools de local-delegate), que no avisa ni bloquea: anota qué agente pidió
cada delegación y con qué esfuerzo, para atribuir el coste equivalente a su modelo. Los dos de
lectura —PreToolUse/Read y PreToolUse/Bash|PowerShell— quedan apagados salvo
--enable-read-hook, que los enciende juntos (--disable-read-hook o uninstall los apagan). Van juntos
porque son una regla sola sobre dos caminos: cerrar la tool Read y dejar cat informe.md
abierto no cambia la conducta, la muda de sitio. Con una imagen grande que acepta
local_describe_image (.png, .jpg, .gif, .webp) el aviso recomienda esa tool con path,
no una lectura por rangos; .svg, .bmp, .ico, las imágenes pequeñas, los .pdf y los
.ipynb pasan en silencio.
Esos dos avisan; rechazar una lectura es otra cosa y viene aparte y apagada
(LD_HOOK_READ_BLOCK). Solo alcanza a la lectura completa de un .md o un .txt grande, con
el backend local respondiendo, y el mensaje del rechazo nombra la tool que sirve y la salida de
emergencia: leer por franjas nunca se bloquea. El motivo de que exista es que está medido —cuatro
veces— que sugerir no cambia la conducta.
Ver Instalación de la integración y
docs/recipes/claude-code-hooks.md.
Plugin de Claude Code, comandos del mod y Claude Desktop
Desde la 0.40, con Claude Code 2.1.292 o posterior instalado con uv tool, install entrega los
hooks como un plugin (local-delegate@local-delegate) en vez de escribirlos en
settings.json, y migra sola una instalación anterior conservando el bloqueo de lectura. Si no se
cumplen las condiciones, sigue con settings.json y dice por qué; --claude-delivery settings
vuelve atrás a mano y update lo respeta. El MCP no va dentro del plugin.
El plugin trae además un mod, que corre dentro de Claude Code sin gastar turnos del modelo:
/local-summarize <ruta>, /local-commit (propone el mensaje desde git diff --cached; solo
lo muestra) y /local-lint <fichero|comando> llaman a la tool local directamente.
Deja fijas local_summarize, local_extract, local_lint_summary y local_commit_msg, para
que el modelo no tenga que buscarlas con ToolSearch.
Pone sobre el prompt una banda con el estado de local-delegate en la sesión: en la terminal,
una barra de una fila con fondo y una etiqueta de estado (● LISTO, ◐ DELEGANDO,
◔ CARGANDO, ○ CAÍDO), el modelo, la tool en curso con su trozo (7/9) y lo que lleva (3 min 16 s), las delegaciones y el ahorro de la
sesión y el modo de lectura (opción status_style: bar o line, una raya sobre una línea);
en Claude Desktop, una sola línea de texto en dos tonos, sin píldora ni enlace. Desde la 0.45.0,
con varias delegaciones a la vez nombra primero la que procesa el backend y, si todas esperan, la
más antigua con su espera (en cola · 4 min 0 s). Una delegación que espera a que llama-swap
cambie de modelo dice ◐ ESPERANDO BACKEND con el modelo que pidió, no el cargado. Se
refresca sola cada segundo mientras hay una delegación en curso. Desde la 0.50.0 un solo sondeo
lento no la pone en ○ CAÍDO: como el panel, hace falta un segundo fallo seguido. Mientras
llama-swap arranca un modelo dice ◔ CARGANDO con ese modelo, aunque /v1/models no responda
a tiempo (#628): ○ CAÍDO queda para un backend que no responde. La cuota de Claude no va
aquí: es de la status line.
Desde la 0.41, el mod de lectura (encendido por defecto, opción read_mod_enabled) resume
con local_summarize la prosa grande que se lee entera y entrega el resumen como resultado de
la propia tool; con diálogo pregunta antes. Tras un resumen, escribir en ese fichero se rechaza
hasta leerlo de verdad. Mientras actúa, los hooks de lectura de la sesión se apartan. Para
decidir qué lee cada llamada le pregunta al daemon, sin arrancar procesos (la sobrecarga medida
por llamada Bash queda dentro del ruido). Sin valor guardado cuenta como encendido; si lo
apagaste en la 0.40.0, se vuelve a encender en el menú de configuración del plugin. Desde la
0.44.2 una lectura por rango pasa siempre literal en un subagente (sin gastar el margen del
80 % del hilo principal), en un fichero corto (200 líneas o menos y menos de 32 KB) y cuando el
rango empieza después de la última línea. Desde la 0.50.0 reutiliza el resumen de un fichero
cuyo texto no cambió (summary_reused en la telemetría, sin contar como ahorro nuevo), y los
hooks dejan pasar la lectura cuando la sesión no tiene el MCP. Desde la 0.51.0, si Claude Code
pasa el resumen a segundo plano, la lectura va literal en vez de entregar su aviso como resumen,
y la cabecera cuenta las líneas que el fichero tiene en ese momento.
Tras actualizar, abre una sesión nueva de Claude Code: los mods se cargan al empezar la sesión.
En Windows, install --desktop añade el chat de Claude Desktop: escribe una entrada que lanza
local-delegate desktop-bridge, un puente stdio hacia el daemon que lee el token él mismo, porque
Desktop no pasa su entorno a los MCP. Para bajar a la 0.39, uninstall antes. Todo el detalle en
Entrega por plugin de Claude Code.
El mod en Codex
Codex no carga el mod ni tiene con qué: no hay comandos de usuario sin modelo (solo !comando, que
corre un comando local) ni una barra en la que pintar algo propio (/statusline elige campos fijos
de Codex). Lo que sí tiene es una forma de que el modelo vea las tools sin buscarlas:
install --clients codex --codex-direct-tools pone omit_tools_from = ["deferred"] en la entrada
MCP. Entran las once tools a la vez (Codex no deja elegir una a una), unos 15,8 KB más por turno,
así que va apagado por defecto; update conserva lo que elijas. La tabla completa, con la
evidencia de cada fila y las pruebas en vivo pendientes:
Codex: qué tiene y qué no del mod.
Groups de llama-swap (opcional)
Con pip install "local-delegate-mcp[llamaswap]" quedan disponibles los CLIs para gestionar
groups de llama-swap (un pool que se turna y, solo si lo pides, un modelo que se queda
cargado) 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):
bash
local-delegate check-llamaswap --config config.yaml --vram-gb 16 --ram-gb 32
local-delegate init-llamaswap --config config.yaml --swap gemma3-4b,gemma4-26b-a4b,qwen36-35b-a3b --vram-gb 16 --ram-gb 32
local-delegate llamaswap residency # qué se queda cargado y con qué TTL; no escribe
local-delegate llamaswap residency --none --ttl gemma3-4b=120 # volver a «ningún residente»
Lo recomendado es ningún residente: con el turno del daemon, los modelos que chocan se
reparten el backend sin pelearse, y un modelo ya cargado se aprovecha cuando hay una celda
aprobada para esa tool (ver Tools). La residencia es opt-in:
init-llamaswap --resident ID o llamaswap residency --pin ID dejan ese modelo en un grupo
persistent con ttl: 0, y retiene su VRAM de forma permanente (--pin pide la VRAM medida de
cada modelo con --vram-model ID=GiB y se niega si no cabe junto al peor caso del resto). --ttl-resident vale 0 por defecto: con persistent y un TTL
mayor que 0 el modelo se descarga igual y no hay residencia de verdad.
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
una copia <config>.<AAAAMMDD-HHMMSS>.bak). llamaswap residency edita solo las líneas que
cambian, deja la misma copia con fecha, no escribe con delegaciones en curso (salvo --now) y
dice qué hizo llama-swap con la recarga. 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.