Plug-in para delegar la generación pesada de código de Claude Code / Codex CLI a un LLM local (tunaLlama)

Es una herramienta de delegación creada para quienes agotan rápido el límite de uso de tarifa plana de Claude Code o Codex CLI al hacer vibe coding.

https://github.com/hang-in/tunaLlama

Cuando programas con Claude Code, las etapas con salidas largas —generación de código, revisión de archivos, refactorización— son las que más tokens consumen. Pero estas etapas por lo general son deterministas y la diferencia de calidad entre modelos es pequeña. En cambio, la descomposición (requisitos → lista de tareas) y la validación (si el resultado devuelto satisface los requisitos) tienen entradas y salidas cortas, pero allí la diferencia de calidad entre modelos sí es grande.

tunaLlama es un backend + plug-in que fija esa asimetría tal cual dentro del flujo de código.

rolmodeloresponsabilidadArchitectClaude / Codex (tarifa plana)descomposición / especificación / validación / integraciónDeveloperLLM local (Ollama / Cloud / LM Studio)generación de código / auto-revisión / auto-correcciónReviewerla misma sesión que Architectveredicto final

Solo las etapas pesadas en tokens se desvían a local, y las etapas cortas de descomposición y validación permanecen en Claude / Codex.

Tanto Claude Code como Codex CLI pueden usar herramientas externas mediante plug-ins.
Una vez instalado, la estructura está hecha para que el agente lo invoque por su cuenta cuando considere que hace falta mientras trabaja.
No hace falta que el usuario diga cada vez "usa esta herramienta". tunaLlama es un tipo de ese plug-in y expone 13 herramientas a través de un servidor MCP (Model Context Protocol).
Con un solo repositorio funcionan tanto Claude Code como Codex CLI.
(ambos clientes reconocen el archivo claude-plugin/marketplace.json.)

Cuando el usuario solicita una tarea (coreano / inglés)

1. Architect descompone la tarea: si es corta, tuna_dev_review; si es larga, redacta primero un documento spec y luego usa tuna_dev_review_from_spec
2. El backend repite el bucle generate → review → fix (delegación acotada - la condición de cierre es review pass o max iter)
   Todas las llamadas se registran en SQLite y se indexan con el analizador morfológico coreano Kiwi
3. Architect valida el resultado y lo devuelve al usuario

Al comparar un LLM local mid-size ejecutado por sí solo vs. el caso en que Architect ordena el contexto antes de entregárselo, hubo una mejora de +0.58 ~ +0.64 (validado en 3 modelos, Phase 7-2). Esto significa que, incluso con el mismo LLM local, si se le pasa un contexto bien organizado, el resultado mejora de forma significativa.
Sin embargo, esta medición se basa en seeds sintéticos. Como se midió sobre un conjunto de pruebas preparado de antemano con escenarios de tareas frecuentes en la práctica, es otro tema si en flujos de trabajo reales de usuarios saldrá exactamente igual. Desde v0.5.7+, las organic dogfooding metrics de 4 tipos (standalone_toy_rate / convention_adherence_rate / ast_excess_score / syntactically_valid) se cargan automáticamente en ~/.tunallama/metrics.db, y se sigue recopilando reproducibilidad de usuarios externos hasta llegar al baseline acumulado.

En cuanto al ahorro de límite, como las fórmulas de cálculo de límites de Anthropic / OpenAI no son públicas, no hay un resultado cuantitativo tipo "ahorra X%". La idea es: "es mejor que usarlo sin más".

Soporte para coreano

Al integrar el analizador morfológico Kiwi, es posible hacer indexación de búsqueda en coreano. Para una entrada sin espacios como "verificación de correo", buscar por "correo" también da match. Es una estructura que compensa la limitación del tokenizador unicode61 de FTS5, que en coreano solo corta por sílabas / jamo. Aun así, los neologismos o términos técnicos que Kiwi no pueda procesar pueden afectar la calidad de búsqueda.

Instalación en 5 minutos

Solo tienes que lanzar una línea en la sesión:

"Sigue INSTALL.md de https://github.com/hang-in/tunaLlama para instalarlo"

El agente instala las dependencias por su cuenta, configura .env, registra el plug-in y realiza la validación paso a paso.
Si prefieres instalación manual, consulta el README.

Matriz de funcionamiento en ambos entornos

Claude Code y Codex CLI funcionan con el mismo repositorio, pero algunas funciones solo han sido validadas en uno de los dos lados (medición real en v0.5.6, Claude Code 2.1.138 + Codex CLI 0.128.0):

ítemClaude CodeCodex CLIinvocación de 13 herramientas MCP✓✓
compartir DB (~/.tunallama/memory.db)✓✓
compartir state.md✓✓
llamadas explícitas a tuna_load_memory / tuna_recall✓✓
Agents auto-discovery✓
SessionStart hook + state.md auto-prepend✓
(v0.5.5+)✗MCP resource auto-attach✗✗
En Claude Code, state.md auto-prepend funciona automáticamente,
y en Codex CLI se recomienda que el usuario haga una llamada explícita a tuna_load_memory en el primer turno o que recupere los docs directamente.
Como la invocación de las 13 herramientas MCP funciona bien en ambos lados, la delegación en sí es posible a nivel de herramientas.

Limitaciones

El ahorro de límite se basa en datos percibidos (mencionados arriba)
El costo del system prompt de las herramientas MCP es un trade-off intencional - la description + schema de 13 herramientas anteponen alrededor de 1.6k tokens al system prompt en cada conversación. No es accidental context bloat, sino un costo de affordance diseñado para que Architect pueda elegir la herramienta de delegación adecuada

El entorno de LLM local (Ollama, etc.; Ollama Cloud también funciona correctamente) es obligatorio - sin eso no funciona
Los valores de búsqueda se basan en seeds sintéticos (mencionado arriba)
Algunas funciones de Codex CLI no funcionan (ver matriz anterior)
Posible impacto en la calidad de búsqueda con neologismos / términos técnicos en coreano

¿Por qué no usar prompt seeds / AGENTS.md?

No intenta resolver los límites de contexto haciendo que el agente lea más documentación.
En cambio, divide la unidad de trabajo en partes pequeñas y las entrega a un LLM local / de bajo costo mediante herramientas MCP, mientras que el modelo Architect de nivel superior se concentra en spec breves, resultados de review y la evaluación final del diff.
Las reglas operativas basadas en documentación pueden generar con el tiempo problemas de stale state, drift y lost-in-the-middle.
tunaLlama evita eso registrando las llamadas de delegación en SQLite y manteniendo una capa de ejecución para buscar / recuperar cuando haga falta.

¿A quién podría resultarle útil?

Usuarios de Claude Code Pro/Max con tarifa plana (motivación de gestionar límites)
Usuarios de Codex CLI (gestión de tarifa plana / API quota de OpenAI)
Quienes ya tienen un entorno de Ollama local / Ollama Cloud / LM Studio
Quienes trabajan con tareas en coreano (integración de Kiwi)

Pruebas / licencia

v0.5.x es una usable dogfooding release. 507 unit/plugin tests + 27 integration/search_quality tests, 90% coverage.
El comando de medición está indicado en el README (pytest --no-cov -q -m "not search_quality and not integration").
La licencia es MIT. Se mantiene sincronizado el README en inglés (README.en.md). Se agradecen feedback / issues / PR.
También son bienvenidas propuestas de compatibilidad con otros AI CLI.