Uma linguagem que promete rodar quase na velocidade de C, paralelizar sozinha em CPU e GPU, e ainda verificar com prova formal que o código que a IA escreveu faz o que você pediu. É muita promessa junta. Eu nunca tinha encostado no Bend 1, então isso aqui é experiência nova pra mim também: no dia do lançamento, apontei meus agentes pra dois projetos meus em Rust e mandei portar pra Bend 2. O resultado desse teste é a parte mais interessante deste artigo.

Antes de começar, o disclaimer: isso é uma review feita no segundo dia de vida da linguagem, baseada num experimento de um dia. Posso estar errado em várias das minhas assunções, e tá tudo bem. Os comentários estão aí embaixo, sintam-se livres pra corrigir e complementar.

Quem é Victor Taelin

Antes de tudo, vale apresentar o autor. O Victor Taelin é um pesquisador brasileiro de programação funcional que passou mais de uma década obcecado por um problema específico: redução ótima de lambda cálculo, o algoritmo do Lamping de 1990, e depois as redes de interação do Lafont.

A própria autobiografia dele conta a trajetória: trabalhou na Ethereum Foundation, criou a linguagem de provas Formality, aposentou cedo com o ETH que acumulou de salário, voltou ao problema por conta própria, criou a HVM (Higher-Order Virtual Machine) e fundou a Higher Order Company, que levantou US$ 4 milhões de seed pra transformar a pesquisa em produto.

E aqui vai um ponto que pra mim importa muito: eu acho ótimo um brasileiro fazendo trabalho sério de design de linguagem de programação. A gente quase não tem pesquisa de ponta de verdade nesse país, muito menos em fundamentos de computação. Só por isso, o Taelin já tem o meu respeito e os meus parabéns pelo que construiu até aqui.

Então deixa registrado: as críticas deste artigo são todas construtivas, de alguém que torce pro Bend chegar mais longe, nada contra ele ou contra o projeto.

De onde vem o Bend

A primeira versão do Bend apareceu em maio de 2024, com sintaxe parecida com Python rodando em cima da HVM2, e a promessa de paralelismo automático: escreva código sequencial, o runtime distribui em todos os cores e até na GPU, sem thread, sem lock, sem mutex.

O lançamento foi viral. Quase mil pontos no Hacker News, mais de 20 mil estrelas no GitHub, vídeo do Fireship. E aí veio a realidade: a thread do HN foi impiedosa. Números de 24 bits, sem FFI, soma simples levando 42 minutos na máquina de um usuário, C++ em um core batendo a RTX 4090 do demo. O próprio Taelin admitiu na época que o codegen era ruim, e admitiu agora, na thread do Bend 2, que o hype de 2024 não converteu em uso: “there is also my own failure into making the language actually be used, rather than just a viral moment”.

O Bend 2 é a resposta pra isso. E atenção: é outra linguagem. O README é explícito que programas de Bend 1 não carregam. Saiu a avaliação por grafos de interação (a HVM); entrou compilação nativa pra um único arquivo C, com clang pra CPU e Metal ou CUDA pra GPU. Os números passam a ser Nat, U32 e F32 de verdade, e o limite de memória pulou de 2 GB pra 8 TB, segundo o anúncio japonês da gihyo. As redes de interação continuam na arquitetura, mas, nas palavras dele, “inets live in it architecturally, but they don’t exist at runtime”.

O que o Bend 2 promete

O pitch novo agora gira em torno de IA. A página do projeto vende uma visão “post-AGI”: humanos vão parar de escrever e ler código, então precisamos de um jeito sem ambiguidade de dizer pras IAs o que queremos. A solução do Bend é dividir o programa em dois arquivos:

• LAWS.bend: as invariantes do sistema, escritas pelo humano.
• PROOF.bend: as provas dessas leis, escritas pela IA.

O type checker do Bend é um verificador de provas, na linha do Lean e do Rocq, então bend PROOF.bend vira um portão de commit: se a prova não fecha, o código não entra. O demo do site é um joguinho com a lei “vencer é impossível” e um convite direto: “Skeptical? Try breaking the game”. O posicionamento é explícito: LAWS.bend é um AGENTS.md com respaldo matemático.

E como é a cara disso? A sintaxe lembra Python com tipos dependentes. Um programa completo com efeitos:

import Base

# Performs effects on the CPU.
def main() -> IO(Unit):
  do IO<Unit>:
    name : String <- IO.try(String, IO.get_env("USER"))
    IO.print("Hello, " ++ name)

O paralelismo é divide-and-conquer: você quebra o trabalho em dois e o runtime espalha pelos cores que encontrar. E o operador ! despacha a função pra GPU:

# Computes 2^d in parallel: a tree of d levels, one leaf per unit.
def pow2(+d: Nat) -> U32:
  match d:
    case 0n:
      1
    case 1n+p:
      a b = pow2(p) pow2(p)
      (a + b : U32)

# Runs pow2 on the GPU, via `!`.
def main() -> IO(Unit):
  result = pow2!(20n)
  IO.print(U32.show(result))

Repara nas diferenças pras linguagens mainstream: não existe if (todo branch é um match em True/False), números naturais se casam por padrão de sucessor (1n+p), e o +d marca o parâmetro como afim, que é o que permite a linguagem viver sem garbage collector.

E as provas são defs comuns. A lei declara o que vale; a prova é indução com reescritas explícitas:

# CLAIM: for every nat x, x + 0 equals x.
law add_zero:
  for x: Nat
  {Nat.add(x, 0n) == x : Nat}

# PROOF: induction on `x`, one rewrite (`%`) per step.
def add_zero(x):
  match x:
    case 0n:
      {==}
    case 1n+xp:
      %add_zero(xp) : {1n+Nat.add(xp, 0n) == 1n+_ : Nat}
      {==}

Sem táticas, sem inferência, tudo anotado à mão. É verbose de propósito: é o preço do checker de 0,1s.

As outras promessas, todas com benchmark na página:

• Roda rápido: Game of Life num M4 Max em 7,8s em um core, contra 6,78s do C. Na GPU, 0,06s, ou 124x.
• Verifica rápido: 3.200 instanciações genéricas checadas em 0,38s, contra 19,2s do Lean e 6,04s do Rocq. A ideia é que o agente possa verificar a cada edição.
• Paraleliza sozinho: operador ! manda a função pra GPU, sem thread, sem lock, sem kernel escrito à mão.
• Sem garbage collector: tipos afins, cada closure pode ser chamada no máximo uma vez, então a memória se resolve estaticamente.

Dois detalhes honestos que eu gostei de ver publicados: o próprio site avisa “Bend is still evolving. Expect bugs”, e o Taelin declarou que o compilador é 99% escrito por IA, com só o kernel de checagem auditado por humanos. Coerente com a tese dele, pelo menos.

E já existe um plano de negócio: o Bender, um “proving agent” pago e proprietário, harness em cima dos modelos da Anthropic e da OpenAI hoje, com modelo dedicado e provador simbólico próprio no roadmap.

Nem todo mundo engoliu os benchmarks

A recepção técnica teve ressalvas fortes, e elas importam. O gist do Nezk, “Why the benchmarks of Bend’s 2 typechecker are misleading (and possible problems with its type system)”, aponta que o Bend pula elaboração, unificação e argumentos implícitos, que é justamente onde Lean e Rocq gastam tempo. Comparar os tempos assim seria comparar maçã com foguete.

Mais pesado: o post do Liam Powell, “Bend 2 and the Vibe-Coding Trap”, nota que a expressão “formal verification” não aparece no site nem no código do Bend, refaz o demo do jogo em SPARK/Ada provando as mesmas duas propriedades automaticamente com GNATprove (“all checks proved (12 checks)”), sem as 442 linhas de prova manual, e conclui que o Bend está “decades behind the state of the art”.

São críticas de gente que entende do assunto e merecem resposta. Dito isso, a thread principal do Bend 2 no HN está com mais de 600 pontos, então atenção o projeto tem.

O que eu testei

Slogan não compila programa, então eu fui testar. Tenho um repositório bend-tests onde apontei meus agentes pra portar projetos reais meus, escritos em Rust, pra Bend 2 (v2.0.16, pinada via mise; pra ter noção da maturidade, a linguagem teve nove releases em dez horas no GitHub, no dia seguinte ao lançamento). A documentação do experimento inteiro está em docs/ lá dentro, e é dela que saem as próximas seções.

Os três candidatos

Escolhi três projetos meus com perfis diferentes. Já aviso: nenhum dos três é um exemplo digno de Bend, e eu sei disso. Eu só peguei projetos pequenos e simples que eu tinha à mão, meio aleatórios, pra ver onde a linguagem quebra quando esfregam nela código comum do dia a dia.

O ghpending é minha CLI que lista issues e PRs abertos dos meus repositórios via GraphQL. O port cobre o comando principal, os filtros, a ordenação e o config.toml, com saída verificada byte a byte idêntica ao binário Rust nos casos testados contra a API real do GitHub (no meu config cheio, a única diferença é a fork view que o port deixou de fora).

O tclock é meu fork do clock-tui, relógio de terminal com timer e cronômetro. O port cobre relógio, timer e stopwatch, sem o sistema de widgets (que sozinho é 2.075 linhas do Rust), verificado dirigindo o binário via pty.

O ai-jail, meu sandbox pra agentes de IA (bubblewrap, Landlock, seccomp), nem virou código: a avaliação no papel já matou. Um port seria um programa em C com um main em Bend, o que anula o propósito. E olha que ele tinha a parte mais interessante pra provar: a lógica de política, tipo “resolução de path nunca escapa da raiz”. Mas não tem como embutir isso no binário Rust, então ficou pra uma próxima.

Os números

Medi Rust e Bend lado a lado nos dois ports:

Lê essa tabela com cuidado, porque ela engana. As runs são bound de rede. O gap dos 43 repos é o Rust fazendo mais trabalho (fork lookups, query sequencial de viewer). O tclock do Bend redesenha frames inteiros, 26 KB/s contra 2 KB/s de diffs do ratatui. E a contagem menor de linhas é em parte porque o port faz menos. Nenhum número aqui mostra o Bend mais rápido que o Rust no mesmo trabalho.

As provas na prática

Aqui mora a parte que o Rust não consegue imitar, então vale o detalhe. O design que funcionou foi provar uma guarda isolada, deixando o algoritmo fora da prova. O alocador de --limit do ghpending ficou em dois estágios: o primeiro é o algoritmo original em U32, não provado; o segundo é uma guarda em Nat que recebe a proposta do primeiro e corta qualquer excesso. As leis dizem que o orçamento é conservado e que nenhum repo recebe mais itens do que tem.

Essa é a guarda de verdade, do alloc.bend do port:

# the lesser of b and w
def take(b: Nat, w: Nat) -> Nat:
  match b w:
    case 0n w0:
      0n
    case 1n+bp 0n:
      0n
    case 1n+bp 1n+wp:
      1n+take(bp, wp)

# what is left of b once w is taken from it
def rest(b: Nat, w: Nat) -> Nat:
  match b w:
    case 0n w0:
      0n
    case 1n+bp 0n:
      1n+bp
    case 1n+bp 1n+wp:
      rest(bp, wp)

A lei vale mesmo se o estágio não provado propor lixo. A guarda não confia na aritmética que ela não consegue enxergar. Esse é o padrão que faz prova funcionar em código real.

O teste de mutação é a medida honesta do negócio. Injetei um off-by-one na guarda que vaza orçamento: as três saídas de exemplo ficaram idênticas, então uma suíte de testes daquele tamanho teria aprovado. O portão de prova rejeitou, com o termo exato que deixou de bater. É o Bend funcionando como prometido, no detalhe.

Agora o preço: 93 linhas de leis e provas pra garantir dois fatos simples sobre uma guarda de umas 30 linhas, começando do zero, porque a Base não traz nenhum lema de Nat (os únicos lemas aritméticos são U32.add_comm e Word.add_comm, que não ajudam em prova de Nat; tivemos que provar associatividade da soma na mão, e o Taelin reconheceu na thread: “We need a mathlib!”).

E o que ficou de fora da prova: a exatidão do algoritmo (precisaria de lemas de divisão, dias de trabalho), tudo que é U32 (por baixo é um vetor de 32 bits; provar aritmética nele sem biblioteca de lemas é impraticável) e literalmente todo o resto do programa: JSON, ordenação, renderização, IO. A superfície provável de um programa como o ghpending é uns poucos por cento do código.

O checker, por outro lado, é a melhor parte da ferramenta: 0,1s por rodada, erro apontando uma linha exata. Foram umas 30 rodadas de check no ghpending. Pra um agente iterando em loop, é exatamente o formato de feedback que ele precisa.

O preço de sair pra C

Tudo que a Base não tem vira foreign effect: um def em Bend cujo corpo é uma função C (pro binário nativo) e uma gêmea em JS (pro runner de desenvolvimento). Os dois ports precisaram de oito efeitos escritos à mão:

• Http.post: porque não existe TLS, HTTP ou DNS (o demo oficial de HTTP hard-coda um IP).
• Clock.unix e Clock.local: porque IO.now é milissegundos desde o boot, sem hora de parede e sem fuso.
• Tty.width, Tty.raw, Tty.key, Tty.size: porque não existe stdin, raw mode nem consulta de terminal. Nada disso existe.
• Clock.millis: conveniência.

E o guia oficial é claro sobre o compromisso: não há promessa de ABI. Os nomes são internos do runtime e qualquer release pode renomeá-los, então “rebuild your effects with every update”. Numa linguagem com nove releases em dez horas, boa sorte. Detalhes que completam o quadro: não existe flag pra linkar biblioteca extra (o ghpending usa um wrapper de $CC que injeta -lcurl), tipos de handle customizados são WONTFIX, e incluir header de C no meio do arquivo funcionou por sorte, porque o runtime define nomes curtos tipo lock e u32.

Aqui encaixa o ponto conceitual: no momento em que você cruza a fronteira do FFI, a prova ficou pra trás. O verificador garante o que está dentro do modelo dele; o código C do outro lado é ato de fé. O Rust tem exatamente o mesmo problema com unsafe, onde as garantias do borrow checker valem até a borda do bloco e dentro dele a prova é sua. Se você quer garantia forte de ponta a ponta, a fronteira com C precisa ser mínima ou inexistente, e hoje em Bend ela é enorme pra qualquer programa real.

Onde o Bend encaixa

Cruzando os três projetos com o que a linguagem oferece, o formato que ganha é um núcleo puro pequeno, com spec afiada que testes cobrem mal, dentro de uma casca fina de efeitos:

• alocadores, schedulers, rate limiters, lógica de quota
• regras determinísticas de jogo ou simulação, principalmente com rollback netcode (o único domínio onde a Base já tem o necessário: UDP, janela, áudio)
• máquinas de estado de consenso, ledger e matching engine
• parsers e codecs com lei de round-trip
• funções de merge de CRDT (comutativas, associativas, idempotentes)
• avaliadores de política de acesso (tipo o do ai-jail)

E o centro de design que os autores declaram: a IA escreve o código e as provas, o humano escreve só o LAWS.bend, e o checker arbitra. A descrição honesta mais curta que eu achei: uma proof-carrying language for AI-written kernels. Comparado com Lean ou Coq, que provam bem e entregam aplicação mal, o Bend é muito mais executável.

Uma coisa que me surpreendeu nos próprios números: de primeira eu assumiria que o nicho natural era pesquisa acadêmica em matemática. É o contrário. Pra matemática ele perde feio pra Lean 4, Coq e Isabelle: sem táticas, quase sem inferência, sem nada na escala da mathlib, sem reais, e com uma fundação (Type : Type, sem positivity check) que deixaria matemático de cabelo em pé. O que ele faz é verificação de software, mais perto de Dafny, F* ou Liquid Haskell do que de assistente de prova.

Duas limitações pesam até nesse nicho: o Bend emite um programa inteiro em vez de uma biblioteca, então o núcleo provado não pode ser linkado numa aplicação Rust hoje; e o custo de prova sem biblioteca de lemas é alto.

O que mudaria o veredito

Registrado no use-cases.md, a lista do que me faria reavaliar:

• saída de biblioteca com ABI C, pra um núcleo provado viver dentro de um programa Rust ou C
• U64/I64 e F64
• uma biblioteca de lemas pra Nat, listas e ordem
• stdin, subprocessos, TLS e JSON na Base, ou um hub de pacotes que tenha isso
• builds nativos incrementais ou mais rápidos (62s pra 1.000 linhas hoje)
• uma ABI de efeitos que sobreviva a um release

A realidade nua e crua

Agora a minha leitura, e você já sabe que eu não adoço.

É uma linguagem recém-nascida. Foi lançada anteontem. Fora o repo da própria linguagem, uma busca no GitHub acha hoje só algumas dezenas de spikes de 48 horas, quase todos com zero estrelas, nada que pareça projeto de verdade. As 21 mil estrelas do repo são quase todas herança do Bend 1, o repo foi renomeado. Os demos do site são todos de brinquedo: joguinho, Game of Life, pow2. São demonstrações de possibilidade, ainda sem uso real.

A stdlib precisa crescer uma ordem de magnitude. A força de uma linguagem mora na biblioteca padrão e no ecossistema. A única exceção histórica a essa regra foi o JavaScript, e aquilo lá é uma lata de vermes que não cabe neste artigo.

Falta a killer app. Toda linguagem que vingou tinha uma. Os meus testes apontam o nicho (núcleos puros provados, escritos por IA), mas alguém precisa transformar isso num app que o mundo queira usar. E aqui entra uma sugestão concreta, de graça: o Taelin podia escolher software open source popular que ele acha que ficaria melhor em Bend e reescrever. O Taelin é o exato oposto do mantenedor teimoso que torce o nariz pra IA: ele desenhou a linguagem inteira em volta de IA. Então que use isso a favor: pega um ripgrep, um jq, um sqlite da vida, reescreve com IA em Bend e publica a comparação lado a lado. Performance, linhas de código, e principalmente o que as provas garantem que o original não garante. Um before/after assim no mundo real vale mais que mil demos de joguinho. E de brinde, cada rewrite desses devolve o feedback mais valioso que existe: quais buracos da stdlib doeram de verdade num projeto real. Nada prioriza melhor o que implementar na próxima versão do que código de verdade esbarrando no que falta.

Não espere webapp, mobile ou qualquer coisa do dia a dia tão cedo. Talvez nem seja o propósito, e tudo bem também. Mas a promessa de “velocidade de C” corta pra outro lado: se o diferencial é performance, é mais fácil ir direto pro C, ainda mais hoje, com LLM escrevendo o código por você.

