Klugg, ou como não fingir que alguém aprendeu

Pedir pra uma IA explicar um assunto ficou fácil. Saber se você aprendeu continua difícil. A conversa termina, a explicação parecia clara, e uma semana depois sobrou pouco. Nada ali registrou o que você tentou, onde errou ou quando valeria revisar.

O Klugg é a minha tentativa de cuidar dessa parte. A descrição curta do repositório é “um harness de aprendizado baseado em fontes, com roteiros adaptativos, prática, evidência e progresso”. Em português de mesa de bar: você diz o que quer aprender, ele ajuda a achar o material, monta um caminho, te faz praticar e guarda o que você realmente demonstrou.

O código é privado, então aqui não vai ter trecho. Vou falar das ideias de design, que é onde o projeto tem mais coisa pra contar.

Duas portas de entrada

Tem dois jeitos de começar. Um é o momento de aprendizado: uma pergunta, um trecho de texto, um erro que você não entendeu. Pode acabar depois da explicação. O Klugg sugere uma checagem curta quando ajudaria, e você pode pular sem ele insistir.

O outro é um objetivo: quando você quer um compromisso contínuo. Aí ele ajuda a definir a capacidade que você quer ter, propõe um roteiro e revisa as recomendações conforme suas tentativas mostram o que precisa de trabalho.

Não tem questionário de perfil nem configuração de curso antes de ser útil. Isso é uma decisão explícita do documento de visão.

Mora dentro da IA que você já usa

Essa é a decisão que mais mudou a arquitetura. O Klugg funciona como app web, como linha de comando e como servidor MCP. Os três falam com o mesmo núcleo, e uma tabela única de comandos gera tanto os comandos da CLI quanto as ferramentas do MCP. Comando novo não tem como esquecer de aparecer num dos lados.

O instalador procura os agentes que você tem na máquina e registra o servidor MCP em cada um. A lista é longa: Claude Code, Codex, Cursor, Gemini CLI, Zed, VS Code e mais de dez outros. Ele também deixa uma dica pro agente: quando você pede pra ele explicar alguma coisa, ele oferece aprender aquilo no Klugg.

A parte mais interessante é o que acontece quando a chamada vem de outra IA. Nesse modo o Klugg não roda modelo próprio. Quando ele precisa de trabalho de modelo, por exemplo gerar uma questão ou avaliar uma resposta, ele pausa a operação, salva o que já foi feito e devolve a tarefa pro agente que chamou: instruções, entrada estruturada e o schema da saída esperada. O agente faz o trabalho e devolve. O Klugg valida a resposta com as mesmas checagens que aplicaria ao próprio modelo e retoma a operação de onde parou.

Isso tem consequências boas. Você usa o modelo e o plano que já paga. E o núcleo continua sendo o dono do estado: o modelo propõe, o núcleo decide o que vira registro. Tem consequências trabalhosas também. A retomada precisa ser idempotente, cada passo só aceita uma resposta, e uma operação que espera demais expira.

A palavra “evidência” é levada a sério

A parte que eu acho mais rara em produto de educação é o cuidado com o que se afirma. O glossário do projeto existe pra impedir que palavras vagas entrem no código. Alguns exemplos das regras:

• Ler uma explicação não conta como entendimento checado.
• Pular um tópico registra uma escolha, não uma habilidade demonstrada.
• Ajuda usada numa tentativa fica visível quando o resultado é interpretado.
• Um exercício copiado de uma fonte é diferente de um exercício gerado pelo tutor, e os dois são tratados de forma diferente.
• Um gabarito tirado de uma fonte diz o que a fonte afirma. Não prova que a resposta está certa.
• Você pode contestar uma avaliação. A contestação fica registrada, mas não muda nada sozinha. Ela autoriza uma reavaliação nova da mesma tentativa, e o histórico antigo é preservado.

E quando você pergunta “estou pronto?”, a resposta não é uma porcentagem. É o quanto do objetivo foi coberto, como você foi em tarefas novas, quais lacunas importam e o que aqueles resultados não garantem.

Tem também uma lista do que o Klugg não faz de propósito: streak, pontos, lembrete coercitivo, checagem obrigatória. Revisão espaçada sim, mas com permissão e por um canal que você escolhe.

Roda na sua máquina

O modo local não precisa de Docker. O banco é um PostgreSQL compilado pra WebAssembly, que sobe junto com o app. Os registros de aprendizado são seus: dá pra exportar, corrigir e apagar. A visão do produto diz que trocar de IA não deveria significar começar o histórico do zero.

A licença é AGPL-3.0.

O que foi difícil

O tamanho, pra começar. O repositório passa de 1.200 commits entre o fim de agosto e meados de novembro de 2026. Muito disso é o trabalho de fazer três interfaces, vários provedores de modelo e o modo “a outra IA trabalha por mim” se comportarem igual.

Outra regra que custa caro e eu mantenho: não existe fallback silencioso entre provedores. Se o modelo configurado não está disponível, o Klugg diz isso em vez de trocar por outro escondido.

E o mais difícil de todos ainda está aberto. O documento de visão é explícito que nada disso prova que as pessoas aprendem melhor. O critério de sucesso é desempenho retido melhor com esforço parecido, ou parecido com bem menos esforço. Isso se mede, não se afirma.

Onde ver

O código não é público. A página do projeto, com lista de espera, fica em klugg.app.