Plug-in (tunaLlama) que delega a geração pesada de código do Claude Code / Codex CLI para um LLM local

É uma ferramenta de delegação criada para quem vê o limite de uso do plano fixo do Claude Code ou do Codex CLI acabar rápido ao fazer vibe coding.

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

Ao programar com Claude Code, as etapas com saída longa — como geração de código, revisão de arquivos e refatoração — são as que mais consomem tokens. Mas essas etapas normalmente são mais determinísticas, e a diferença de qualidade entre modelos tende a ser pequena. Já a decomposição (requisitos → lista de tarefas) e a validação (se o resultado devolvido atende aos requisitos) têm entradas e saídas curtas, mas apresentam diferenças maiores de qualidade entre modelos.

O tunaLlama é um backend + plug-in que cristaliza essa assimetria diretamente no fluxo de código.

PapelModeloResponsabilidadeArchitectClaude / Codex (plano fixo)Decomposição / especificação / validação / integraçãoDeveloperLLM local (Ollama / Cloud / LM Studio)Geração de código / auto-revisão / auto-correçãoReviewerMesma sessão do ArchitectVeredito final

Só as etapas pesadas em tokens vão para o ambiente local, enquanto as etapas curtas de decomposição e validação continuam no Claude / Codex.

Tanto o Claude Code quanto o Codex CLI conseguem usar ferramentas externas por meio de plug-ins.
Depois de instalar uma vez, a estrutura permite que o agente invoque isso por conta própria quando achar necessário enquanto trabalha.
O usuário não precisa pedir toda vez "use esta ferramenta". O tunaLlama é um tipo desses plug-ins e expõe 13 ferramentas por meio de um servidor MCP (Model Context Protocol).
Um único repositório funciona tanto para Claude Code quanto para Codex CLI.
(O arquivo claude-plugin/marketplace.json é reconhecido por ambos os clientes.)

Quando o usuário solicita uma tarefa (coreano / inglês)

1. O Architect decompõe a tarefa — se for curta, tuna_dev_review; se for longa, cria um documento de spec e depois usa tuna_dev_review_from_spec
2. O backend repete o loop generate → review → fix (delegação limitada — a condição de parada é review pass ou max iter)
   Todas as chamadas são registradas em SQLite e indexadas com o analisador morfológico coreano Kiwi
3. O Architect valida o resultado e o devolve ao usuário

Quando comparado o uso do LLM local mid-size sozinho vs. após o Architect organizar o contexto e repassar, houve +0.58 ~ +0.64 (validação em 3 modelos, Phase 7-2). Isso significa que, mesmo com o mesmo LLM local, o resultado melhora de forma significativa quando o contexto é bem organizado antes de ser enviado.
No entanto, essa medição é baseada em seeds sintéticos. Como foi medida sobre um conjunto de testes preparado antecipadamente com cenários de tarefas frequentes no mundo real, é uma questão separada se o mesmo resultado aparecerá de forma idêntica em fluxos reais de usuários. As métricas de dogfooding orgânico passaram a ser carregadas automaticamente em ~/.tunallama/metrics.db a partir da v0.5.7+ em quatro tipos (standalone_toy_rate / convention_adherence_rate / ast_excess_score / syntactically_valid), e a reprodutibilidade com usuários externos continua sendo coletada junto com o baseline acumulado.

Quanto à economia de limite, como as fórmulas de cálculo de limite da Anthropic / OpenAI não são públicas, não há um resultado quantitativo como "economiza X%". A ideia é: "é melhor do que usar sem isso".

Suporte a coreano

Com o analisador morfológico Kiwi integrado, é possível fazer indexação de busca em coreano. Para entradas sem espaços, como "geomgeom de e-mail", a busca ainda pode encontrar correspondência por "e-mail". A estrutura compensa a limitação do tokenizador unicode61 do FTS5, que tende a dividir o coreano apenas em sílabas / jamo. No entanto, neologismos / termos técnicos que o Kiwi não consegue processar podem afetar a qualidade da busca.

Instalação em 5 minutos

Basta mandar uma linha na sessão:

"Instale seguindo o INSTALL.md de https://github.com/hang-in/tunaLlama";

O agente instala as dependências, configura o .env, registra o plug-in e faz a validação passo a passo por conta própria.
Se preferir instalação manual, consulte o README.

Matriz de funcionamento nos dois ambientes

Claude Code e Codex CLI funcionam com o mesmo repositório, mas alguns recursos só foram validados em um dos lados (medição real na v0.5.6, Claude Code 2.1.138 + Codex CLI 0.128.0):

ItemClaude CodeCodex CLIFerramentas MCP: chamada das 13✓✓
Compartilhamento de DB (~/.tunallama/memory.db)✓✓
Compartilhamento de state.md✓✓
Chamada explícita de tuna_load_memory / tuna_recall✓✓
Agents auto-discovery✓
SessionStart hook + state.md auto-prepend✓
(v0.5.5+)✗MCP resource auto-attach✗✗
No Claude Code, o state.md auto-prepend funciona automaticamente,
No Codex CLI, recomenda-se que o usuário faça uma chamada explícita a tuna_load_memory no primeiro turno ou busque os docs diretamente.
Como a chamada das 13 ferramentas MCP funciona normalmente em ambos, a delegação em si é possível no nível da ferramenta.

Limitações

A economia de limite é baseada em dados percebidos de uso (mencionados acima)
O custo do system prompt das ferramentas MCP é um trade-off intencional — as descriptions + schema das 13 ferramentas adicionam cerca de 1.6k tokens ao system prompt de cada conversa. Isso não é aumento acidental de contexto, mas um custo de affordance projetado para que o Architect selecione a ferramenta de delegação apropriada

Ambiente de LLM local obrigatório (Ollama etc., Ollama Cloud também funciona normalmente) — sem isso, não funciona
Os valores de busca são baseados em seeds sintéticos (mencionados acima)
Alguns recursos do Codex CLI não funcionam (ver matriz acima)
Possível impacto na qualidade da busca com neologismos / termos técnicos em coreano

Por que não prompt seed / AGENTS.md

Não tenta resolver o limite de contexto fazendo o agente ler mais documentos.
Em vez disso, divide as tarefas em unidades pequenas e as envia por ferramentas MCP para LLMs locais / de baixo custo, enquanto o modelo Architect de nível superior se concentra em uma spec curta, no resultado da revisão e no julgamento do diff final.
Regras operacionais baseadas em documentos podem, com o tempo, gerar problemas como stale state, drift e lost-in-the-middle.
Para evitar isso, o tunaLlama registra as chamadas de delegação em SQLite e mantém uma camada de execução que faz busca / recall quando necessário.

Para quem isso pode ajudar

Usuários do plano fixo Claude Code Pro/Max (motivação para gerenciar o limite)
Usuários do Codex CLI (gerenciamento do plano fixo / quota de API da OpenAI)
Quem já usa ambiente Ollama local / Ollama Cloud / LM Studio
Quem trabalha com tarefas em coreano (integração com Kiwi)

Testes / licença

Versão v0.5.x utilizável para dogfooding. 507 testes unitários/plug-in + 27 testes de integração/qualidade de busca, 90% de cobertura.
O comando de medição está especificado no README (pytest --no-cov -q -m "not search_quality and not integration").
A licença é MIT. O README em inglês (README.en.md) segue sincronizado. Feedback / issues / PRs são bem-vindos.
Sugestões de compatibilidade com outros AI CLI também são bem-vindas.