E aqui entra a minha situação concreta. Eu uso Rust pra caramba. Odeio a sintaxe, acho a ergonomia sofrível. Mas como quem escreve o código é o LLM e eu não preciso lidar com aquilo na mão, eu tolero, e em troca levo performance, garantias boas o suficiente e um ecossistema gigantesco de crates e frameworks. Ecossistema. É isso que decide.

Eu não escolho linguagem pela elegância do paper. Escolho pelo tamanho do ecossistema que eu não preciso escrever na mão.

O foco em prova e GPU, e a dúvida que fica

Uma coisa que me incomodou de leve o tempo inteiro: o Taelin claramente concentra tudo em dois pilares, provas e GPU, e eu não tinha certeza do que isso significava pro escopo da linguagem. Fui ler o que ele mesmo disse no thread de pré-lançamento e no HN, e a história é mais interessante do que eu assumi.

O pilar GPU é a herança de pesquisa. São dez anos de interaction nets e redução ótima, da HVM até aqui. Mas tem uma nuance que me surpreendeu: o Bend 2 conscientemente trai o idealismo acadêmico dele. Nas palavras do próprio: “Bend2 is designed to be practical, not idealistic”, mais perto de C do que de Haskell, porque ele não conseguiu fazer as interaction nets baterem as variantes lower-order em hardware comum. A GPU ficou como aplicação prática da obsessão, sem virar fetiche.

O pilar prova é mais velho que a era LLM: vem da época da Ethereum Foundation, de contrato imutável segurando milhões com bug, que gerou o Formality. A era LLM só deu pra obsessão antiga uma roupagem de mercado: “the same capabilities that proved Navier-Stokes will now be writing real proofs that your own apps are correct”.

E aí vem a minha hipótese que não sobreviveu à pesquisa. Eu estava pronto pra escrever que a stdlib mínima talvez fosse de propósito, que a ideia nunca foi programação geral, e que a minha crítica ao deserto de bibliotecas estaria mirando o alvo errado. Errado eu. As palavras dele são de ambição geral mesmo: “the potential to become the most sensible choice for any vibe-coded project”, “Bend is made for the general public”, e o time “working hard to […] make this language competitive with the mature alternatives in the market”. A única magreza deliberada é a do checker, sem inferência, verbose de propósito. A Base pequena é dia dois de vida mesmo, tanto que ele próprio pede uma mathlib.

Isso faz a minha crítica à stdlib morder ainda mais forte: se o objetivo declarado é ser a escolha pra qualquer projeto vibe-coded, a comparação com ecossistemas maduros é o jogo que ele mesmo escolheu jogar.

E tem o ângulo do negócio, que ele admite com uma franqueza rara: “we ship without a product”. A linguagem é o substrato gratuito; o vendável é o Bender e a infraestrutura de prova que vem atrás. Vale ficar de olho nesse espaço.

A dúvida que sobra, e essa eu registro sem resposta: a ambição generalista é o norte dele, mas a realidade que eu medi empurra o Bend pro nicho de núcleos verificados escritos por IA. Qual dos dois vence, só o tempo diz.

O recado final

Se eu pudesse dar um conselho pro Taelin, seria esse: a parte difícil, a pesquisa, ele já fez. Agora vem a parte menos glamourosa, que é a que decide se linguagem vive ou morre: marketing e construção de ecossistema. Adoção, material de ensino, killer app, stdlib, mathlib. Ir muito além de toys e demos.

O exemplo que me vem à cabeça é o Zig. Anos de estrada e ainda briga por adoção, mesmo tendo uso prático imediato: o zig cc sozinho já é um substituto trivial pra compilar C, sem usar nada da linguagem. Tem app real usando, o Ghostty do Mitchell Hashimoto é o caso famoso. Mas o Andrew Kelley, o autor, é uma figura notoriamente difícil, da turma que torce o nariz pra IA, e claramente não entende de construção de ecossistema, e isso segura o Zig pra trás. Perfeccionismo técnico não combina com marketing e adoção.

O Bend 2 tem potencial de verdade. Checker instantâneo, provas pegando bug que teste não pega, paralelismo sem cerimônia. Mas potencial sozinho não significa nada se a adoção não vier. Eu torço pra vir, e torço duplo por ser um brasileiro liderando.

E uma provocação final, dessa vez pra você que leu até aqui. Stdlib rala, zero frameworks, zero bibliotecas de terceiros, nenhuma killer app: tudo isso deixa de ser problema quando você olha de outro ângulo e vira mapa de oportunidade. Cada coisa que falta no Bend é uma coisa que alguém vai ter que escrever, e quem chegar primeiro grava o nome na história do projeto. Se você sempre quis contribuir com open source de impacto mas nunca achou espaço nos projetos maduros, onde já existe de tudo, aqui tem um terreno vazio esperando.

São os meus dois centavos. Não levem tão a sério.

O que eu mais gostei no post do Jarred foi o nível de detalhe. Ele não vendeu a fantasia idiota de escrever um prompt tipo “rewrite Bun in Rust” e esperar milagre. Pelo contrário. O que ele descreveu foi procedimento: PORTING.md, análise de lifetimes, LIFETIMES.tsv, trial run com três arquivos, workflows dinâmicos, revisores adversariais, correção de processo quando os agentes começaram a fazer besteira com git stash, depois compiler errors virando fila de trabalho, depois smoke tests, depois suíte inteira, depois CI multi-plataforma. Nada de vibe coding irresponsável. Engenharia usando IA como multiplicador.

Por isso fiquei decepcionado com a resposta do Andrew Kelley, “My Thoughts on the Bun Rust Rewrite”. Andrew é o criador do Zig. Eu queria ler o melhor argumento técnico possível defendendo Zig. Queria ver ele explicar onde Bun confundiu problema de linguagem com problema de arquitetura. Queria ver quais APIs Zig poderiam ter ajudado, quais invariantes deveriam ter sido endurecidas, onde comptime, allocators, arenas, errdefer, DebugAllocator e o novo desenho de I/O do Zig poderiam mudar a análise.

Em vez disso, uma parte grande do texto vira tentativa de assassinato de reputação. Comentário sobre personalidade, gestão, VC, cultura de startup, fofoca de bastidor. Pode até haver mágoa real ali. Não me interessa. Não ajuda tecnicamente.

Então resolvi fazer o exercício que eu esperava ter lido: colocar Claude Fable 5 e GPT 5.6 Sol como árbitros técnicos e pedir a eles a resposta que Andrew deveria ter escrito. Não a resposta gentil. Não a resposta de torcida. A resposta técnica.

Antes de passar a palavra, um off-topic. Se você, como eu, ficou olhando aquelas animações bonitas do GitHub no post do Bun e pensou “eu quero isso nos meus projetos”, eu fui lá e fiz. O github-visualize é um dashboard self-hosted que acompanha seus repositórios e reproduz a evolução dos commits, o heatmap por hora e a corrida do CI até ficar verde. Está tudo aberto no GitHub.

Mas agora vamos separar apoio de prova. Uma coisa é dizer “eu teria feito algo parecido”. Outra é dizer “era tecnicamente impossível continuar em Zig”. Para responder isso, precisamos olhar para causas: quais bugs eram realmente bugs de linguagem, quais eram problemas de arquitetura, quais eram custos de ecossistema, e quais poderiam ter sido reduzidos com uma disciplina diferente dentro do próprio Zig.

É daí que começa a análise.

Antes, vocabulário mínimo. Use-after-free é usar memória depois de liberá-la. Double-free é liberar a mesma memória duas vezes. Leak é esquecer de liberar. Ownership é quem é responsável por destruir um recurso. Lifetime é por quanto tempo uma referência continua válida. FFI é a fronteira onde Rust ou Zig chamam C/C++ e perdem parte das garantias da linguagem. GC root é uma forma de dizer ao coletor de lixo: “não colete este objeto ainda”. Pinning é segurar um buffer no lugar para ele não ser movido, destacado ou invalidado enquanto alguém ainda tem um ponteiro para ele. Reentrância é quando uma chamada volta para dentro do runtime antes da chamada anterior terminar.

O que o Rust compra de verdade

A tese mais forte do post do Bun é simples: uma porcentagem grande dos bugs listados era use-after-free, double-free ou recurso esquecido em caminho de erro. Em Rust seguro, boa parte disso vira erro de compilador ou cleanup automático por Drop, desde que o recurso esteja modelado como valor dono. Rust não prova ausência geral de vazamentos: ciclos de Rc, mem::forget, Box::leak e abort ainda existem. Mas ele torna o vazamento acidental em caminho de erro muito mais difícil.

Isso está correto. E é um argumento forte.

O ponto forte do Rust aqui não é magia. É que ele obriga certas relações de posse e vida útil a aparecerem no tipo, em vez de ficarem espalhadas como convenção. Quando um valor tem dono, quando ele é movido, quando ele sai de escopo, quando um destrutor roda, isso deixa de ser só acordo entre programadores. O compilador participa.

No código atual do Bun, dá pra ver o padrão em miniatura. Um wrapper de bytes do MySQL guarda um valor do JavaScriptCore pinado, e o Drop desfaz o pin quando o objeto morre:

impl Drop for Bytes {
    fn drop(&mut self) {
        if !self.pinned.is_empty() {
            // `pinned` is rooted by the caller's MarkedArgumentBuffer for the
            // lifetime of this Value (see struct doc); the FFI itself is `safe fn`.
            JSC__JSValue__unpinArrayBuffer(self.pinned);
        }
        // self.slice dropped automatically
    }
}

Fonte: src/sql_jsc/mysql/MySQLValue.rs. O detalhe importante não é a chamada FFI em si. É o cleanup acompanhar o dono do valor.

Esse é o round que Rust ganha limpo. Em um projeto pequeno, disciplina basta. Em meio milhão de linhas, com callback reentrante, threadpool, libuv, sockets, TLS, JavaScriptCore, parser, bundler, package manager e API Node, disciplina vira custo recorrente.

Rust provavelmente reduziu o espaço de estados inválidos que o time precisava manter na cabeça. Vitória real.

Mas vitória real não significa vitória total.

Zig não estava indefeso

O argumento mais fraco que se pode fazer contra Zig é fingir que ele é C com sintaxe nova. Não é. Zig tem mecanismos explícitos para tratar exatamente parte desses problemas.

O mais óbvio é errdefer, o mecanismo idiomático para cleanup em caminho de erro:

fn readThing(alloc: std.mem.Allocator, fail: bool) ![]u8 {
    const buf = try alloc.alloc(u8, 16);
    errdefer alloc.free(buf);

    if (fail) return error.Boom;
    return buf;
}

test "leak em caminho de erro" {
    const alloc = std.testing.allocator;
    try std.testing.expectError(error.Boom, readThing(alloc, true));
}

O std.testing.allocator reporta vazamentos em testes. O DebugAllocator ajuda a encontrar double-free, leaks e vários usos inválidos de memória, inclusive tornando bugs mais barulhentos por não reutilizar endereços imediatamente. Isso não é a mesma coisa que prova estática de ausência de use-after-free. Não é borrow checker. Não cobre alocação feita dentro de C++, JavaScriptCore, BoringSSL ou qualquer outro allocator externo. Só pega o que passa por ele e só nos caminhos exercitados pelos testes.

O comentário do próprio allocator é preciso sobre o que ele entrega:

//! * Captures stack traces on allocation, free, and optionally resize.
//! * Double free detection, which prints all three traces (first alloc, first
//!   free, second free).
//! * Leak detection, with stack traces.
//! * Never reuses memory addresses, making it easier for Zig to detect branch
//!   on undefined values in case of dangling pointers.

Fonte: debug_allocator.zig. É ferramenta boa de teste e debug. Não é um teorema.

Mesmo assim, é errado dizer que Zig não tinha ferramenta nenhuma. Tinha.

A diferença é o momento do feedback. Em Rust, muita coisa aparece na compilação. Em Zig, muita coisa aparece em teste, fuzzing, allocator instrumentado, ASAN, revisão e estilo arquitetural. Em código crítico, isso importa. Feedback cedo é melhor.

Mas também importa dizer a frase inteira: se o problema era falta de invariantes claras no código Zig, a resposta poderia ter sido uma reescrita em Rust. Também poderia ter sido uma reestruturação agressiva do Zig.

Não sabemos qual teria sido mais barato. Só sabemos qual o Bun escolheu.

Drop não é só açúcar, mas também não é milagre

O post do Bun acerta ao contrastar defer com Drop.

Em Zig, você escreve:

var resource = try Resource.init(allocator);
defer resource.deinit();

Isso é explícito. Está na sua cara. Não há fluxo de controle escondido. Essa é a filosofia do Zig: se algo acontece, você deve conseguir apontar para o lugar onde acontece.

Em Rust, se o tipo implementa Drop, o cleanup acompanha o dono:

impl Drop for Resource {
    fn drop(&mut self) {
        self.deinit();
    }
}

Isso não é apenas açúcar sintático. As regras de destruição do Rust ligam Drop a ownership, move semantics, ordem de destruição de campos e unwind de panic. Código seguro comum não consegue usar um valor depois de movido, nem dar double-drop no objeto como se ainda fosse dono dele. É uma garantia de linguagem.

Mas a garantia termina onde começa a semântica que o compilador não entende.

Se o drop chama uma função FFI para desproteger um valor do JavaScriptCore, o Rust garante que o destrutor vai rodar nos caminhos normais de escopo e drop, não em abort, mem::forget, leaks intencionais ou ciclos de Rc. Ele não prova que o ponteiro do JSC ainda é válido. Não prova que o GC não tem uma regra especial. Não prova que uma callback assíncrona de C não vai chamar de volta depois que você destruiu o wrapper.

O comentário no mesmo wrapper do Bun mostra o tamanho do contrato que ainda fica fora do compilador:

/// JS could `transfer()`/detach an earlier ArrayBuffer, or drop the last
/// JS reference to it and force GC, while we still hold a borrowed slice
/// into it. Pinning the backing `ArrayBuffer` makes it non-detachable for
/// the duration, and the caller's stack-scoped `MarkedArgumentBuffer`
/// roots the wrapper so GC can't sweep the cell. `Drop` unpins.
pub struct Bytes {
    pub slice: ZigStringSlice,

Fonte: MySQLValue.rs. Repara no tamanho do contrato. Ele não sumiu por ser Rust. Ficou documentado e encapsulado.

Essa é a fronteira real: Rust melhora o lado Rust do contrato. Ele não faz mágica dentro do heap do JavaScriptCore.

A fronteira FFI continua sendo o inferno

Bun não é uma CLI simples. Bun é runtime JavaScript. Ele conversa com JavaScriptCore, uWebSockets, usockets, BoringSSL, SQLite, bibliotecas de compressão, APIs de sistema, handles assíncronos, buffers que podem ser destacados por JavaScript no meio de uma coerção, callbacks reentrantes e GC conservador.

É aí que o debate fica interessante.

Dentro de um bloco unsafe, Rust exige disciplina. O próprio Rustonomicon sobre FFI trata chamada estrangeira e ponteiro cru como obrigações do programador. Se o binding estiver mentindo, se a ownership real não bater com o tipo, se a callback estrangeira sobreviver ao objeto Rust, o compilador não salva.

O binding do Bun documenta as pré-condições na própria declaração:

unsafe extern "C" {
    /// By-value `JSValue`; C++ side null-checks and reads its own heap state.
    /// No caller-side preconditions → `safe fn`.
    safe fn JSC__JSValue__unpinArrayBuffer(v: JSValue);
    /// 0 = detached/null, 1 = FastTypedArray (GC-movable — caller should dupe;
    /// no unpin needed), 2 = pinned ArrayBuffer (caller must unpin).
}

Fonte: MySQLValue.rs. A linguagem permite declarar uma chamada estrangeira como segura. A obrigação de provar essa segurança continua sendo nossa.

Só que existe uma diferença importante: Rust permite encapsular esse unsafe atrás de APIs seguras. Você pode criar tipos de handle, NonNull, PhantomData, Pin, lifetimes marcando relação entre wrapper e runtime, wrappers que não implementam Send ou Sync, RAII para roots do GC, e uma superfície menor para auditoria. O objetivo não é zerar o perigo. É encolher o lugar onde o perigo mora.

O exemplo mais didático do post do Bun é o bug de uv_close. A primeira versão compilava, mas entregava um Box para libuv fechar assincronamente e deixava o Box cair no fim do escopo. Use-after-free seguido de double-free. A versão corrigida no código atual torna a transferência explícita:

spawn::WindowsStdioResult::Buffer(pipe) => {
    // `uv_close` is async — libuv keeps the raw handle pointer until the
    // next loop tick. Leak the Box so it outlives this scope; dropping it
    // here would be a use-after-free + double-free when the callback fires.
    Box::leak(pipe).close(Subprocess::on_pipe_close)
}

Fonte: js_bun_spawn_bindings.rs. Compilou em Rust e ainda estava errado na fronteira C/async. O processo de revisão pegou.

Aqui leak não significa “vazar para sempre”. Significa tirar o Box do controle lexical do Rust e transferir a posse para o protocolo assíncrono do libuv, cuja callback depois reconstitui e libera a alocação.

Zig também permite escrever wrappers bons. A diferença é que ele não tem a fronteira safe/unsafe como parte da linguagem. Em Zig, tudo é explícito e revisável. Em Rust, uma parte maior do contrato pode virar tipo.

Para um time grande, isso pesa. Pesa ainda mais quando parte do código está sendo gerada por agentes.

Arenas: sim, Bun já usava

Aqui o argumento pró-Zig precisa ser honesto. Arenas são idiomáticas e excelentes para certos problemas: parser, AST, ciclo de vida de uma requisição, dados que morrem juntos.

Mas o post do Bun não ignora arenas. Ele diz explicitamente que a abordagem existente já era uma mistura de lifetimes por arena, reference counting e “pay really close attention”. Inclusive cita parser state e AST nodes como bons casos para arena.

O trecho do post é esse:

Our current approach is a mix of:

- arena lifetimes, where the scope of when it's accessible is clear
  (parser state doesn't escape the calling function and so AST nodes
  are a good choice there)
- reference-counting
- pay really close attention

Fonte: post oficial do Bun. O contra-argumento bom não é “use arena”. Eles já usavam. O contra-argumento bom é perguntar se as fronteiras que sobraram poderiam ter sido endurecidas em Zig.

Então a resposta correta não é “vocês esqueceram arena”. Eles não esqueceram.

A resposta correta é: arena resolve o caso em que o lifetime é claro. Ela não resolve sozinha handle de socket que fecha assincronamente, callback que roda depois, SSL session que precisa de free específico, root do GC, ponteiro que pode ser invalidado por reentrância, nem objeto que cruza várias camadas de API com ownership implícito.

Arena é uma ferramenta boa. Não é religião.

Se o Bun tivesse endurecido mais as fronteiras em Zig, talvez parte do benefício do rewrite pudesse ter vindo daí: APIs mais restritas, menos ponteiro cru atravessando subsistema, handles com ownership explícito, allocators instrumentados por padrão em teste, fuzzing direcionado para reentrância, wrappers que obrigam deinit, menos “presta atenção”.

Mas isso também seria uma reescrita. Só que dentro de Zig.

O borrow checker ajuda, mas não onde a internet acha

Muita gente fala de borrow checker como se ele fosse um detector universal de bug. Não é. Borrow checker é o pedaço do compilador Rust que impede certos empréstimos inválidos: dois donos mutáveis ao mesmo tempo, referência viva depois do dono morrer, uso depois de move. É muita coisa. Não é tudo.

Ele não entende o heap do JavaScriptCore. Não entende todas as regras de GC. Não entende automaticamente que uma callback de C pode disparar JS, que pode destacar um ArrayBuffer, que pode reentrar no runtime, que pode invalidar um ponteiro capturado antes. Essas invariantes precisam ser modeladas.

Mas quando são modeladas, Rust cobra.

Um exemplo pequeno no Bun: wrapper de uSockets que transforma ponteiro C em borrow Rust amarrado a &mut self:

impl PacketBuffer {
    pub fn get_peer(&mut self, index: c_int) -> &mut sockaddr_storage {
        // SAFETY: uSockets guarantees a non-null, properly-aligned peer pointer for
        // indices < packet count. The returned storage lives inside the C-owned packet
        // buffer, which is exclusively loaned to the data callback for its duration; no
        // other Rust or C path holds a reference to it. The reborrow of `&mut self`
        // ties the returned lifetime to this handle, so the borrow checker prevents
        // obtaining a second overlapping `&mut` via `get_peer`/`get_payload`.
        unsafe { &mut *us_udp_packet_buffer_peer(self, index) }
    }
}

Fonte: src/uws_sys/udp.rs. O unsafe ainda existe. Mas, depois que o wrapper cria a referência, o borrow checker consegue impedir certos abusos no lado Rust.

E Bun não é só heap JavaScript. É parser, bundler, resolver de módulos, package manager, watcher de arquivos, protocolo HTTP, buffers, caches, tabelas, filas, estado de processo, glue code. Nessas partes, ownership local importa muito. Vec, String, slices, mapas, wrappers, enums, estados finitos: tudo isso fica mais fácil de refatorar com o compilador te batendo na mão.

O argumento honesto não é “borrow checker resolve Bun”. É: o borrow checker reduz muitas classes de erro no lado Rust do Bun, e isso libera atenção humana para a parte que continua difícil.

É forte o suficiente. Não precisa exagerar.

comptime: aqui Zig tem uma vantagem real

O melhor contra-exemplo técnico no próprio post do Bun é Output.pretty.

No Zig, a string de formato podia ser um parâmetro comptime. O próprio post do Bun coloca a diferença assim:

// Zig:
pub inline fn pretty(comptime fmt: string, args: anytype) void;
Output.pretty("<r>{f}<r>", .{hyperlink});

// Primeira API Rust:
pub fn pretty(payload: impl PrettyFmtInput);
Output::pretty(format_args!("<r>{}<r>", hyperlink));

Isso permitia processar marcadores de cor e formatação no literal conhecido em tempo de compilação, antes de misturar argumentos runtime. Ao portar para Rust, a primeira versão virou função. Resultado: o parser de tags mexeu em bytes que vinham dos argumentos. O issue #30693 mostra a regressão no port/canary envolvendo escape OSC 8 de hyperlink e <r>, não uma falha lançada em stable.

O bug era exatamente a contaminação entre template e argumento runtime:

TerminalHyperlink::Display emits an OSC 8 hyperlink:

\x1b]8;;URL\x1b\ai\x1b]8;;\x1b\

The closing string terminator ST is the final two bytes `\x1b\`.

This is then wrapped via `Output::pretty(format_args!("<r>{}<r>", hyperlink))`.
The rendered string tail is `...\x1b\<r>`.

Fonte: issue #30693.

Depois eles corrigiram usando macro.

O código atual deixa a diferença explícita:

/// Write to stdout with `<tag>` color expansion.
/// Function form: performs the `<tag>` → ANSI rewrite at runtime on the rendered
/// payload (using stdout's colour state). Prefer the `pretty!` macro for literal
/// templates so the rewrite happens at compile time.
#[inline(always)]
pub fn pretty(payload: impl PrettyFmtInput) {
    let buf = payload.into_pretty_buf(enable_ansi_colors_stdout());
    write_bytes(Destination::Stdout, &buf);
}

E logo abaixo:

/// Compile-time `<tag>` → ANSI escape rewriter.
///
/// This must be a proc-macro because it consumes a string literal and emits
/// a new string literal usable as a `format_args!` template.
///
/// `pretty_fmt!("<red>{s}<r>", true)`  → `"\x1b[31m{}\x1b[0m"`
/// `pretty_fmt!("<red>{s}<r>", false)` → `"{}"`
pub use bun_core_macros::pretty_fmt;

Fonte: src/bun_core/output.rs.

Isso demonstra uma força legítima do Zig: comptime é a própria linguagem rodando em tempo de compilação. Você não muda para um sistema paralelo. Em Rust, macros são poderosas e maduras, mas são outro mecanismo. Para alguns tipos de API, Zig é simplesmente mais direto.

Mas também não vamos transformar um bug de port em prova universal contra Rust. O problema ali não foi “Rust é frágil”. Foi a tradução errada de uma API comptime para uma função runtime. O próprio post do Bun reconhece isso e corrige com macro.

A leitura correta é mais simples: Zig tinha uma garantia estrutural ali. A primeira versão Rust perdeu essa garantia. Isso custou uma regressão no port/canary.

Ponto para Zig.

Tamanho de binário e performance: cuidado com causalidade barata

O post do Bun mostra números bons: binário menor, alguns benchmarks mais rápidos, startup melhor em certos cenários.

Os números do post:

Bun v1.4.0 (canary) — Windows — 76 MB
Bun v1.3.14          — Windows — 94 MB
Bun v1.4.0 (canary) — Linux   — 70 MB
Bun v1.3.14          — Linux   — 88 MB

Bun.serve  — 169.6k → 177.7k — +4.8%
node:http  — 103.8k → 108.5k — +4.5%
fastify    —  91.5k →  95.9k — +4.8%

Fonte: post oficial do Bun.

Eu acredito nos números. Não acredito em atribuição simples.

Reescrita muda muita coisa ao mesmo tempo. Muda layout de código, remove dívida, troca toolchain, mexe em LTO, muda como generics/comptime são instanciados, muda linker, muda código morto, muda ICU, muda organização interna. Quando tudo isso acontece junto, não dá para olhar o gráfico e dizer: “foi Rust”.

Também não dá para dizer: “foi só rewrite”.

O próprio post fala em combinação: Rust, mudanças em ICU, Identical Code Folding, LTO, codegen, limpeza acumulada. LTO é otimização no link final, quando o compilador enxerga mais do programa antes de gerar o binário. Identical Code Folding é o linker juntando funções idênticas em uma só. Andrew tem razão em lembrar que Zig também tem suporte a LTO e que parte desses ganhos poderia ter sido buscada antes. Mas isso não prova que o resultado seria igual. Só prova que a causalidade é mista.

O Cargo.toml do Bun mostra que há engenharia de build explícita nessa história:

# Cargo's defaults (lto=false, codegen-units=16) leave us at ~105 crates × 16
# CGUs ≈ 1680 separately-optimized units with NO cross-crate inlining beyond
# `#[inline]`-annotated leaf fns. `lto = "fat"` + `codegen-units = 1` collapses
# the whole Rust crate graph into one LLVM module, matching Zig's shape.
[profile.release]
lto = "fat"
codegen-units = 1
debug = "line-tables-only"
strip = "none"
panic = "abort"

Fonte: Cargo.toml.

E tem configuração de LTO atravessando Rust e C++:

/**
 * Cross-language LTO: rustc emits LLVM bitcode (`-Clinker-plugin-lto`) into
 * `libbun_rust.a` so the final lld `-flto=thin` link sees through Rust↔C++
 * call edges. When false but `lto` is true, both halves still LTO
 * independently (C++ via `-flto=thin`, Rust via `[profile.release] lto =
 * "fat"`); only the cross-language inlining is lost.
 */
crossLangLto: boolean;

Fonte: scripts/build/config.ts. Não é “Rust venceu”. É linguagem, toolchain, linker, configuração e código trabalhando juntos.

Mesma coisa para stack usage e profundidade de parser. O post atribui melhoria ao Rust emitir melhor llvm.lifetime.start/end e permitir reutilização de stack slots. Detalhe de codegen? Sim. Mas detalhe de codegen entregue pelo toolchain atual conta. O próprio Zig ainda tem uma issue aberta sobre stack allocations que não acabam no fim do escopo. Para o usuário, pouco importa se a vantagem vem da linguagem pura, do compilador ou da maturidade do backend. Importa que funciona hoje.

O mecanismo descrito pelo Bun é este:

Rust's LLVM IR codegen emits LLVM's llvm.lifetime.start and
llvm.lifetime.end intrinsics for stack variables when they are no longer
in use, which lets LLVM reuse stack space slots.

E o ticket do Zig diz, sem rodeio, que esse caso ainda não está resolvido:

Block stack allocations do not disappear at end of block scope #23475

Também existe a solução arquitetural: parser iterativo com stack explícita na heap. Funciona em Zig e Rust. Mas é outro trabalho.

Leitura honesta: os números favorecem a versão Rust do Bun naquele experimento. Eles não provam superioridade geral de linguagem.

Miri, crates e o mundo real

Há vantagens de Rust que não têm equivalente direto em Zig hoje.

Crates é a óbvia. O ecossistema Rust é grande, maduro e prático. Para um projeto do tamanho do Bun, biblioteca boa na prateleira vale engenharia real. Zig ainda está amadurecendo nesse ponto.

Miri também é vantagem real. Ele detecta classes de comportamento indefinido em código Rust executado: out-of-bounds, use-after-free, dados não inicializados, problemas de alinhamento, data races em certos casos. O próprio projeto documenta os limites: não é prova formal, avalia as execuções que você fornece e tem suporte restrito para FFI e APIs de plataforma. Não substitui teste. Mas para validar abstrações unsafe isoladas, é uma ferramenta que Zig não tem do mesmo jeito.

Bun não só cita Miri no abstrato. Ele está no toolchain:

[toolchain]
channel = "nightly-2026-05-06"
components = ["rust-src", "rustfmt", "clippy", "miri", "llvm-tools"]

Fonte: rust-toolchain.toml.

E tem teste interno explicando exatamente o uso:

// Run under Miri (`bun run rust:miri -p bun_ptr`): every path here walks raw
// pointers through `Box::into_raw` / `heap::take`, so Tree Borrows is what
// proves the ref/deref/destructor handoff does not alias or use-after-free.

Fonte: src/ptr/ref_count.rs. Não prova o programa inteiro. Exercita uma abstração perigosa sob um modelo feito para detectar comportamento indefinido nesses caminhos executados.

Há também contratação, tooling, documentação, IDE, cultura de revisão, CI, exemplos, gente no mercado. Isso não é detalhe político. É engenharia. Linguagem existe dentro de ecossistema.

Se o Bun fosse um projeto menor, com um time menor, menos pressão e menos superfície Node-compatible, talvez eu desse outro peso para isso. Mas Bun virou runtime usado por milhões de downloads mensais. A margem para “vamos manter disciplina perfeita” diminui.

Async: Zig talvez tenha uma resposta melhor, mas ainda não é o presente do Bun

Zig removeu async/await antigo e está redesenhando I/O em torno de std.Io, passado pelo chamador de modo parecido com Allocator. A ideia é boa: evitar o function coloring clássico, deixar a função menos acoplada a blocking, threaded ou event-driven, e tratar I/O como capacidade explícita.

O formato proposto é assim:

const std = @import("std");
const Io = std.Io;

fn saveData(io: Io, data: []const u8) !void {
    const file = try Io.Dir.cwd().createFile(io, "save.txt", .{});
    defer file.close(io);

    try file.writeAll(io, data);

    const out: Io.File = .stdout();
    try out.writeAll(io, "save complete");
}

Fonte: Kristoff sobre o novo async I/O do Zig. O io é uma capacidade passada explicitamente, como Allocator.

Eu gosto muito dessa direção.

Mas ela ainda está em transição. A issue de acompanhamento continua aberta: há protótipo, roadmap, discussão, partes entrando aos poucos. Não é uma base estável sobre a qual o Bun pudesse apostar hoje sem custo.

Então o argumento aqui não pode ser “Zig já resolveu”. A formulação correta é: Zig está caminhando para um desenho de async/I/O que pode ser mais limpo em alguns aspectos do que o modelo colorido tradicional. Mas Bun precisava tomar decisão com o que existe agora, não com o que promete existir depois.

Isso é sempre cruel com linguagens jovens. Mas é real.

O processo do rewrite importa mais que a linguagem

O melhor do post do Jarred não é Rust. É método.

O loop mental do post é literalmente isso:

// Pseudocode, not real code:
let task;
while ((task = todoList.pop())) {
  const result = task();
  const feedback = await Promise.all([review(result), review(result)]);
  await apply(feedback, result);
}

Depois, compiler errors viraram fila:

~16,000 compiler errors left

error: deref *mut EventLoop before field access
error[E0034]: multiple applicable items in scope
error: event_loop/EventLoopTimer.rs: port Timespec::ns from bun.zig

E o ciclo por crate era explícito:

- For each crate, run cargo check, group the output by file and save the errors to a file
- Fix all the compiler errors within that crate
- 2 adversarial reviewers for the crate's changes
- 1 fixer applies the fixes

Fonte: post oficial do Bun.

Ele não mandou Claude reescrever um runtime inteiro e foi dormir. Ele montou loops. Separou implementador de revisor. Usou contexto diferente para revisão adversarial. Fez trial run. Corrigiu o workflow quando os agentes começaram a se atropelar. Proibiu comandos perigosos. Dividiu worktrees. Transformou compiler errors em fila. Rodou a mesma suíte TypeScript porque a suíte não dependia da linguagem do runtime. Usou CI multi-plataforma como árbitro.

Essa é a parte que todo mundo deveria estudar.

O modelo não substituiu engenharia. O modelo executou trabalho dentro de um processo de engenharia. Quando o processo estava ruim, o resultado ficava ruim. Quando o processo melhorava, o resultado melhorava.

É o detalhe que a discussão tribal ignora. A história não é “Claude reescreveu Bun”. A história é “um engenheiro transformou uma migração gigante em vários loops verificáveis e usou Claude para acelerar cada loop”.

Muito mais interessante.

Então Zig falhou?

Não.

Zig não falhou por Bun ter escolhido Rust. Rust também não virou resposta universal porque Bun escolheu Rust.

O que a evidência pública mostra é mais chato: aquele código, naquele momento, estava caro demais para evoluir com o nível de confiança que o time queria. Rust comprou previsibilidade. Comprou feedback de compilador. Comprou ecossistema. Comprou um safe/unsafe boundary explícito. Comprou tooling. Comprou um ambiente em que agentes de IA conseguem bater em compiler errors e avançar mecanicamente.

Basta para justificar a decisão.

Mas não é suficiente para provar que Zig era tecnicamente inviável para Bun. Muitos problemas citados parecem também problemas de fronteira: ownership implícito, APIs permissivas demais, alocação sem contrato visível, recursos que cruzam camadas sem tipo carregando o dono, testes que talvez não capturavam invariantes difíceis, e o custo humano de revisar tudo isso.

Essas coisas poderiam ter sido atacadas em Zig. Talvez uma reestruturação agressiva do Zig tivesse resolvido muita coisa. Talvez não. Talvez custasse mais que o port. Talvez custasse menos, mas entregasse menos confiança. Não temos o contrafactual.

E é exatamente por isso que a conclusão precisa ser calibrada.

Eu apoio a decisão do Jarred como decisão de produto e engenharia. O post dele é um dos relatos mais úteis que já vi sobre rewrite grande assistido por IA. Mas gostar da decisão não me obriga a fingir que ela era a única conclusão técnica possível.

E tem um disclaimer importante. A Anthropic comprou o Bun em dezembro de 2025, e o próprio Jarred abre o post dizendo que ele e o time do Bun agora trabalham lá. A Anthropic vende Claude Code. Jarred tinha todo o incentivo institucional para usar o máximo possível de Claude e transformar essa reescrita numa demonstração pública do produto do novo empregador. Isso não prova má-fé, nem invalida um resultado técnico. Mas adiciona viés à decisão e à forma como o caso é apresentado. Ignorar esse conflito de incentivos seria tão ingênuo quanto ignorar a mágoa do Andrew com a saída do Bun de Zig.

A melhor leitura é menos dramática: Bun escolheu pagar um custo grande agora para reduzir custos recorrentes de manutenção depois. Rust foi uma escolha defensável, talvez ótima para aquele time naquele momento. Zig continuou sendo uma linguagem excelente, mas teria exigido outro tipo de reengenharia: mais invariantes explícitas, menos ownership informal, mais ferramentas ligadas por padrão, mais fronteiras endurecidas.

Andrew poderia ter escrito isso. Poderia ter defendido Zig no campo técnico. Poderia ter dito: “Rust comprou algumas garantias reais, mas boa parte do problema era arquitetura e processo; aqui está como Zig poderia ter atacado as mesmas causas.” Esse teria sido um post útil.

Não precisamos declarar vencedor. Linguagem não substitui arquitetura. Ela só muda quais erros ficam baratos de detectar e quais continuam dependendo de disciplina humana.

Bun escolheu trocar uma parte dessa disciplina por compilador. Eu acho uma boa aposta.

Não acho que isso enterre Zig.

Eu gosto dessa fase. O projeto deixa de ser “o que eu imaginei no meu setup” e vira “o que quebra na máquina de outra pessoa”. Aí aparece Windows, macOS, Arch, AUR, path esquisito, token salvo em lugar diferente, shell diferente, terminal diferente. Chato? Sim. Necessário? Também.

Mas o prato principal de hoje não é ai-jail nem ai-memory. É TUI. Mais especificamente, é minha mania recente de escrever pequenas ferramentas de terminal em Rust com Ratatui, mas querendo que elas fiquem com cara de Bubble Tea.

O app que não vou abrir

Nas últimas semanas também mexi num projeto privado que não pretendo abrir. É uma TUI pra acompanhar minha conta nos EUA, investimentos, assets, posições, covered calls, open calls, essas coisas chatas de adulto. Não vou publicar o código porque é o tipo de ferramenta que nasceu colada no meu fluxo financeiro, nas minhas planilhas, nos meus extratos e nas minhas gambiarras internas. Abrir isso seria transformar uma ferramenta minha em suporte gratuito pra bug de banco dos outros. Tô fora.

Mas dá pra mostrar a cara geral. Censurei o que precisava censurar:

Observação óbvia, mas vou deixar explícito: todos os valores, tickers, posições e datas mostrados no screenshot são dados falsos de demonstração. Não é dado real da minha conta, nem portfolio real, nem recomendação de investimento.

Toda vez que faço uma TUI pequena, a mesma dúvida aparece: que stack usar?

Se eu fosse escrever tudo na unha, provavelmente escolheria Python ou Go. São linguagens mais confortáveis pra esse tipo de utilitário pequeno. Python porque é direto, cheio de biblioteca, ótimo pra script que conversa com API e parseia JSON. Go porque gera binário simples, cruza plataforma bem, e tem ergonomia boa pra CLI.

Só que hoje eu raramente escrevo esse código todo na unha. Eu orquestro Claude, Codex, OpenCode, mando revisar, mando refatorar, mando testar. Nesse cenário, a falta de ergonomia do Rust pesa menos, porque quem briga com borrow checker, trait bound e lifetime chato é o LLM. Eu fico mais no papel de revisor e usuário final. E aí Rust começa a ficar muito atraente.

Ferramental bom. cargo é ótimo. Testes são fáceis de rodar. Cross compile é administrável. O binário final é limpo. Erro de memória idiota praticamente some. Não estou dizendo que Rust é magicamente melhor que Go ou Python pra toda TUI. Não é. Mas com LLM escrevendo a maior parte, o custo que normalmente me faria evitar Rust cai bastante. E os modelos atuais estão surpreendentemente competentes em Rust, desde que você mande rodar teste, consertar warning e não aceite a primeira versão como se fosse revelação divina.

Ratatui é bom, mas eu queria a cara do Charm

O Ratatui é uma biblioteca Rust pra construir interfaces ricas no terminal: dashboards, apps interativos, tabelas, listas, gauges, layouts, tudo aquilo que antigamente a gente chamava de “ncurses moderno”. Ele é o sucessor espiritual do tui-rs, e hoje é provavelmente o caminho mais óbvio se você quer fazer TUI séria em Rust.

Ratatui funciona bem. O problema é gosto pessoal: por padrão, não acho bonito. Não é feio no sentido “isso parece programa de DOS de 1993”. Dá pra fazer coisa boa. Mas muita TUI em Ratatui cai naquela estética quadrada, cinza, funcional, meio admin panel de datacenter.

Eu gosto mais da pegada da Charmbracelet. O gum, por exemplo, é uma coleção de comandos pra deixar shell script interativo sem virar festival de read -p e case. Prompt, select, filter, spinner, tabela, pager, estilo. Você monta um script bash com cara de app decente em minutos.

E tem o Bubble Tea, em Go, inspirado na arquitetura Elm. Você tem um model, recebe mensagens, atualiza estado, renderiza uma view. É uma ideia simples e muito boa pra terminal: estado entra, evento entra, view sai. A Charm também tem um gosto visual que eu curto: cores boas, espaçamento decente, componentes leves, nada com cara de formulário WinForms jogado no terminal.

Então eu queria o seguinte: continuar em Rust com Ratatui, mas roubar a sensação de Bubble Tea. Não o runtime inteiro. Não um clone perfeito. Só a direção visual e alguns componentes.

Daí nasceu o ratatui-bubbletea.

O projeto não substitui o Ratatui. Ele fica por cima. A ideia é oferecer uma camada de tema e componentes com inspiração em Bubble Tea/Bubbles, mas ainda renderizando com Ratatui.

Hoje ele é dividido em crates:

• ratatui-bubbletea-theme, com paleta, helpers e estilos compartilhados.
• ratatui-bubbletea-components, com componentes prontos como select list, spinner, progress, table, text input, viewport e help.
• ratatui-tea, opcional, pra quem quer uma ergonomia mais perto de Model, Msg e Cmd, sem fingir que Rust virou Go.

O README tem os exemplos completos e a documentação do que já existe. Por enquanto, eu trato como toolkit pequeno. Serve pra meus apps, e se servir pra mais alguém, ótimo. Se não servir, também não tem drama. O objetivo era parar de reimplementar o mesmo tema e os mesmos widgets toda vez que eu começava uma TUI nova.

ai-usagebar como exemplo público

Como não vou abrir o app financeiro, precisava de um exemplo público usando essa estética. Então atualizei meu ai-usagebar.

Pra quem não lembra, expliquei o projeto no post “Criei um Widget de Waybar pra Omarchy pra Monitorar Uso de Planos de LLM: ai-usagebar”. Ele nasceu como widget de Waybar pra mostrar uso de planos de LLM: Claude, OpenAI Codex/ChatGPT, Z.AI, OpenRouter. Bateu o olho na barra, sabe se está perto do limite e qual vendor usar agora.

Depois virou também TUI standalone. E graças a contribuições, hoje suporta Windows também. Isso é engraçado porque a origem dele é totalmente Linux/Omarchy/Waybar. Mas é open source: alguém usa em outro ambiente, encontra atrito, manda PR, e pronto, o projeto fica menos provinciano.

No ai-usagebar a diferença visual não muda a vida de ninguém. É uma tela simples. Abas, gauges, texto, atalhos. Mas é um bom exemplo porque é pequeno, real, testado, empacotado, e não depende do meu app privado. Dá pra olhar o código e ver como apliquei a camada de tema.

Os apps de coceira própria

Esses projetos todos seguem a mesma lógica: eu tenho uma coceira, faço uma ferramenta pequena, uso, ajusto, empacoto. Nada de roadmap de startup. Nada de manifesto. Só ferramenta que resolve um incômodo meu.

Um exemplo recente é o clock-tui. Ele não nasceu comigo. Era um projeto Rust antigo, tclock, que parecia abandonado. Eu queria um relógio grande no meu segundo monitor vertical. Aquele monitor fica do lado, e eu gosto de ter um “desk clock” enorme ocupando parte da tela. Usei o clock-tui original por um tempo.

Só que uma tela vertical inteira só pra mostrar hora é desperdício. Eu já tinha o ghpending, que lista issues e PRs abertos em todos os meus projetos. Ele é meu “tem alguém esperando resposta?” em formato de CLI. Também queria ver minha agenda.

Então fiz outro app pequeno: google-calendar-tui. Ele usa as contas Gmail já registradas no GNOME Online Accounts e resume meus próximos compromissos no terminal. Read-only. Sem ritual de OAuth novo. Sem mais um config secreto espalhado em lugar esquisito.

Com essas duas peças, modernizei o clock-tui e adicionei layout de widgets auto-refresh. Agora o relógio ocupa a tela como eu queria, mas em volta dele aparecem pendências do GitHub e agenda do Google Calendar.

Isso é exatamente o tipo de coisa que eu nunca faria se custasse um fim de semana inteiro. Mas com LLM, vira uma sequência de tarefas pequenas: lê o projeto antigo, moderniza dependências, roda teste, adiciona módulo de widget, chama ghpending, chama google-calendar-tui, organiza layout, corrige bug, empacota. Ainda dá trabalho. Mas é trabalho de supervisão e refinamento, não de ficar brigando com boilerplate.

Ajustando Geary sem fork

Outra coceira veio do GNOME.

Como eu queria centralizar minhas contas no GNOME Online Accounts, comecei a usar Geary e o calendário do GNOME no segundo monitor também. Gosto da ideia: contas configuradas uma vez, apps do desktop reaproveitando a mesma infraestrutura, nada de cada programinha inventar seu próprio login.

O problema é que o Geary tem um layout fixo de três colunas. Numa tela normal, tudo bem. Num monitor vertical, fica apertado. A coluna de pastas, a lista de mensagens e o corpo do e-mail brigam por espaço. Eu não queria manter um fork do Geary só pra esconder uma sidebar. Fork de app GTK grande é dívida. Você pisca e passa o resto da vida resolvendo conflito de merge.

Então fiz um módulo GTK: geary-hide-sidebar-module. Ele injeta um comportamento no Geary em runtime e permite recolher/expandir a sidebar, com atalho e auto-collapse em janela estreita. Sem recompilar Geary. Sem manter fork. Só um módulo pequeno com uma responsabilidade bem específica.

Essa é uma lição boa: às vezes você não precisa forkar a aplicação inteira. Dá pra ajustar por fora. GTK_MODULES existe. Wrapper existe. Config existe. CSS existe. Script existe. Nem toda personalização precisa virar uma manutenção eterna de código dos outros.

Código pequeno ficou barato

É por isso que estou insistindo tanto nessa ideia de apps pequenos. Com LLMs atuais, ficou muito fácil implementar uma ideia específica pra deixar seu ambiente do jeito que você quer. Sem esperar alguém ter exatamente a mesma dor. Sem ficar procurando no GitHub por três horas uma ferramenta que faz 80% do que você quer e 40% do que você não quer.

Você descreve a coceira, cria um repo, pede um protótipo, testa, manda refatorar, manda escrever teste, manda empacotar. Se ficar ruim, joga fora. Se ficar bom, instala e usa.

Eu não deixo isso virar gambiarra jogada no ~/bin sem dono. Meus apps têm testes. Têm builds automatizados. Muitos têm release no GitHub, pacote no AUR, instalação normal com yay no Arch. Usam paths XDG, então config vai pra ~/.config, cache vai pra ~/.cache, dados vão pra ~/.local/share. Fica organizado. Dá pra atualizar. Dá pra remover. Dá pra outra pessoa clonar e contribuir.

Pra fechar, os links todos num lugar só:

• ratatui-bubbletea
• ai-usagebar
• clock-tui
• ghpending
• google-calendar-tui
• geary-hide-sidebar-module
• ai-jail
• ai-memory

Se você usar algum deles e quebrar no seu setup, abre issue. Se souber corrigir, manda PR. Eu uso essas ferramentas de verdade, então bug report útil tende a virar correção rápido.

Minha regra prática é essa: personalize seu ambiente sem transformar tudo em gambiarra. Faça ferramenta pequena. Teste. Empacote. Documente. Deixe o LLM carregar o peso chato e use seu cérebro pra decidir o que presta.

Essa é a parte divertida de programar que tinha sumido um pouco. Agora voltou.

Há cinco dias eu escrevi um post longo sobre memória de agentes de código onde recomendei o agentmemory como solução. Depois de uma semana rodando ele em produção pessoal, voltei atrás. Esse post explica o que deu errado, e o projeto open source que comecei a construir pra resolver: o ai-memory.

Por que o agentmemory não rolou

O agentmemory tem as ideias certas (LLM Wiki do Karpathy, consolidação em tiers, hooks de captura automática, MCP) mas a implementação tem problemas estruturais que doem em uso diário. Os principais que peguei na prática:

• Reindexação do BM25 a cada restart. O índice persiste num arquivo (mem:index:bm25.bin) através de um KV remoto chamado iii-engine. Com poucas observações isso voa, mas passa de 10K observações e o state::set começa a dar timeout, o arquivo fica em ~96 bytes vazio, e cada restart paga ~5 minutos reconstruindo do zero (issue #309, aberta).
• Janela de perda de dados de 5 segundos. Toda persistência passa por um debounce de 5s do IndexPersistence. Quando o timeout de 30s do state::set estoura, o processo Node morre levando junto tudo que tava em memória (#204).
• Dois caminhos de leitura de config no mesmo código. process.env direto num lugar, getMergedEnv() em outro. O famoso “setei a variável e nada mudou” (#456).
• Hook errado em ~47% das tool calls do Claude Code. O hook leu data.tool_output, mas o Claude Code manda tool_response. Seis semanas com observações sumindo silenciosamente (#539).
• Engine roda no diretório de trabalho do chamador. Usuários de Windows acharam que perderam memórias porque cada terminal abria o state store num path diferente (#303, aberta).

Tem mais. Documentei aqui no meu repo de pesquisa. O autor é responsivo, o repo tem 15.7K estrelas, e mesmo assim a arquitetura escolhida (TypeScript MCP + iii-engine Rust separado + 4 portas, 3 processos, índices em memória persistidos via KV remoto) acumula uma classe de bug que não tem como fechar sem reescrever metade do sistema. A forma do problema é estrutural, não falta de esforço do mantenedor.

Foi a mesma história com toda outra solução que testei: ou é incompleta, ou focada demais em alguma tecnologia específica (vector DB proprietário, knowledge graph que precisa de Neo4j, pipeline LLM elaborado), ou exige que o usuário grite write_note toda vez que quer salvar algo. Nenhuma “sai do caminho” o bastante pra eu confiar em sessões longas.

O que eu queria desde o começo

Quando comecei minha maratona de 37 dias de vibe coding lá em fevereiro, sabia que precisava de algum organizador de conhecimento. Levei mais de 500 horas de experimentação pra cristalizar o que eu queria de verdade.

Pra quem usa só um dos três (Claude Code, ou Codex, ou opencode) e fica nele, você provavelmente não precisa de nada extra. Os três já fazem um trabalho razoável de gerenciar memória dentro da sessão. Claude Code tem três níveis de compaction (microcompact por gap temporal, autocompact por threshold de token, sessionMemoryCompact experimental). Codex tem auto_compact_token_limit por modelo. opencode tem compaction ancorada com buffer de 20K. Cobri isso em detalhe no post anterior.

A única disciplina extra que vale a pena adotar nesse caso é manter um diretório docs/ no projeto com arquivos markdown organizados por tópico, e pedir pro agente salvar lá quando algo importante acontece. Pesquisas que não devem ser refeitas, pegadinhas conhecidas, justificativa de por que escolheu opção A em vez de B. Funciona. Exige disciplina.

O problema aparece pra quem é como eu, que pula entre agentes no mesmo projeto. Eu uso Claude Code como padrão (acho o harness, o orquestrador de subagentes, e o planning de tarefas longas superior). Mas quando o Claude empaca num problema, eu disparo o Codex no mesmo diretório só pra “agitar”. O Codex pensa mais “fora da caixa” e às vezes encontra uma solução que o Claude não enxergou. Aí volto pro Claude pra implementar com mais cuidado.

Esse vai-e-volta entre agentes é o cenário onde a memória externa importa muito. Sem ela:

• Você fecha o Claude Code, abre o Codex no mesmo diretório, e o Codex não sabe nada do que foi discutido nas últimas 4 horas.
• Você precisa pedir manualmente pro Claude escrever uma nota de handoff em ./HANDOFF.md, depois pedir pro Codex ler. Toda vez.
• Projetos que você deixou parados por semanas: você abre, esqueceu por que decidiu não usar Redis, esqueceu qual era o bug que tinha na biblioteca X.

Karpathy resolveu o conceito da coisa no LLM Wiki dele, que detalhei no post anterior. Mas tem uma frase específica do gist que ficou na minha cabeça:

O index.md é “surpreendentemente bom — em ~100 fontes e algumas centenas de páginas, sem precisar de embeddings”.

Aquela linha resume o que eu queria. Não precisa de tecnologia complicada. Storage simples (markdown em git), índice simples (SQLite com FTS5 e links), instalação simples (um binário ou container), uso automático (hooks que disparam sozinhos), zero manutenção (memória decai sem o usuário mexer).

Foi por isso que comecei o ai-memory.

A pesquisa antes do código

Em vez de só sair codando, pesquisamos o código-fonte e issues dos projetos relevantes pra entender o que cada um acertou e errou. Salvei a pesquisa no próprio repo:

• research-karpathy-llm-wiki.md — o que Karpathy escreveu literal, separado do que a comunidade atribui (parafraseando) a ele. Três princípios fundamentais: compilação em vez de retrieval, três camadas (raw / wiki / schema), três operações (ingest / query / lint). Foi o blueprint conceitual.
• research-agentmemory.md — análise técnica do agentmemory: quatro níveis de consolidação (working → episodic → semantic → procedural), supersessão com is_latest=false em vez de delete, decaimento exponencial, reflexão por cluster. Mantive as ideias do agentmemory, mudei a implementação.
• research-basic-memory.md — Python, MCP-native, markdown puro no disco. O modelo é explicitamente manual: o agente chama write_note quando ele decide salvar. Bom modelo de storage, péssimo modelo de captura (depende do agente lembrar de chamar).
• research-cognee.md — pipeline de cognify (extract → chunk → graph + summarize → embed → persist) com knowledge graph + vector + relational triplo. Excelente pra agente de empresa rica que quer relação semântica entre entidades. Pesado demais pra “memória de sessão de coding”.

A síntese que tirei: agentmemory tem as ideias certas. O resto é execução.

A ideia que eu mais gosto do agentmemory, e que ele herdou parcialmente do LLM Wiki v2, é a consolidação tipo sono: memória curta retém detalhes brutos, memória longa vai consolidando e resumindo, e memória de longo prazo não acessada vai sendo esquecida. Não acumula lixo. Tem accessCount, decaimento exponencial geométrico, reforço por repetição espaçada. É similar e inspirado no que um humano faz dormindo.

No ai-memory eu mantive essa estrutura mas troquei a engenharia por baixo:

• TypeScript → Rust em binário único. Sem KV remoto separado. Sem 3 processos. Um binário escrito em Rust, com um diretório de dados e um servidor Axum.
• Índice persistente em SQLite + FTS5. Nativo. Sem reindex a cada restart. WAL mode, busy_timeout 5s.
• Writer único em thread dedicada via mpsc. Sem janela de perda de 5s, sem timeout de 30s estourando.
• Markdown puro no disco como source of truth. SQLite é só índice derivado. Você pode abrir o wiki no Obsidian. Pode dar grep. Pode versionar com git (e ele versiona automaticamente).
• Isolamento por projeto na estrutura física do disco. <wiki_root>/<workspace_id>/<project_id>/... chaveado por UUIDs estáveis. Renomear projeto é update de uma coluna. Apagar projeto é rm -rf de um subdir. Mesmo nome de página em dois projetos não colide.
• Embedding e LLM são opcionais. Sem chave de provedor, o sistema ainda funciona com FTS5, expansão por links e fallback nas observações brutas. Adicione embeddings quando quiser re-ranking vetorial, e Claude Haiku ou GPT-5.4-mini quando quiser páginas consolidadas com qualidade.

Como funciona no dia a dia

A interação com os agentes é por dois mecanismos: hooks/extensões (captura automática) e MCP (consulta sob demanda).

Claude Code e Codex usam shell hooks. OpenCode usa plugin TypeScript. OMP/Pi usa extensão TypeScript. Cursor e Gemini CLI usam configurações JSON de lifecycle. Todos mandam eventos equivalentes (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop, SessionEnd) como POST fire-and-forget pro servidor HTTP do ai-memory (rodando em 127.0.0.1:49374 por padrão). O agente nunca espera. Se o ai-memory tiver fora do ar, a sessão continua normal, só sem captura. Claude Desktop e OpenClaw entram como MCP-only: consultam memória, mas não capturam ciclo de vida automaticamente.

Do lado do agente, o MCP server expõe ferramentas que o LLM pode chamar quando achar útil:

O snippet de routing que vai no CLAUDE.md (ou AGENTS.md pra Codex/OpenCode/Cursor/Gemini/OMP) é o que faz o agente saber quando chamar qual ferramenta. Ele se instala com um comando: peça pro agente “instala o routing do ai-memory neste projeto” e ele invoca a tool MCP memory_install_self_routing, recebe o snippet canônico, e escreve no arquivo certo. Idempotente.

Exemplo de handoff entre agentes

Eis o cenário concreto que motivou o projeto:

$ claude
> "Tô refatorando autenticação. A rotação de JWT tá quebrada, vou
   testar session cookies como alternativa."
[trabalha por uma hora]
> /exit

$ codex   # mesmo diretório, horas ou dias depois
[SessionStart hook do ai-memory busca o handoff e prepende ao contexto]
> "Continuando: você estava investigando session cookies como
   alternativa à rotação de JWT quebrada. Posso seguir?"

Você não fez nada especial. No SessionEnd do Claude Code, o ai-memory consolidou as observações da sessão numa página sessions/<uuid>.md, criou um handoff tipado com open_questions + next_steps, e marcou como “pending”. No SessionStart do Codex, o servidor viu o handoff pending, recuperou e injetou no contexto inicial. O agente lê e continua.

Mesmo cenário se você abandona o projeto por dois meses e volta. O memory_explore calibra a verbosidade automaticamente: faz menos de uma hora desde a última sessão, retorna uma linha. Faz mais de 30 dias, retorna um resumo completo do que rolou.

Adotando ai-memory num projeto que já existe

Se você instalar o ai-memory num projeto que já tem meses de história, o wiki começa vazio e as primeiras sessões são saldo zero. Você tá populando, não recuperando. O comando ai-memory bootstrap resolve isso. Ele coleta seu git log, README, docs/, cabeçalhos de módulo e arquivos de regras do projeto (CLAUDE.md / AGENTS.md), e manda pro servidor que usa o LLM pra gerar páginas-semente do wiki:

cd ~/Projects/meu-projeto
ai-memory bootstrap

Custa cerca de $0.05 com Claude Haiku 4.5 (orçamento capado em 50K input tokens). Rode com --dry-run primeiro pra ver o que seria mandado sem pagar. A partir daí o wiki começa com contexto real, e cada sessão adiciona em cima.

Instalação: três comandos

Eu reduzi a instalação ao essencial. O caminho recomendado é Docker, porque o servidor fica isolado e a atualização é uma linha. Não precisa de mais nada:

# 1. Wrapper script (~3KB) que chama o binário dentro do container
mkdir -p ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/akitaonrails/ai-memory/main/bin/ai-memory \
    -o ~/.local/bin/ai-memory
chmod +x ~/.local/bin/ai-memory

# 2. Sobe o servidor (loopback-only, sem auth — single-user laptop)
docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    -e AI_MEMORY_LLM_PROVIDER=anthropic \
    -e ANTHROPIC_API_KEY=sk-ant-... \
    akitaonrails/ai-memory:latest

# 3. Configura seu agente
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

Pronto. Abra o Claude Code como sempre. Cada prompt e tool call agora aterrissam no ai-memory, e a próxima sessão que você abrir no projeto vai ver um handoff com onde você parou.

Repita o passo 3 com --agent codex, --agent opencode, --agent omp/pi, --client cursor, --client gemini-cli, --client pi/omp, etc. pra outros agentes. Claude Desktop e OpenClaw são MCP-only. Idempotente: re-rodar substitui só a entrada do ai-memory, preserva qualquer outro hook/MCP que você tenha. Faz backup .bak-<timestamp> antes de cada escrita.

O README do projeto cobre as variações (Docker compose, homelab no LAN com bearer token, instalação sem Docker, build do fonte). Recomendo seguir o docs/install.md se seu setup foge do caminho padrão.

Comandos úteis que vale conhecer

Depois de instalado, o dia a dia normal é só usar os agentes. Mas vale conhecer alguns comandos pra quando precisar:

• ai-memory upgrade — auto-atualização do wrapper + docker pull da imagem nova + re-instalação dos hook scripts/plugins/extensões. Idempotente. Se você tem servidor remoto separado, refresca só o cliente local; o servidor você atualiza separadamente.
• ai-memory bootstrap — semeia o wiki a partir de git log + README + docs/ + regras do projeto. Pra projetos que já existem antes do ai-memory entrar.
• ai-memory purge-project --project <nome> --confirm — apaga um projeto inteiro. Atômico: linhas do SQLite, subdir do wiki, sem tocar nos vizinhos.
• ai-memory rename-project --from <nome> --to <novo> — renomeia. Uma coluna no DB, sem mover arquivo no disco. Sem efeito colateral.
• ai-memory backup — snapshot do diretório de dados (wiki + SQLite). ai-memory restore desfaz.
• ai-memory lint / ai-memory forget-sweep / ai-memory embed — manutenção manual. Lint e forget-sweep também rodam no agendamento do servidor por padrão; embedding backfill existe mas fica desligado por default porque pode chamar provedor pago.
• ai-memory generate-auth-token — quando você for expor o servidor além do loopback (ver docs/deploy.md).

Explorando o wiki no navegador

O servidor também pode montar uma UI web read-only em http://127.0.0.1:49374/web quando sobe com --enable-web. Mesmo binário, mesma porta, sem processo extra. Serve pra três coisas práticas: auditar o que o agente vem salvando, conferir se as páginas consolidadas tão coerentes, e compartilhar uma página avulsa com alguém do time sem precisar dar acesso ao agente.

A homepage lista os projetos detectados, cada um com contagem de páginas e tempo desde a última atividade:

Repare no aviso laranja no topo: o wiki é otimizado pra consumo por LLM, com páginas compiladas a partir de observações de sessão pelo LLM consolidador. Pra documentação canônica curada por humano, use o docs/ próprio do projeto. O /web é pra “spelunking” (vasculhar o histórico).

Cada projeto é isolado por UUID na estrutura física do disco. Duas páginas com o mesmo path em projetos diferentes não colidem. Ao clicar num card você cai na árvore de páginas dele:

A sidebar mostra a árvore agrupada por tipo: concepts/ (conhecimento durável), decisions/ (decisões arquiteturais), gotchas/ (pegadinhas), _rules/ (regras de projeto sugeridas pro CLAUDE.md), sessions/ (logs por sessão), e bootstrap.md (manifesto gerado pelo ai-memory bootstrap). A coluna direita mostra atividade recente.

Clicando em qualquer página, você cai no markdown renderizado:

O rendering tem syntax highlighting, badges de tier (working/episodic/semantic/procedural) e kind (decision/gotcha/rule/fact), breadcrumbs, supersession chain visível. A busca combina FTS5, expansão por links e, se configurado, embeddings; modo claro/escuro segue a preferência do sistema via prefers-color-scheme.

Pra editar o wiki você abre os arquivos direto em qualquer editor de markdown (Obsidian funciona bem). A interface web é read-only por design: o LLM consolidador é quem escreve, humanos só leem.

Por que Docker

A escolha de Docker como caminho recomendado foi deliberada. Algumas vantagens práticas:

• Atualização é uma linha. ai-memory upgrade puxa a imagem nova, refresca o wrapper, re-instala hooks/plugins/extensões. Você não compila Rust, não cuida de versão de libsqlite, não briga com mise/Node version churn como acontece com soluções baseadas em Node.
• Isolamento real. O servidor roda no container, lê só /data (volume nomeado), não polui seu sistema. Se quiser limpar, é docker volume rm.
• Mesma imagem em vários setups. Laptop, desktop, homelab. Mesma imagem amd64 ou arm64.
• Restart automático. --restart unless-stopped faz o servidor voltar quando você reinicia o Docker, ou quando liga a máquina (assumindo systemctl enable docker).
• Build de source não é necessário. Quem compila Rust toolchain 1.95+ leva uns 3 minutos em release. Pro usuário final, isso é cerimônia desnecessária. O Docker abstrai tudo.

Tem caminho sem Docker no docs/install.md pra quem prefere. Mas Docker é onde a UX é melhor.

Qual LLM usar pra consolidação

Esse é um caso onde não precisa de modelo pesado. A consolidação é texto entra, texto sai: o agente registra observações brutas durante a sessão, no SessionEnd o LLM compila 1-5 páginas de wiki classificadas como concept / decision / gotcha / rule. Não tem raciocínio complexo, não tem código. Opus 4.7 ou GPT-5.5 thinking são overkill, custam caro e demoram muito pra uma tarefa que aceita modelo leve.

Pra escolher o default rodamos A/B testing sério em 6 provedores diferentes contra 5 fixtures sintéticas, cada uma desenhada pra estressar um modo de falha específico: extração multi-página, restrição (resistir a fabricar página quando a sessão é trivial), classificação correta de rule vs gotcha vs decision, e separação de tópicos não relacionados. A doc completa, com tabelas de parse rate, latência e qualidade por fixture, tá em docs/llm-provider-comparison.md. Resumindo a tabela final:

Por que Haiku ficou como default: hospedado (sempre disponível), o melhor em restrição (resiste a fabricar páginas quando a sessão é trivial, crucial pra wiki não virar coleção de páginas vazias) e o melhor em classificação (acerta kind: rule consistentemente, que é o que faz o roteamento automático pro _rules/<slug>.md funcionar). Custo de $0.02 por consolidação é desprezível pra uso pessoal.

Mas o usuário tem alternativas legítimas:

• GPT-5.4-mini se o orçamento aperta (5× mais barato que Haiku, 2× mais rápido). O único defeito mensurável foi fabricar uma página decisions/docs-spelling.md numa sessão de correção de typo. Over-classification, mas leve.
• qwen3:32b no Ollama se você tem servidor local com ~20GB de RAM/VRAM disponível. Zero custo por consolidação, fidelidade compatível com os hospedados. A latência alta (~92s) não importa porque consolidação roda em background.
• DeepSeek V4 Flash funciona, mas o GPT-mini iguala em qualidade e bate em velocidade.

Quem quiser testar outros modelos, o harness de avaliação tá em evals/ como crate Rust separada. Adiciona um JSON de fixture, roda cargo run -p ai-memory-eval --release, compara dois provedores lado a lado. Os outputs ficam em evals/runs/<timestamp>/{baseline,candidate}/ com o .raw.txt exato que o modelo respondeu mais o .meta.json com latência e parse rate. PRs com novos modelos testados são muito bem-vindos.

Status: beta, falta usuário

O ai-memory tá nas tags v0.2-complete no GitHub. As funcionalidades principais funcionam: captura automática, MCP, web UI opcional, bootstrap, purge/rename/backup, bearer auth, browse, busca FTS5 + graph/link-neighbour RRF, embeddings opcionais, consolidação, decay, manutenção agendada e handoff entre Claude Code / Codex / OpenCode / Cursor / Gemini CLI / OMP-Pi. Eu rodo em produção pessoal há algumas semanas.

Mas é beta. Precisa de muito mais usuário batendo nele pra eu encontrar os bugs que ainda não aparecem na minha máquina. Claude Desktop e OpenClaw funcionam como MCP-only; alguns clientes MCP exóticos ainda precisam de teste real. A integração mais polida hoje é Claude Code, seguida de Codex, OpenCode e OMP/Pi.

Se você tá lendo até aqui, considera instalar e me mandar feedback. Issues no github.com/akitaonrails/ai-memory/issues. PRs são muito bem-vindos — o código é Rust, MIT, e a arquitetura tá documentada em docs/ARCHITECTURE.md e docs/design-decisions.md. Mesmo bug report de “instalei, não rodou no meu setup” ajuda — significa que tem algo que assumi sobre ambientes que não bate com o seu.

A motivação central continua sendo a frase do Karpathy. Memória de agente é texto. Texto fica no disco. Indexa com SQLite. Compila com LLM quando vale o trabalho. Esquece quando ninguém olha mais. Sai do caminho. E quando você troca de agente no meio do projeto, o próximo já sabe onde você parou.

É isso que o ai-memory tenta entregar.

Até “funciona”, mas esse projeto foi mais pelo exercício. Dito isso, deixa eu contar por que fiz isso.

O problema com o OpenClaw

O OpenClaw é um gateway que conecta canais de mensagem (Telegram, Discord, Slack, WhatsApp, etc.) a provedores de IA (OpenAI, Anthropic, Ollama). Você configura, sobe o servidor, e pode conversar com LLMs direto pelo Telegram ou qualquer outro canal. É um projeto popular e com bastante atividade.

Atividade demais, na verdade.

Eu fiz um clone depth-1 do repositório e rodei um tokei:

Mais de um milhão de linhas de TypeScript. Os 2.799 arquivos de teste parecem bastante em número absoluto, mas proporcionalmente ao tamanho do codebase, a cobertura é baixa. A maior parte do código está em 29 pacotes de um monorepo com 21 extensões.

Fui buscar mais commits pra entender o ritmo de desenvolvimento. Nos 100 commits que consegui puxar, todos caíram em apenas 2 dias (9 e 10 de março). ~50 commits por dia, de 42 contribuidores diferentes. Vibe coding ao extremo.

A conclusão é a que você imagina: volumes enormes de código gerado por IA sendo despejados num repositório a uma velocidade que impossibilita review humano sério. E isso me incomodou o suficiente pra ir investigar mais a fundo.

A auditoria de segurança

Pedi pro Claude fazer uma auditoria de segurança completa no código do OpenClaw. O relatório encontrou:

Sete vulnerabilidades críticas. Deixa eu listar algumas:

• Timing side-channel na comparação de tokens – o safeEqualSecret() faz um return antecipado no type-check, permitindo que um atacante distinga tokens malformados de tokens errados medindo latência.
• eval() no browser tool – execução arbitrária de JavaScript sem sandbox.
• Shell sem allowlist – qualquer tool pode executar qualquer comando no sistema.
• Webhooks do Slack sem verificação de assinatura nenhuma.
• Transcripts e config em texto puro no disco, sem criptografia.
• Sem rate limiting efetivo – IPs podem ser spoofados se o operador configura trusted proxies de forma ampla.

Essas são só as que o Claude encontrou numa varredura automatizada. Provavelmente tem mais.

Eu não vou rodar isso na minha máquina. Nem dentro de um container Docker. Um gateway que recebe webhooks da internet, executa comandos shell, se conecta a APIs de IA com suas chaves, e guarda histórico de conversas, tudo isso com 7 vulnerabilidades críticas conhecidas? Não, obrigado.

Então eu fiz o que qualquer desenvolvedor racional faria: decidi construir o meu.

A primeira tentativa: Claude Code

Comecei do jeito mais direto. Clonei o OpenClaw, apontei o Claude Code pro código, e pedi: “reescreve isso em Rust.”

Não funcionou. O codebase é grande demais. Mais de um milhão de linhas de TypeScript espalhadas em 29 pacotes. O Claude não consegue manter tudo em contexto. O resultado inicial foi muito incompleto: muitos tipos criados mas sem implementação, todo!() por toda parte, boilerplate demais e funcionalidade de menos.

Troquei pro Codex 5.4 pra testar. Mesma coisa: pedi pra analisar e reescrever. Melhorou um pouco em certos aspectos, mas o problema fundamental é o mesmo. Nenhuma IA hoje pega um projeto desse tamanho e reescreve inteiro de uma vez. O contexto não cabe.

A técnica que funciona

O que funciona é ir devagar. Um passo de cada vez.

Pede pro Claude (ou Codex) analisar o código original em etapas. Faz um plano longo detalhando cada feature. Depois implementa uma feature por vez em Rust, com testes, faz commit, e repete. É tedioso, mas é o que produz código que compila e funciona de verdade.

O motivo é simples: o código original é tão massivo que nenhum agente de IA (nem vários em paralelo) consegue manter tudo em contexto ao mesmo tempo. Você precisa decidir o que importa, implementar aquilo, validar, e seguir pro próximo.

E precisa decidir o que cortar. O OpenClaw tem 21 extensões de canal: Google Chat, iMessage, IRC, Teams, Matrix, Mattermost, Nostr, Twitch… Eu não preciso de nenhuma dessas. Mantive os canais mainstream: Web, Telegram, Discord, Slack, Signal, WhatsApp e Email. TTS? Fora. Polls? Fora. WhatsApp Web via Baileys? Fora, uso a Cloud API oficial. São features que adicionam complexidade sem valor proporcional.

Descobrindo o IronClaw

No meio do desenvolvimento, descobri o IronClaw, que se apresenta como “OpenClaw em Rust”. Ótimo, pensei. Vou ver o que eles fizeram.

Clonei o repositório e pedi pro Claude escrever um relatório de comparação. O IronClaw tem coisas boas. Adotei 12 features:

Circuit breaker com retry e backoff exponencial pra resiliência de providers LLM. Detecção de leak de credenciais no output. Cache de respostas LLM com SHA-256 da prompt. Cost tracking com budget guards (aviso em 80%, bloqueio em 100%). Extended thinking pra Claude 3.7+ e o1. MCP client pra tool servers externos. Lifecycle hooks em inbound, tool calls e outbound. Smart model routing que joga queries simples pra modelos mais baratos. Suporte a túneis (cloudflared, ngrok, tailscale). REPL interativo (frankclaw chat). Routines com event triggers além de cron. Job state machine com auto-repair.

Mas o IronClaw depende de PostgreSQL + pgvector, tem sandbox WASM (wasmtime adiciona ~10MB), e é parte do ecossistema NEAR AI. Eu quero um binário único com SQLite embarcado e zero dependências externas.

O que o FrankClaw traz do OpenClaw

O core do OpenClaw está lá: 7 canais de mensagem, multi-provider com failover, agent runtime, sistema de comandos, skills, subagents, browser automation via CDP, bash tool com allowlist, cron jobs, REPL interativo. Mais as 12 features do IronClaw que listei acima.

Mas vários pedaços precisaram ser reescritos de um jeito que o original não fez. A compactação de contexto, por exemplo, usa sliding window com estimativa de tokens, pruning de mensagens e repair automático de tool pairs que ficam órfãos quando o contexto é cortado. O failover entre providers agora é model-aware: se você pede um modelo Claude e o provider da vez é OpenAI, ele pula automaticamente em vez de dar erro. O canvas renderiza SVG, HTML e Markdown com detecção de conflitos de revisão. São coisas que no OpenClaw ou não existiam ou estavam pela metade.

Depois veio a fase de adicionar o que faltava pra paridade. O FrankClaw hoje tem 30+ LLM tools: web_fetch (SSRF-safe com HTML-to-text), web_search (Brave API), file_read/file_write/file_edit (sandboxed no workspace com proteção contra path traversal), pdf_read, image_describe (via modelos de vision), audio_transcribe, sessions_list/sessions_history/sessions_delete, message_send/message_react, cron_list/cron_add/cron_remove, config_get (auto-redação de secrets), agents_list, memory_get/memory_search, mais os browser tools (browser_open, browser_extract, browser_snapshot, browser_click, browser_type, browser_wait, browser_press, browser_sessions, browser_close, browser_aria).

Algumas adições que não existem no OpenClaw original: um sistema de memória/RAG com SQLite FTS5 e embeddings (OpenAI, Gemini, Voyage) que sincroniza arquivos do workspace automaticamente. Uma API compatível com OpenAI (/v1/chat/completions e /v1/models), então qualquer cliente que fala esse protocolo (Cursor, Continue, Open WebUI) pode usar o FrankClaw como backend sem adaptação. Uma TUI em ratatui pra quem prefere terminal. Aprovação interativa de tools destrutivos antes de executar.

Tem coisas menores que fazem diferença na prática. Você pode configurar múltiplas API keys por provider com round-robin e backoff automático, então se uma key estourar o rate limit, a próxima assume. O model catalog já sabe context windows e custos dos modelos OpenAI e Anthropic sem você ter que configurar. Extração de URLs de mensagens tem blocklist de IPs privados contra SSRF. O sistema de comandos aceita directives inline (/think, /model) além de aliases.

Do lado de operação: ACP (Agent Client Protocol) via JSON-RPC 2.0 sobre NDJSON pra quem quer integrar programaticamente. Sistema de plugins com manifests e lifecycle de enable/disable. i18n com 9 locales via FRANKCLAW_LANG. Workspace identity files (SOUL.md, IDENTITY.md) pra definir a personalidade do bot por projeto. Health monitor nos canais com auto-restart. WebSocket com ping keepalive que sobrevive timeouts de proxy e túnel. frankclaw start/stop/status pra quem quer rodar como daemon com PID tracking. E toda a configuração migrou de JSON pra TOML.

Hardening: onde está o diferencial

O relatório de auditoria que rodamos no OpenClaw encontrou 7 vulnerabilidades críticas e 9 high. O FrankClaw resolve todas:

O FrankClaw compila com #![forbid(unsafe_code)] em todos os 13 crates. Zero blocos unsafe.

E a auditoria não parou no OpenClaw. Fizemos uma auditoria por componente em 14 fases comparando cada parte do FrankClaw contra o original: canais, providers, runtime, tools, sessions, crypto, cron, webhooks. Tudo documentado.

Deploy: como instalar

O FrankClaw roda com Docker Compose. Três containers: gateway, Chromium headless (pra browser tools), e Cloudflare tunnel (pra receber webhooks).

1. Clonar e configurar

git clone https://github.com/akitaonrails/frankclaw.git
cd frankclaw
cp .env.docker.example .env.docker

Edite o .env.docker com suas chaves:

# Providers de IA (preencha os que usar)
OPENAI_API_KEY=
ANTHROPIC_API_KEY=

# Canais (preencha os que quiser usar)
TELEGRAM_BOT_TOKEN=         # via @BotFather
WHATSAPP_TOKEN=             # Meta Business Platform
WHATSAPP_PHONE_ID=
WHATSAPP_VERIFY_TOKEN=
DISCORD_BOT_TOKEN=
SLACK_BOT_TOKEN=
SLACK_APP_TOKEN=

# Embedding providers (só se usar memória/RAG)
# GEMINI_API_KEY=
# VOYAGE_API_KEY=

# Opcional: criptografia de sessions (recomendado)
# Gere com: openssl rand -base64 32
FRANKCLAW_MASTER_KEY=

# Opcional: scan de malware em uploads
VIRUSTOTAL_API_KEY=

2. Configurar o gateway

O arquivo frankclaw.toml define agentes, modelos e canais. Use o wizard ou os exemplos:

# Gerar config base com canal web
cargo run -- onboard --channel web

# Ou copiar dos exemplos
ls examples/channels/

Pra cada canal, o CLI tem templates prontos:

cargo run -- config-example --channel telegram
cargo run -- config-example --channel whatsapp

3. Cloudflare Tunnel (pra receber webhooks)

Se você vai usar canais que precisam de webhook (Telegram, Discord, Slack, WhatsApp), precisa de um túnel público. O Docker Compose já inclui o cloudflared:

# Copie suas credenciais do Cloudflare
cp docker/cloudflared/config.yml.example docker/cloudflared/config.yml
cp ~/.cloudflared/<tunnel-id>.json docker/cloudflared/credentials.json
cp ~/.cloudflared/cert.pem docker/cloudflared/cert.pem
# Edite config.yml com seu hostname

4. Subir

docker compose up -d

O gateway sobe na porta 18789 (interna ao Docker). O cloudflared roteia o tráfego externo. O Chromium fica na rede interna pra browser tools.

Pra testar local sem Docker:

cargo run -- chat

Abre o REPL interativo direto no terminal (agora também tem uma TUI em ratatui com dark mode e tabs). Sem gateway, sem webhook. Bom pra validar que o provider de IA está respondendo antes de configurar canais.

Validação

cargo run -- check     # valida config
cargo run -- doctor    # diagnóstico completo
cargo run -- audit     # auditoria de segurança com severity ratings

O audit é o que eu mais gosto. Ele verifica se você tem criptografia habilitada, se as permissões de arquivo estão corretas, se os webhooks têm verificação de assinatura, se o bash tool está em deny-all. Sai com exit code non-zero se encontra problemas críticos, então dá pra colocar no CI.

O processo de desenvolvimento

O projeto tem 178 commits em ~5 dias de trabalho (10-16 de março). Quase 57 mil linhas de Rust em 120 arquivos, organizados em 13 crates.

Os commits contam a história. As primeiras dezenas foram scaffold: estrutura do workspace, tipos básicos, o gateway HTTP/WebSocket, primeira versão dos channel adapters. Código gerado em massa, muita coisa incompleta.

Depois começaram os adapters de canal, um por um:

236aa1c - Minimal Discord channel adapter
fd67017 - Minimal Slack channel adapter
9f51373 - Minimal Signal channel adapter
1052e47 - WhatsApp channel webhook adapter
035f86e - Email channel adapter (IMAP inbound, SMTP outbound)

Quando os canais básicos estavam no lugar, veio a integração do IronClaw num commit grande:

c87ab32 - IronClaw-derived features: circuit breaker, retry, leak detection, cache, cost tracking, extended thinking

E aí veio o hardening. Essa foi a fase que eu mais tive que intervir manualmente, porque o Claude gera código funcional mas não pensa em vetores de ataque sozinho:

db34198 - Prompt injection sanitization, external content wrapping, prompt size limit
5719b34 - Optional VirusTotal malware scanning for file uploads
ccd2b2b - Harden input validation across all user-facing entry points
aa918ee - Optional ai-jail sandbox for bash tool
2d7b1df - Security audit command with severity-rated findings
d12cc97 - 3-tier ToolRiskLevel system replacing binary browser mutation flag
21e0c91 - Timing-safe token comparison in WhatsApp, crypto audit tests
e240c1b - Webhook replay prevention with timestamp verification
876a78c - Gateway & media: SSRF redirect validation, filename hardening

22 commits de security hardening. Mais 10 de auditoria por componente. Cada achado virou um commit com fix.

Depois vieram as auditorias específicas por canal, cada uma descobrindo edge cases diferentes:

43b085f - Discord audit: HELLO timeout, fatal close codes, message chunking
12c7cff - Telegram audit: caption overflow, parse fallback, edit idempotency
f515062 - WhatsApp audit: message type filtering, send error classification
3c42aff - Slack audit: fatal auth errors, send error classification

Browser tools precisaram de atenção extra. Um headless Chrome que recebe URLs de um LLM é um vetor de ataque óbvio:

3217a96 - Browser automation: CDP timeout, SSRF guard, session limits, crash recovery
d98a803 - Gate mutating browser tools behind operator approval
014f56e - Browser screenshot/ARIA tools for accessibility tree inspection

Nos commits mais recentes, o projeto começou a divergir do OpenClaw:

5d73c4d - OpenAI-compatible HTTP API (/v1/chat/completions, /v1/models)
d832c36 - Memory/RAG system with SQLite FTS5, embeddings, and file sync
2b05f47 - Interactive tool approval for mutating/destructive tools
49034eb - Web console: dark mode, 8 tabs, focus mode, tool sidebar
9f51a18 - TUI, Gemini/Voyage embeddings, plugin management, ACP protocol
3c0703b - Config migration from JSON to TOML
eb130ad - Channel health monitor with auto-restart and rate limiting
2c3ea7e - Workspace bootstrap files (SOUL.md, IDENTITY.md) to system prompt
9df61bf - Model-aware failover routing, canvas SVG rendering
c7ba108 - WebSocket ping keepalive and auto-reconnect to web console

A API compatível com OpenAI é a que eu mais uso no dia a dia. Cursor, Continue, Open WebUI, qualquer coisa que fala o protocolo OpenAI consegue usar o FrankClaw como backend sem mexer em nada do lado do cliente.

Os números

Comparado ao OpenClaw:

Os números não são diretamente comparáveis. O OpenClaw tem 21 extensões de canal que eu cortei, uma UI web mais completa, e features de nicho que não portei. Mas o core (gateway, canais mainstream, providers, runtime, sessions, tools, memória) está lá com 22x menos código.

Como ajudar (beta testing)

O FrankClaw funciona pra conversa básica via Web e Telegram (testei ambos). WhatsApp funciona pra mensagens simples. Discord, Slack, Signal e Email estão implementados mas não tiveram teste extensivo. Não fizemos nenhum workflow complicado ainda.

Se você quer testar: clone o repositório, suba com Docker Compose, configure pelo menos um canal (Telegram é o mais fácil) e tente usar normalmente. Mande mensagens, teste tool calls, tente quebrar o sistema. Abra Issues no GitHub com o que encontrar.

O que eu sei que precisa de mais olhos: workflows com tools (browser, bash, MCP), subagent orchestration, failover entre providers, session persistence com criptografia, smart routing entre modelos, scheduled jobs, o sistema de memória/RAG, e a API OpenAI-compatible. Basicamente tudo que vai além de “manda mensagem, recebe resposta”.

Não precisa ser desenvolvedor Rust. O valor maior está em usar o sistema de formas que eu não pensei e encontrar os edge cases que só aparecem com uso real.

O FrankClaw não substitui o OpenClaw hoje. O OpenClaw tem mais canais, mais features, mais gente trabalhando nele. Mas carrega o peso de mais de um milhão de linhas de TypeScript geradas a 50 commits por dia por dezenas de contribuidores, com vulnerabilidades críticas documentadas. O FrankClaw é a alternativa pra quem olha pra isso e pensa “eu não vou rodar esse código na minha máquina”.

Mas vou ser honesto: apesar de ter sido divertido construir, eu pessoalmente não sei se preciso disso. O FrankClaw é um gateway genérico, feito pra ser flexível, conectar qualquer canal a qualquer provider, com runtime de agentes, tools, subagents, jobs, hooks. É muita infraestrutura.

O que eu descobri nos últimos meses é que eu consigo construir bots customizados pra tarefas específicas muito mais rápido. Em 1 dia eu tenho um bot funcionando, focado no que eu preciso, sem carregar o peso de um framework genérico. Foi o que eu fiz com o Marvin no projeto da newsletter, por exemplo. Um bot de Discord feito sob medida, que faz exatamente o que eu preciso e nada mais.

Um gateway genérico como o FrankClaw faz mais sentido pra quem quer uma interface unificada entre vários canais de chat e vários modelos de IA sem programar. Se esse é o seu caso, experimenta. Se você é desenvolvedor e sabe o que quer, talvez um bot customizado te sirva melhor. Fica a seu critério.

O repositório está aqui. AGPL-3.0.

–

Em janeiro publiquei um shell script de ~170 linhas que montava um sandbox com bubblewrap pra rodar Claude Code, OpenCode, Crush e qualquer outro agente de IA. Funcionava. Resolvia o problema. Mas era um script bash jogado em ~/.local/bin/ que você tinha que copiar, colar, e rezar pra não precisar customizar demais.

Dois meses usando aquele script todo dia me mostraram os limites. Queria configuração por projeto. Queria suporte a macOS pros devs do meu time. Queria parar de editar arrays em bash toda vez que precisava de um diretório extra. E queria algo que alguém pudesse instalar com brew install ou cargo install em 10 segundos, sem ler 170 linhas de script.

Resultado: ai-jail. Uma ferramenta em Rust, ~880KB, 4 dependências, 124 testes, que faz exatamente o que aquele script fazia e mais. Vou explicar o que mudou e por que você deveria estar usando.

O Problema (de novo, pra quem pulou o post anterior)

Agentes de IA pra programação precisam de acesso ao seu filesystem. Precisam rodar compiladores, linters, grep, ls, make, cargo, npm. O mínimo pra serem úteis. O problema é que junto com esse acesso vem a capacidade de ler ~/.aws/credentials, exportar suas chaves SSH, ou rodar um rm -rf fora do diretório do projeto.

Não é paranoia. Supply-chain attacks são reais. Toda hora uma lib de NPM, PyPI, ou RubyGems é comprometida. Se o agente rodar npm install e um post-install script malicioso tentar exfiltrar seus dados, a única coisa entre o atacante e suas credenciais é o que você montou de barreira antes.

A resposta é um sandbox. Especificamente, um que permita o agente trabalhar no diretório do projeto com as ferramentas que precisa, mas que torne invisível todo o resto do sistema.

De Script pra Ferramenta

O shell script do post anterior já resolvia isso com bubblewrap. O ai-jail resolve o mesmo problema, mas trata as limitações que dois meses de uso diário revelaram:

A lógica core é a mesma: bubblewrap cria namespaces isolados de PID, UTS, IPC, monta o $HOME como tmpfs efêmero, e só monta o diretório do projeto com escrita. A diferença é que agora tudo isso é configurável sem editar código.

Instalação

Quatro formas:

# Homebrew (macOS e Linux)
brew tap akitaonrails/tap && brew install ai-jail

# Cargo
cargo install ai-jail

# Mise
mise use -g ubi:akitaonrails/ai-jail

# Binário direto do GitHub Releases
curl -fsSL https://github.com/akitaonrails/ai-jail/releases/latest/download/ai-jail-linux-x86_64.tar.gz | tar xz
sudo mv ai-jail /usr/local/bin/

No Linux, bubblewrap precisa estar instalado separadamente: pacman -S bubblewrap (Arch), apt install bubblewrap (Debian/Ubuntu), dnf install bubblewrap (Fedora). No macOS não precisa de nada extra.

Uso Básico

cd ~/Projects/meu-app

# Roda Claude Code dentro do sandbox
ai-jail claude

# Roda Codex
ai-jail codex

# Roda OpenCode
ai-jail opencode

# Bash puro pra debug
ai-jail bash

# Qualquer comando
ai-jail -- python script.py

Na primeira execução, ele cria um arquivo .ai-jail no diretório do projeto:

# ai-jail sandbox configuration
# Edit freely. Regenerate with: ai-jail --clean --init

command = ["claude"]
rw_maps = []
ro_maps = []

Esse arquivo é commitável no repo. Quando outro dev do seu time clona o projeto e roda ai-jail, a mesma configuração se aplica.

Se quiser adicionar diretórios extras, pode fazer pela CLI ou direto no TOML:

# Diretório extra com escrita
ai-jail --rw-map ~/Projects/shared-lib claude

# Diretório extra somente leitura
ai-jail --map /opt/datasets claude

Quer ver o que o sandbox vai fazer sem executar nada?

ai-jail --dry-run --verbose claude

Isso mostra cada mount point, cada flag de isolamento, o comando completo do bubblewrap. Sem surpresas.

Por Que Bubblewrap no Linux

Avaliei as alternativas antes de decidir. O documento completo de análise tá no repositório, mas o resumo é:

Bubblewrap (bwrap) é o sandbox que o Flatpak usa pra isolar todo app desktop. ~50KB de binário, ~4000 linhas de C, mantido pelo time do GNOME. Roda sem root usando CLONE_NEWUSER pra criar namespaces sem privilégio elevado. Tá empacotado em toda distro Linux relevante e testado em escala por milhões de instalações Flatpak.

Considerei e descartei as alternativas. Firejail requer setuid root, e confiar em setuid pra proteger contra agentes que já rodam no seu sistema é contraditório. nsjail e minijail são projetados pra ambientes de produção (Google os usa internamente), complexos demais pra workstation de dev. systemd-nspawn requer root e é pra containers de sistema, não pra isolar um processo.

Landlock é um caso diferente. Ele não substitui bubblewrap — não tem nada a ver com namespaces ou mount isolation. Mas complementa. Landlock é um LSM (Linux Security Module) que controla acesso no nível do VFS, independente dos mount namespaces. Isso fecha vetores que o bwrap sozinho não cobre: rotas de escape pelo /proc, tricks com symlinks dentro de mounts permitidos, e serve como seguro contra bugs no próprio mecanismo de namespaces. A partir da v0.4.0, o ai-jail aplica Landlock automaticamente em kernels 5.13+ como defense-in-depth. Usa ABI V3 (Linux 6.2+) com degradação graceful pra V1 em kernels mais antigos, e vira no-op silencioso se o kernel não suportar. Se causar problema com alguma ferramenta específica, --no-landlock desativa.

Bubblewrap acerta no ponto exato: isolamento real sem root, em toda distro, e simples o suficiente pra wrappear num binário de 880KB.

O Que o Sandbox Faz no Linux

Quando você roda ai-jail claude, o seguinte acontece:

O agente roda em namespaces isolados de PID, UTS e IPC, com hostname ai-sandbox, e morre automaticamente se o pai morrer (--die-with-parent).

O filesystem é montado numa sequência específica (bubblewrap é order-dependent). /usr, /etc, /opt, /sys entram read-only pras ferramentas do sistema. /dev e /proc montados pra acesso a devices e processos. /tmp e /run como tmpfs frescos. GPUs auto-detectadas (/dev/nvidia*, /dev/dri). Docker socket, X11/Wayland, /dev/shm, tudo auto-detectado e montado se existir.

A parte mais importante é o tratamento do home directory. $HOME é montado como tmpfs vazio. Depois, seletivamente, dotfiles são layered por cima. .gnupg, .aws, .ssh, .mozilla, .sparrow nunca são montados (dados sensíveis). .claude, .crush, .codex, .aider, .config, .cargo, .cache, .docker entram como read-write porque os agentes precisam escrever aqui. Todo o resto entra read-only. Dentro de ~/.config, subdiretórios de browser são escondidos atrás de tmpfs: BraveSoftware, Bitwarden. Mesma coisa em ~/.cache: BraveSoftware, chromium, spotify, nvidia. O agente não consegue nem ver que esses diretórios existem.

O diretório corrente do projeto é o único lugar com permissão de escrita (além dos dotdirs de ferramentas). O agente modifica o código, mas não toca no resto.

macOS: sandbox-exec

No macOS, o backend é o sandbox-exec com profiles SBPL (Sandbox Profile Language). É uma API legada da Apple, depreciada oficialmente mas sem substituto público. Funciona hoje, mas a Apple pode remover no futuro.

O ai-jail gera um profile SBPL em runtime que replica a mesma lógica do Linux:

• Default deny em tudo
• Permite operações de processo (exec, fork, signal)
• Permite rede (exceto em lockdown)
• Permite leitura global, nega paths sensíveis (.gnupg, .aws, .ssh, ~/Library/Keychains, ~/Library/Mail)
• Permite escrita só em diretório do projeto, dotfiles de ferramentas, e /tmp

As limitações são reais. GPU (Metal) e Display (Cocoa) são system-level no macOS, sandbox-exec não consegue restringir. As flags --no-gpu e --no-display simplesmente não têm efeito no macOS. A paridade entre plataformas é aproximada, não exata.

Mesmo com essas limitações, é melhor do que rodar o agente completamente aberto. O sandbox-exec protege contra acesso a filesystem sensível e, em lockdown, remove permissões de escrita e rede.

Windows: Não Suportado (E Provavelmente Nunca Será)

Não é falta de vontade, é falta de primitivas. Windows não tem equivalente userspace a Linux namespaces. Não tem mount API como bubblewrap. AppContainers existem mas usam um modelo de segurança completamente diferente, requerem privilégios de admin, e mapear a funcionalidade do bwrap pra AppContainers seria efetivamente escrever outro projeto do zero.

A solução pra Windows é WSL 2:

# No WSL 2 (kernel Linux real)
sudo apt install bubblewrap
cargo install ai-jail
# ou: mise use -g ubi:akitaonrails/ai-jail

cd /mnt/c/Users/voce/Projects/meu-app
ai-jail claude

WSL 2 roda um kernel Linux de verdade. Bubblewrap funciona normalmente. Os arquivos do Windows ficam acessíveis em /mnt/c/. Performance de I/O é mais lenta pelo mount de 9p, mas funciona. Pra projetos grandes, clonar dentro de ~/Projects/ no lado Linux melhora a performance consideravelmente.

Lockdown Mode

Pra workloads que você realmente não confia, existe --lockdown:

ai-jail --lockdown bash

Lockdown faz tudo que o modo normal faz, mas vai além. O projeto é montado read-only (não read-write). GPU, Docker, Display e mise são desabilitados. Flags --rw-map e --map são ignoradas. $HOME vira tmpfs puro, sem dotfiles do host. No Linux, a rede é cortada com --unshare-net e o ambiente é limpo com --clearenv. No macOS, as variáveis de ambiente são limpas e as regras de escrita e rede são removidas do SBPL.

É o sandbox mais restritivo que dá pra fazer sem usar uma VM. Útil pra auditar código de terceiros ou rodar agentes em projetos que você não conhece.

Bootstrap: Configuração Automática de Permissões

ai-jail --bootstrap gera configurações de permissão pras ferramentas que você usa:

ai-jail --bootstrap

Pro Claude Code, gera ~/.claude/settings.json com listas de allow/deny/ask. Permite git status, diff, log, ls, grep, cargo, npm, python, docker compose. Bloqueia rm -rf, sudo, chmod 777, git push –force. Pergunta antes de git push, rm, docker run.

Pro Codex, gera ~/.codex/config.toml com approval_policy = "on-request".

Pro OpenCode, gera ~/.config/opencode/opencode.json com permissões de bash, edit, write.

Antes de sobrescrever qualquer arquivo, faz backup automático (settings.json.bak). E rejeita operações se o alvo for um symlink, pra evitar path traversal.

É exatamente o conteúdo que eu coloquei manualmente no post anterior, mas automatizado e testado.

Mas o Claude Code Já Tem Sandbox Próprio

Tem. Desde outubro de 2025, o Claude Code oferece um sandbox runtime via o comando /sandbox. E adivinhe o que ele usa por baixo? Bubblewrap no Linux e sandbox-exec no macOS. O mesmo stack.

Mas as diferenças importam.

ai-jail é agnóstico de ferramenta. Funciona com Claude, Codex, OpenCode, Crush, e qualquer comando. O sandbox do Claude só protege o Claude. Se amanhã você trocar de agente, o ai-jail continua funcionando igual.

O ponto que mais me incomoda é o escape hatch. Quando um comando falha por restrição de sandbox, o Claude pode tentar novamente com dangerouslyDisableSandbox, caindo de volta no fluxo normal de permissões. Dá pra desabilitar isso ("allowUnsandboxedCommands": false), mas é opt-out, não opt-in. No ai-jail, não existe escape hatch. O processo roda dentro do bwrap ou do sandbox-exec, ponto. Não tem como o agente decidir sozinho sair do sandbox.

Outra diferença prática: o .ai-jail vive no diretório do projeto e pode ser commitado no repositório. Qualquer dev que clona o projeto herda a mesma política de sandbox. O sandbox do Claude depende de settings.json global.

Quando roda dentro de Docker, o sandbox do Claude cai pra um modo enableWeakerNestedSandbox que, nas palavras da própria documentação, “considerably weakens security”. O ai-jail não foi projetado pra rodar dentro de Docker (ele roda diretamente na workstation do dev), então esse problema não existe.

Sobre rede: o sandbox do Claude roteia tráfego por um proxy e permite/bloqueia por domínio. ai-jail no modo normal herda a rede do host; no lockdown, corta a rede inteira com --unshare-net. A abordagem do Claude é mais granular; a do ai-jail é mais simples e mais difícil de contornar.

Os dois não são mutuamente exclusivos. Dá pra rodar o sandbox do Claude dentro do ai-jail. O ai-jail cuida do isolamento de filesystem; o sandbox do Claude adiciona filtragem de rede por domínio. Layers de segurança se somam.

Por Que Não Usar –dangerously-skip-permissions Sem Jail

Vou ser direto: se você roda Claude Code com --dangerously-skip-permissions sem nenhum sandbox, tá confiando cegamente que a LLM nunca vai executar algo destrutivo. E tá confiando que nenhuma dependência do seu projeto foi comprometida num supply-chain attack.

Toda flag --dangerously tem esse nome por um motivo. O Claude Code é explícito: esse modo existe pra CI/CD e automação em ambientes já isolados (containers, VMs descartáveis). Não pra sua workstation pessoal com ~/.aws/credentials, ~/.gnupg/, SSH keys, e o banco de senhas do seu browser.

Com ai-jail, o agente tem autonomia total dentro do sandbox. Faz o que quiser no diretório do projeto, usa as ferramentas que precisa, e não consegue acessar nada fora do que foi explicitamente permitido.

ai-jail + Git: A Rede de Segurança que Você Já Tem

Tem uma coisa que eu não mencionei ainda e que muda o cálculo de risco: se o seu projeto tá num repositório Git, com remote no GitHub/GitLab, e o agente não tem permissão de git push, o dano que ele consegue causar é limitado ao diretório local.

Pense assim. O pior cenário dentro do ai-jail é o agente corromper todos os arquivos do projeto. Irritante? Sim. Catastrófico? Não. Você faz git checkout . e volta ao último commit. Se ele corromper o .git de alguma forma (improvável, mas possível), você deleta o diretório e clona de novo. O remote não foi tocado.

Por isso o --bootstrap do ai-jail coloca git push na lista de “ask” (perguntar antes), não na lista de “allow”. E git push --force vai direto pra “deny”. O agente pode commitar à vontade localmente, pode criar branches, pode fazer rebase. Nada disso afeta o remote. Quando chega na hora de push, você revisa o que ele fez e decide se vai pro ar.

Essa combinação, sandbox pra filesystem + Git pro código + push manual, já te dá um nível de segurança muito razoável pro dia a dia. O ai-jail protege seus dados pessoais e o sistema. O Git protege seu código. E a decisão de publicar continua sendo sua.

Se quiser ir além, as próximas duas seções cobrem camadas adicionais.

ai-jail vs Dev Containers

Desde que escrevi o ai-jail, a pergunta mais frequente é: “por que não usar Dev Containers?”. A resposta curta é que um não substitui o outro. Resolvem problemas diferentes.

Dev Containers (a spec do containers.dev) define um ambiente de desenvolvimento completo num devcontainer.json. Você especifica imagem base, ferramentas, extensões do VS Code, variáveis de ambiente, e o editor monta tudo pra você num container Docker. O Docker também lançou recentemente os Docker Sandboxes, que vão além e rodam cada agente numa microVM com Firecracker, com isolamento de hardware.

ai-jail não faz nada disso. Ele não define ambiente. Não instala ferramentas. Não roda imagem Docker. Ele pega o ambiente que já existe na sua máquina e restringe o que o processo pode acessar.

Na prática, a diferença é:

Dev Container faz mais sentido quando você precisa que todo o time tenha exatamente o mesmo ambiente, ou quando o projeto tem dependências que ninguém quer instalar no host, ou pra rodar agentes não-interativos em CI/CD. Docker Sandboxes com microVM são o isolamento mais forte que existe fora de uma VM dedicada.

ai-jail faz mais sentido quando você já tem o ambiente configurado e quer startup instantâneo sem Docker daemon. Ou quando usa ferramentas que são chatas de rodar dentro de container (CUDA, Wayland, mise). Ou simplesmente quando quer a mesma proteção pra qualquer agente, não só os que têm integração com devcontainer.

E dá pra combinar. Eu conheço gente que roda ai-jail dentro de um Dev Container pra ter reprodutibilidade de ambiente + restrição de filesystem. Layers de segurança se somam.

Sistemas Operacionais Imutáveis: A Última Camada

Se você quer levar a segurança a sério, a terceira camada é o sistema operacional em si.

Sistemas imutáveis como Fedora Silverblue, NixOS, e openSUSE Aeon têm o filesystem raiz read-only. O sistema base não pode ser modificado por nenhum processo, nem com root. Atualizações são atômicas: ou aplicam completamente ou não aplicam. E se algo der errado, você faz rollback pra imagem anterior em um reboot.

Na prática, isso significa que mesmo se um agente de IA escapasse do sandbox (exploiting uma vulnerabilidade no kernel, por exemplo), ele não conseguiria modificar o sistema de forma persistente. No próximo reboot, o sistema volta ao estado declarado. No NixOS, o sistema inteiro é definido por um arquivo de configuração (configuration.nix). No Silverblue, o base é uma imagem OSTree que recebe updates atômicos via rpm-ostree.

Pra desenvolvedores, a pegada é: suas ferramentas de dev rodam em containers (Toolbox/Distrobox no Silverblue, nix-shell no NixOS). O sistema base fica intocado. Apps desktop vêm via Flatpak, que já roda em sandbox. O resultado é que a superfície de ataque do host é mínima.

Fedora Silverblue é provavelmente a entrada mais acessível. Já é Fedora por baixo, com GNOME, funciona com hardware que Fedora suporta, e o Toolbox te dá um Fedora Server containerizado onde você instala o que quiser sem tocar no host. NixOS é mais poderoso (reprodutibilidade total, rollback declarativo), mas a curva de aprendizado é real.

A combinação completa fica assim: o OS imutável cuida do sistema (filesystem read-only, updates atômicos, rollback em um reboot). O ai-jail cuida da sessão (namespace isolado, home efêmero, dados sensíveis invisíveis). E o Git cuida do código (remote intocado enquanto o agente não tiver push).

Nenhuma dessas camadas é perfeita sozinha. Mas o ataque que fura as três ao mesmo tempo — escapar do namespace, persistir num filesystem read-only, e corromper um remote Git — é um cenário que eu ficaria confortável chamando de improvável.

O melhor é que nenhuma exige mudar como você trabalha. O ai-jail é um comando antes do seu agente. Git você já usa. E um OS imutável é uma instalação, não uma mudança de workflow.

Detalhes Técnicos (Pra Quem Se Importa)

Escrito em Rust com 124 testes e 4 dependências: lexopt (parsing de CLI sem clap), serde + toml (config), nix (syscalls Unix). Sem runtime async, sem framework de cores (ANSI direto), binary de ~880KB com LTO e strip.

O signal handling é feito corretamente: SIGINT, SIGTERM, e SIGHUP são forwarded pro processo filho. O handler só chama libc::kill, que é async-signal-safe. O reaping do processo usa waitpid em loop com retry em EINTR.

Arquivos temporários (como o /etc/hosts customizado que o sandbox monta) usam RAII: um SandboxGuard que implementa Drop em Rust. Se o processo pai morrer por qualquer razão, o cleanup acontece.

A compatibilidade de configuração é garantida por política de desenvolvimento: nunca remover campos, nunca renomear, campos novos sempre com #[serde(default)], campos desconhecidos são silenciosamente ignorados. Testes de regressão pra formatos antigos de .ai-jail garantem que atualizar o binário nunca quebra configs existentes. São 32 testes só de config.

Roadmap

O que falta:

• Mais backends de ferramentas no bootstrap: Aider, Cursor, Windsurf. Conforme mais agentes padronizarem arquivos de configuração de permissão.
• Profile sharing pra monorepos, pra não ter que configurar cada serviço separadamente.

Instalação e Primeiro Uso (Resumo Rápido)

# 1. Instalar
brew tap akitaonrails/tap && brew install ai-jail
# ou: cargo install ai-jail

# 2. No Linux, instalar bubblewrap
sudo pacman -S bubblewrap  # Arch
# sudo apt install bubblewrap  # Debian/Ubuntu

# 3. Entrar no projeto e rodar
cd ~/Projects/meu-app
ai-jail claude

# 4. (Opcional) Gerar configs de permissão
ai-jail --bootstrap

# 5. (Opcional) Ver o que o sandbox faz
ai-jail --dry-run --verbose claude

O .ai-jail criado pode ser commitado no seu repo. A partir daí, qualquer dev que clonar o projeto roda ai-jail claude e tem o mesmo sandbox.

Conclusão

O shell script de janeiro resolveu o problema. O ai-jail resolve o problema direito. Config por projeto, suporte a macOS, lockdown mode, bootstrap de permissões, dry-run pra auditar, e um binário de 880KB que instala em 10 segundos.

Se você usa agentes de IA pra programar, rode eles num sandbox. A boa vontade da LLM não é garantia de nada, e supply-chain attacks não escolhem vítima. Isolamento de processo é a barreira que funciona.

O projeto é GPL-3.0 e tá no GitHub: github.com/akitaonrails/ai-jail

Issues e PRs são bem-vindos.

Meu interesse é simples. Rust é uma linguagem pequena, mais próximo da categoria de C ou Objective-C do que GoLang, ou Elixir. Uma das coisas que sempre podemos fazer para “vitaminar” nosso querido Ruby é criar extensions em C. Mas se você já tentou fazer isso, sabe que nem é tão complicado com pequenas coisas à la “hello world”, mas a coisa pode ficar exponencialmente complicada com muitas dependências e complexidades de toolchains. Então minha intenção em aprender Rust é ver se ela pode ser uma boa alternativa para criar extensions nativas performática facilmente consumíveis via FFI (Foreign Function Interface).

Este artigo é apenas um pequeno exercício que vai além de um simples “hello world”, que seria absolutamente trivial. Quero fazer uma pequena biblioteca capaz de ler um arquivo de tamanho arbitrário (portanto não pode carregar tudo em memória) e fazer um parse com regular expressions (algo que fazemos comumente).

Para isso estou usando como teste um arquivo de atores de filmes que baixei do FTP do IMDB, em particular o arquivo “actors.tgz” que abre como “actors.list”. De cara vou dizer que é um dump bem porcaria, cujo texto sequer está em UTF-8. E para os efeitos deste artigo eu fiz uma versão menor com somente as primeira 10 mil linhas dele, que é um mísero arquivo de 515kb (comparado aos 938MB originais). Poderia ser qualquer arquivo, mas aleatoriamente escolhi esse.

Coloquei o projeto no meu Github como exercício (contribuições são bem vindas, pra melhorar o exemplo). Em Ruby, o código é simplesmente algo assim:

def find_actors(filename, skip_lines, target_movie)
  actors = []
  actor = nil
  File.foreach(filename).with_index do |line, line_num|
    next if line_num < 239
    line.encode!(line.encoding, 'binary', invalid: :replace, undef: :replace)
    if line.strip == ''
      actor = nil
      next
    end
    slices = line.split(/\t/)
    actor_buffer = slices.first
    movie        = slices.last
    if actor.nil? && !actor_buffer.nil? && actor_buffer != ''
      actor = actor_buffer
    end
    if !movie.nil? && movie.include?(target_movie)
      actors << actor unless actors.include?(actor)
    end
  end
  actors.join("\n")
end

Dá pra melhorar isso, mas é o suficiente para nossos propósitos. Rodando contra o arquivo pequeno de exemplo, o resultado vai ser:

> ruby actors.rb                                                                                                                               running pure Ruby version
145, Lyric
3, Utai
4 Real
4Shore
4Sure
4th Ba5e
4Tune
50 Cent
  0.050000   0.000000   0.050000 (  0.060104)

Se você baixar meu código do repositório, primeiro garanta que você tem o Rust instalado. Pra isso basta executar o seguinte:

curl -sSf https://static.rust-lang.org/rustup.sh | sh

Quando baixar meu código, vai ver que ele tem os arquivos Cargo.toml e Cargo.lock. Eles são semelhantes ao nosso Gemfile/Rakefile e Gemfile.lock. No Ruby controlamos nossas tarefas com Rake, as gems com Bundler (que lê as versões exatas do Gemfile.lock) e normalmente baixamos dependências que são Rubygems do Rubygems.org.

No caso do Rust, ele controla tanto tarefas (build, teste) e declaração de dependências via o arquivo Cargo.toml (TOML sendo uma alternativa mais moderna a YAML). Em vez de Rake e Bundler temos Cargo. Em vez de Rubygems temos Crates. E em vez de Rubygems.org temos Crates.io.

Sendo uma linguagem que compila binários nativos, executamos cargo build mas se fizermos diretamente cargo test (para rodar testes incluídos no código) ou cargo run (para rodar o binário executável que fica no diretório bin/) ele vai automaticamente fazer a compilação do que precisa. No nosso caso, como estamos gerando uma biblioteca (que poderia ser um “.so” para Linux, ou um “.dylib” pra Mac ou “*.dll” para Windows), ele compila por padrão no diretório target/debug (que vai ser mais lento por ter símbolos pra debug e outros suportes). Para gerar a versão final, precisa executar cargo build –release e rodar como cargo run –release que vai gerar e linkar do binário em target/release.

Isso tudo dito, dê uma olhada nos arquivos Cargo.toml, src/main.rs, src/lib.rs. Os arquivos de Ruby estão misturados e são os actors.rb, imdb.rb. Pra executar a versão Ruby, lembre-se de também rodar gem install ffi primeiro (não estou usando Bundler nesse exercício).

O Código Rust

Agora vamos olhar o código Rust equivalente ao Ruby anterior:

use std::io::prelude::*;
use std::io::BufReader;
use std::fs::File;

extern crate regex;
use regex::Regex;

pub fn find_actors(filename: String, skip_lines: usize, target_movie: String) -> String {
    let file = File::open(filename).unwrap();
    let mut reader = BufReader::new(&file).lines().skip(skip_lines);

    let mut actor = String::new();
    let mut actors : Vec<String> = Vec::new();
    let regex = Regex::new(r"^(.*?)\t+(.*?)$").unwrap();
    loop {
        let line = match reader.next() {
            Some(line) => match line {
                Ok(line) => line,
                Err(_)   => String::new(),
            },
            None => break,
        };

        match regex.captures(&line) {
            Some(captures) => {
                let actor_buffer = captures.at(1).unwrap();
                let movie        = captures.at(2).unwrap();

                if actor.is_empty() && !actor_buffer.is_empty() {
                    actor = actor_buffer.to_string();
                }

                if !movie.is_empty() && movie.contains(&target_movie) && !actors.contains(&actor) {
                    actors.push(actor.to_string());
                }
            },
            None => {
                actor = String::new();
            }
        };
    }
    actors.connect("\n")
}

Essa função usa coisas do próprio Rust que importamos dos módulos str::io e std::fs e tem a Crate regex externa. Também exportamos esse módulo com o nome de “imdb” que é o declaramos no Cargo.toml:

[package]
name = "actors"
version = "0.1.0"
authors = ["vagrant"]

[lib]
name = "imdb"
path = "src/lib.rs"
crate-type = ["rlib", "dylib"]

[dependencies]
regex = "0.1.8"
libc = "0.1.8"

Eu removi um trecho do arquivo que vou explicar na próxima seção, sobre FFI. Por enquanto vamos nos ater a esse código.

A sintaxe em si não deve ser tão assustadora num primeiro momento. As coisas estranhas vão exigir algum estudo.

• O Rust tem tipos e eles são declarados. O compilador usa inferência de tipos então não precisa declarar tudo o tempo todo como em Java. Ao contrário de Ruby, Rust não é orientado a “objetos”. Ele tem structs e funções declaradas pra essas structs. Cada struct pode implementar funções declaradas em Traits, que funcionam mais ou menos como Interfaces ou Protocolos (em Swift/Obj-C). Leia outro artigo sobre Trait aqui.

• Existe o conceito de Generics. Por isso a sintaxe de Vec que declara um Vetor com cada elemento sendo um String. Vetores são muito usados, então estude a respeito, mas é basicamente um Array de tamanho dinâmico (que pode receber novos elementos, possivelmente uma lista ligada).

• Falando em Strings, existe a struct String e a primitiva ‘str’. Um “hello world” é um ‘str’ que pode virar um String se fizermos “hello world”.to_string().

• Em Rust, todos bindings de variáveis são imutáveis. Para torná-la mutável precisamos declarar explicitamente com let mut como no exemplo acima. Leia mais sobre Variable Binding. Em particular, isso leva aos conceitos de Ownership/Propriedade de uma variável, Borrowing/Empréstimo de variáveis entre escopos diferentes, como passar para uma função e Lifetime/Tempo de Vida de uma variável. Vou adiantar que esse é um dos conceitos que pode levar mais tempo para se acostumar.

Rust não tem garbage collector como em Ruby ou Java. Primeiro, porque ele usa primariamente o Stack em vez do Heap. Stack é uma pilha. Toda chamada de função empilha as variáveis que usa em seu espaço. Quando chama uma nova função ele empilha isso acima de si com suas variáveis. Quando a última função retorna, ele pode limpar as variáveis que alocou (que são sua “propriedade”). Se precisamos passar uma variável de uma função para a função seguinte podemos ou “copiar” o valor (normvalmente o que se faz com primitivas como i32 ou f64 - que são inteiros de 32bits ou floats de 64-bits, dentre outros tipos primitivos) ou podemos “mover a propriedade”, por exemplo:

let x = "hello".to_string();
let y = x;
println!("{}", x); // vai dar pau, porque movemos a propriedade de "x" para o "y"

Ou “emprestar”. Empréstimos são declarados com “&” (’e’ comercial) e somente podemos emprestar uma única vez como em let y = &x. Sim, essa mecânica vai demorar mais pra se entender se você só conhece linguagens como Ruby ou Javascript. Se você aprendeu Objective-C antes do advento do ARC, já teve que parar pra pensar nesse tipo de ciclo de vida de retain/copy/release.

Outros artigos como este ou este podem ajudar. O objetivo dessa mecânica é para justamente evitar possibilidades de leaks de memória, ter desalocação determinística, usar a menor quantidade de memória quanto possível. Tecnicamente, não deveria haver leaks de memória óbvios em Rust. E não ter a lógica de Garbage Collection elimina uma das maiores complexidades que temos em linguagens mais modernas que contam com uma VM, o que facilita o uso do Rust para mais usos de sistema mais de baixo nível.

• Você vai ver várias chamadas a unwrap(), isso pode ser estranho. Então veja esta linha em específico:

let regex = Regex::new(r"^(.*?)\t+(.*?)$").unwrap()

Isso é só um jeito mais curto pra:

let regex = match Regex::new(r"^(.*?)\t+(.*?)$") {
    Ok(regex) => regex,
    Err(_) => panic!("invalid regex"),
};

O match é a avaliação de um Pattern Matching sobre um tipo chamado core::result::Result que é a alternativa do Rust de evitar retornar códigos de erro (como em C) ou usar um sistema de exceptions (como em Ruby mesmo). Nesse caso a criação de uma struct de Regex pode dar certo ou errado. Se der certo teremos o resultado voltando como “Ok”, se der errado voltará como “Err(e)” e podemos fazer alguma coisa com o erro ou parar tudo como no exemplo, chamando a macro “panic!”. O método unwrap implementa exatamente essa lógica se não estamos interessados em tratar o erro.

Em conjunto com o conceito de Result, temos Option Monads (implementado como core::option::Option), também conhecidos como tipos “Maybe” que devolvem “Some” (algum valor) ou “None” (nenhum valor), que é a resposta do Rust pra não ter que lidar com Null. Em Ruby, como existe a classe NilClass, podemos criar ferramentas como NullObjects onde um “Maybe” devolve esse NullObject/None ou o valor em si, “Some”.

Veja a biblioteca Naught pra entender mais do conceito.

Em resumo isso significa que você vai ver muito códigos com “unwrap” e “match” lidando com “Ok/Err” ou “Some/None”. Sendo honesto, ainda não estou tão seguro das melhores práticas de quando e como usar isso e definitivamente é um tópico que vou estudar mais.

Veja que tanto no reader.next(), que é pegando o próximo elemento o Iterador do Regex quanto o regex.captures() que faz o match da Regex contra o string da linha devolvem o tipo “Option” e usamos “match” para saber o que fazer. No primeiro caso, se não houver um próximo elemento no iterador, ele devolve “None” e sabemos que podemos sair (break) do loop. E no segundo caso, se a linha sendo processada não bater com a regex, ele devolve “None” e sabemos que acabou o bloco do ator corrente, então podemos zerá-la antes de começar o próximo ator.

• O resto do código depois do “captures()” é a mesma lógica que em Ruby, de checar linha do arquivo, dividir entre nome do ator e seus filmes, acumular o nome do último ator (porque no formato do arquivo um ator tem vários filmes, um em cada linha), e ir acumulando os nomes no Vetor/Array. No final simplemente pegamos todos os nomes e concatenamos com um “\n”.

Este código não lida com alguns conceitos mais interessantes do Rust como Threads. Recomendo, no mínimo, ler toda a documentação oficial no site do Rust para entender esses e mais dos conceitos importantes.

Exportando para consumo em FFI

A maioria dos exemplos que achamos primeiro usando o Google, são códigos simples. Estou usando direto a gem FFI em vez de usar a Fiddle, então saibam que existem duas maneiras.

Sem mais delongas, no mesmo arquivo src/lib.rs eu coloquei o seguinte:

extern crate libc;
use libc::c_char;
use std::ffi::{CString, CStr};

#[no_mangle]
pub extern "C" fn ffi_find_actors(filename_ptr: *const c_char, skip_lines: i32, target_movie_ptr: *const c_char) -> *const c_char {
    let filename = unsafe {
        CStr::from_ptr(filename_ptr)
    };
    let target_movie = unsafe {
        CStr::from_ptr(target_movie_ptr)
    };
    let result = find_actors(
        std::str::from_utf8(filename.to_bytes()).unwrap().to_string(),
        skip_lines as usize,
        std::str::from_utf8(target_movie.to_bytes()).unwrap().to_string()
        );
    CString::new(result).unwrap().as_ptr()
}

Ou seja, eu fiz uma nova função que consome a que analisamos antes. A que fizemos primeiro recebe structs String e devolve uma String, que são structs de Rust. Não entendi ainda como converter isso automaticamente para ser consumido externamente. Então essa função acima recebe de fora do Rust um ponteiro para uma lista de chars (que é o conceito original de uma “string”/“corrente”), pega o ponteiro, pega os bytes do local onde o ponteiro aponta, e cria uma ‘str’ UTF-8, e finalmente chama ’to_string()’ pra gerar uma String de Rust.

Então ele pega o resultado, que é uma String, cria um CString (que vem do módulo “std::ffi”), ou seja, uma “String de C” e devolve o ponteiro para fora. Note que nos casos onde recebemos ponteiros, declaramos que é um bloco “unsafe”.

A diretiva #[no_mangle] é para o compilador do Rust manter e não bagunçar o nome da função internamente. E pub extern é para declará-la disponível para ser usado publicamente e externamente.

Sinceramente, não sei se essa é a forma correta de se expôr uma função. Provalvemente de um jeito melhor e mais simples, mas ainda não encontrei. Se alguém souber como, não deixe de colocar nos comentários.

Então, do lado do Ruby, consumimos desta forma:

require 'ffi'

module RustWorld
  extend FFI::Library
  ffi_lib 'target/release/libimdb.so'
  attach_function :ffi_find_actors, [:string, :int, :string], :string
end

Note que estamos fazendo link com a versão de “release” gerado via cargo build –release. E então declaramos a assinatura da função que queremos usar.

Finalmente, podemos usar dentro do Ruby normalmente assim:

RustWorld.ffi_find_actors(filename, 239, target_movie)

Comparação de Performance

Aqui vem uma pequena surpresa. Eu fiz esse código com uma versão em Ruby e outra em Rust, lendo e processando o mesmo arquivo, para obter o mesmo resultado final. O que tive foi o seguinte:

RUST=1 ruby actors.rb                                                                                                                         0.070000   0.010000   0.080000 (  0.079534)

ruby actors.rb                                                                                                                                0.060000   0.000000   0.060000 (  0.057541)

Ou seja, a versão Ruby é um pouco mais rápido que a versão em Rust, por uma margem de 27% (!!). Esses tempos foram marcados internamente dentro do Ruby (consumindo o Rust via FFI) com a biblioteca Benchmark.

E medindo diretamente, calculando o tempo com a função “time”:

time cargo run --release                                                                                                                    cargo run --release  0.11s user 0.04s system 99% cpu 0.156 total

time ruby actors.rb                                                                                                                         ruby actors.rb  0.28s user 0.03s system 98% cpu 0.311 total

Aqui vemos o Ruby sendo mais lento. Como o arquivo de testes é muito pequeno, o tempo de subir o Ruby interfere na medição. Então vamos tentar com outro arquivo maior, com 52MB em vez de meros 515k:

time cargo run --release
cargo run --release  7.04s user 0.11s system 99% cpu 7.184 total

time ruby actors.rb
ruby actors.rb  6.69s user 0.08s system 99% cpu 6.808 total

Ou seja, o Ruby ainda é mais rápido que a versão Rust. E aqui podemos ficar confusos: o Rust, sendo muito mais próximo de C do que de Ruby, não deveria ser algumas ordens de grandeza mais rápido?

O código em si é muito simples. O primeiro ponto é que ele depende mais de I/O (ler o arquivo). E nisso o Ruby é muito rápido pois essa lógica é implementada internamente em C.

A segunda parte que eu imagino mais pesada é processar a Regex linha a linha. E nesse caso a engine de Regex do Ruby é bastante rápida, também internamente sendo feita em C - mais do que isso, ela é madura, tendo passado por inúmeras reescritas e refatoramentos nos últimos anos. E a biblioteca Regex do Rust eu imagino que, por ser ainda imatura, tem muito a ser otimizada e isso está segurando os números.

Outra coisa: é um processamento sequencial, linear, do arquivo. Se gastássemos mais tempo em particionar o arquivo e rodar pedaços em paralelo para maximizar o uso da máquina, imagino que o Rust talvez tivesse alguma vantagem, mas mesmo nesse caso usaríamos alguma coisa como a biblioteca Grosser/Parallel do Ruby, como já expliquei em outro artigo, pra conseguir também com Ruby usar todas as CPUs da máquina.

Na verdade, o problema não é o Rust ser “lento” mas subestimarmos o Ruby achando que ele sempre vai ser lento em tudo quando na verdade não é o caso. Faça a lição de casa antes de assumir que algo é lento ou rápido, você vai se surpreender em ver como Ruby é muito - e rápido - em diversos tipos de tarefas que à primeira vista parece que não. E não considerem que “Rust” é ruim por causa deste teste: é um caso de uso específico, que depende mais da forma como a biblioteca de Regex (possivelmente) amadureceu até este ponto.

Obs 05/06/15: Logo após publicar o post o camarada Jeffry DeGrande mandou um Pull Request que troca a lenta crate “regex” pela “pcre” que, como seu nome diz, linka por baixo com a boa e velha biblioteca nativa “libpcre3” (Perl Compatible Regular Expression). Com isso os tempos ficam Muito melhores:

> RUST=1 ruby actors.rb
running Rust/FFI version
  1.600000   0.010000   1.610000 (  1.625171)

> ruby actors.rb
running pure Ruby version
  5.980000   0.050000   6.030000 (  6.046123)

Como eu suspeitava, a culpada era mesmo a biblioteca imatura de regex. Trocando pela pcre a implementação em Rust fica na menos que 3.7 vezes mais rápida que a em Ruby, que seria um tempo que deveríamos mesmo esperar de uma linguagem compilada!

Conclusão

Rust atingiu sua versão 1.0 em Maio de 2015, ou seja, poucos dias atrás. Significa que muita coisa que você encontrar na Web, blogs, foruns, estarão defasados. Eu tive muita dificuldade em encontrar bons exemplos de código que funcionam na versão 1.0. Algumas structs mudaram de módulo. Alguns métodos estão com assinaturas diferentes e retornando coisas diferentes. A própria documentação oficial está com alguns erros ainda. Então tenha um pouco de paciência pois é a partir de agora com bons materiais vão começar a surgir.

Quem investiu tempo em aprender C/C++ (ou pelo menos Objective-C pré-ARC) não vai estranhar tanto assim o modelo de gerenciamento de memória do Rust. A idéia de ownership/borrowing não é tão diferente assim de um retain/release. Só que em vez de contar referências, você só pode “emprestar” uma vez. Além disso os valores são imutáveis, então é um modelo mais simples - embora mais difícil de se adaptar logo de cara. Especialmente importante é entender o modelo de alocar no Stack em vez de na Heap.

Também não há códigos de erro de retorno nem Exceptions. Aprender a lidar com o modelo de Pattern Matching em estruturas de Result/Option é outra mudança na forma de programar. Minha recomendação é abrir códigos fontes de terceiros como o próprio Cargo, para ver como são usados na prática.

Uma das coisas que não toquei neste artigo é seu excelente suporte a concorrência e paralelismo. Leia o exemplo do Dining Philosopher e como o Rust resolve esse clássico problema. É bem simples mesmo entender.

Para quem acha que o mundo é orientado a objetos, Rust é mais uma linguagem que - embora tenha alguma semântica de objetos - não é orientado a objetos. Ele tem structs e funções associadas a structs. Entender o modelo de Traits é crucial.

Rust é uma linguagem compilada, então toda vez que fizer algum código, existe o ciclo de compilar antes de executar, coisa que esquecemos como é no mundo Ruby ou Javascript. Mas a existência do Cargo facilita completamente esse fluxo e torna a experiência mil vezes mais agradável do que no mundo C, onde iríamos ter que mexer com Makefiles ou coisa similar. A organização padrão de projetos gerados pelo Cargo, empacotamentos em Crates e gerenciamento de dependências largamente inspirado no Bundler (que, aliás, todo mundo copia hoje em dia pois é o melhor modelo), ajuda muito ainda mais no começo.

Acompanhem o repositório no Github chamado Awesome Rust que tem diversos links de projetos open source. Outro repositório é o Rust Learning com links para várias documentações importantes para aprender. Existe já o rascunho de um “guideline de estilo”.

Finalmente, Rust não é uma linguagem simples, definitivamente nem um pouco perto de algo como Ruby ou mesmo Elixir. Ele é mais baixo nível e vejo aplicações para coisas em nível de sistema. Ferramentas de linha de comando pra Linux. Bibliotecas para processamento de imagens, processamento numérico. Coisas que possam ser consumidas por outras linguagens ou aplicações, como o exemplo de expor funcionalidades como extensions nativas para Rubygems. Nesse sentido ele é mais seguro em termos de gerenciamento de memória, e com performance de processamento comparável a C++. Então é uma boa chance para programadores de linguagens de alto nível como Ruby ou Swift conseguirem descer para o nível de sistema sem precisar perder a cabeça com a complexidade de C/C++.