project helena · v0.7 · MIT esc
Helena
Uma camada em cima do Claude Code que chega zerada e aprende o seu jeito de trabalhar, carrega skill só quando precisa e só guarda o que o benchmark prova que ajuda. A layer on top of Claude Code that starts blank and learns how you work, loads skills only when they are needed and only keeps what the benchmark proves helps.
a sua helenayour helena
Ela chega zerada. Aprende com você.She arrives empty. She learns from you.
Quando você instala, ela não sabe nada sobre você: nenhuma memória, nenhum kit, nenhuma skill sua. Vem só o mecanismo: os hooks que sempre rodam, a memória que se grava sozinha e o benchmark que decide o que fica. Cada correção sua vira uma nota. Cada procedimento que se repete vira candidato a skill. Quanto mais você usa, melhor ela fica. When you install her, she knows nothing about you: no memories, no kits, none of your skills. Only the machinery ships: hooks that always run, memory that writes itself and a benchmark that decides what stays. Every correction you make becomes a note. Every procedure you repeat becomes a skill candidate. The more you use her, the better she gets.
- dia 1day 10
memórias. Os hooks já protegem: chave de API não sobe pro git, texto ilegível volta pra correção, onde você parou fica no HANDOFF.md.memories. The hooks already protect you: API keys stay out of git, unreadable text goes back for a fix, where you stopped lives in HANDOFF.md.
- semana 1week 1+
Suas correções viram notas no seu Obsidian. A próxima sessão já começa sabendo.Your corrections become notes in your Obsidian vault. The next session starts already knowing.
- mês 1month 1++
Kits do seu jeito: a skill certa entra quando o pedido precisa e fica fora quando não precisa.Kits shaped like your work: the right skill comes in when a request needs it and stays out when it does not.
- semprealways=
Skill candidata só entra se ganhar no benchmark. O que empata sai, porque contexto custa.A skill candidate only gets in if it wins the benchmark. Ties go out, because context costs.
/helena:remember <fatofact> # ensina algo agorateach her something now /helena:forget <fatofact> # apaga o que estiver erradoremove what is wrong /helena:status # mostra o que ela já sabeshow what she knows so far /helena:budget # quanto ela gasta e quanto economizawhat she costs and what she saves /helena:skills # as skills que ela criou sozinhathe skills she created on her own /helena:undo <skill> # apaga uma skill que ela crioudelete a skill she created
Tudo que ela aprende fica nas suas pastas (o seu cofre do Obsidian e ~/.helena), nunca dentro do plugin. Atualizar não apaga nada. Everything she learns stays in your folders (your Obsidian vault and ~/.helena), never inside the plugin. Updating never wipes it.
por que existe · a helena do criadorwhy it exists · the creator's helena
Eu estava ensinando a mesma coisa toda semana.I kept teaching the same thing every week.
Li todas as minhas sessões com o Claude Code, em 15 projetos. O padrão era sempre o mesmo: eu corrigia, a IA acertava e, na sessão seguinte, esquecia. Eu tinha uns 60 skills instalados e quase nenhum era chamado na hora certa. Ter skill não basta. Ela precisa aparecer quando o pedido precisa dela, e sair quando não ajuda. I read every Claude Code session I had, across 15 projects. The pattern never changed: I corrected the AI, it got it right, and the next session it forgot. I had about 60 skills installed and almost none were called at the right time. Having a skill is not enough. It has to show up when the request needs it, and leave when it does not help.
O QUE EU MAIS PEDIAWHAT I ASKED FOR THE MOST
O QUE EU CORRIGIA DE NOVO E DE NOVOWHAT I CORRECTED OVER AND OVER
"Não tem chave do Gemini, usa o agy.""There is no Gemini key, use agy."
3 projetos. Hoje é uma skill de 20 linhas.3 projects. Now a 20-line skill."Continua de onde a gente parou.""Pick up where we left off."
Cada vez um arquivo com nome diferente. Hoje o HANDOFF.md entra sozinho.A different file name every time. Now HANDOFF.md loads by itself."Algumas letras estão difíceis de ler.""Some text is hard to read."
6 vezes. Hoje um hook mede o contraste antes de entregar.6 times. Now a hook measures contrast before delivery."Não commita na main, cara.""Don't commit to main, man."
A regra muda por projeto. Hoje fica em .helena/git e o hook cobra.The rule changes per project. Now it lives in .helena/git and a hook enforces it."Nada de API key, autentica pelo CLI.""No API keys, authenticate through the CLI."
Virou memória no Obsidian.Became a memory note in Obsidian.
Isso é o que a minha Helena aprendeu comigo. A sua começa do zero e vai aprender outras coisas: as suas. That is what my Helena learned from me. Yours starts from zero and will learn other things: yours.
como funcionahow it works
Você ensina uma vez. Ela não esquece.You teach it once. It does not forget.
- 01ObservaObserve
Lê o seu histórico e acha o que você repete e o que você corrige. Segredo sai mascarado.Reads your history and finds what you repeat and what you correct. Secrets come out masked.
mine.py - 02LembraRemember
Uma nota por fato no seu Obsidian. Entra no início de cada sessão e é gravada sozinha no fim.One note per fact in your Obsidian vault. Loaded when a session starts, written by itself when it ends.
vault/Memory - 03CarregaLoad
Skills ficam fora do contexto até o pedido precisar: site, 3D, vídeo, segurança, pagamento.Skills stay out of context until a request needs them: web, 3D, video, security, payments.
~/.helena/kits.json - 04ProvaProve
Cada tarefa roda com e sem a Helena. Skill que não ganha sai, porque contexto também custa.Every task runs with and without Helena. A skill that does not win is removed, because context costs too.
eval/run.py
em segundo planoin the background
Ela trabalha sozinha.She works on her own.
No máximo uma vez a cada 20 horas, no Haiku, ela arruma a casa. Cada centavo gasto fica anotado e aparece no /helena:budget, ao lado do que ela economizou. At most once every 20 hours, on Haiku, she tidies up. Every cent she spends is logged and shows up in /helena:budget, next to what she saved.
- 01Cria skillsCreates skills
Pedido repetido 20+ vezes, ou 5+ vezes em 2+ sessões, vai pro Haiku. Ele só escreve a skill se houver um procedimento de verdade. A skill entra na biblioteca, você é avisado com o comando pra apagar, e se ninguém usar por 30 dias ela sai.A request repeated 20+ times, or 5+ times across 2+ sessions, goes to Haiku. It only writes a skill if there is a real procedure. The skill goes to the library, you get a notice with the command to delete it, and if nobody uses it for 30 days it is removed.
/helena:undo - 02Desliga pluginsTurns off plugins
Plugin que um projeto nunca usa é desligado só naquele projeto. Pediu algo que precisa dele ("vamos pôr um gateway de pagamento" → Stripe) e ela liga de novo; vale ao reiniciar a sessão. Plugin com hook nunca é desligado.A plugin a project never uses is switched off in that project only. Ask for something that needs it ("let's add a payment gateway" → Stripe) and she turns it back on; it applies when the session restarts. Plugins with hooks are never switched off.
.claude/settings.local.json - 03Anota o projetoKeeps a hub
Uma nota por projeto no seu Obsidian: como ele está agora e o registro de decisões e commits.One note per project in your Obsidian vault: what it is like now, and a log of decisions and commits.
vault/Projects
economiasavings
Menos contexto. Mesmo resultado.Less context. Same results.
Em 7 dias e 3.030 mensagens, medimos 243k tokens de contexto por mensagem, dos quais só 39k eram fixos. O resto é histórico que cresce a cada fala. Por isso ela corta nas duas pontas: skills ficam numa biblioteca até o pedido precisar, e a sessão é mantida curta. Over 7 days and 3,030 messages we measured 243k tokens of context per message, only 39k of them fixed. The rest is history that grows with every message. So she cuts at both ends: skills stay in a library until a request needs them, and sessions are kept short.
tokens de contexto fixo em cada mensagem, medidos (39,7k → 27,8k). Um corte de 30%.fixed context tokens on every message, measured (39.7k → 27.8k). A 30% cut.
tokens a mais ao tirar as 21 skills de vídeo do contexto fixo (estimado pelo tamanho das descrições). Mesmo resultado no teste.more tokens saved by moving 21 video skills out of fixed context (estimated from description size). Same test result.
era o custo da skill de auditoria de API pra dar o mesmo resultado. Foi pra biblioteca.was the cost of the API audit skill for the same result. It went to the library.
falas suas por sessão antes de destilar memória, e a destilação roda no Haiku. Sessão curta não gasta nada.messages of yours per session before memory is distilled, and distillation runs on Haiku. Short sessions cost nothing.
tokens de contexto e ela avisa (de novo em 250k e 500k): salva o HANDOFF.md e abre sessão nova. A barra de status mostra o tamanho o tempo todo.context tokens and she warns you (again at 250k and 500k): save HANDOFF.md and start fresh. The status line shows the size all the time.
resume o projeto no início da sessão (estrutura, scripts, últimos commits). Nada de reexplorar o repositório.sums up the project at session start (structure, scripts, last commits). No re-exploring the repo.
notas de memória que batem com o pedido entram inteiras. Sem ida e volta pra ler.memory notes that match the request are delivered whole. No round trip to read them.
LLM nos hooks de segredo e de git. Regex e git, em milissegundos.LLM calls in the secret and git hooks. Regex and git, in milliseconds.
é o limite: lockfile, pasta de build, arquivo gigante e git log sem limite são barrados antes de inundar o contexto.is the cap: lockfiles, build output, huge files and unbounded git log are blocked before they flood the context.
cada mensagem relê o contexto inteiro
~15k tokens fixos a menos × 40 mensagens = ~600k tokens que deixam de ser relidos numa sessão every message re-reads the whole context
~15k fewer fixed tokens × 40 messages = ~600k tokens no longer re-read in one session
a regrathe rule
Skill é sugestão.Hook é garantia.Skills suggest.Hooks enforce.
O que tem que acontecer sempre (não subir chave de API, não commitar na main, checar se o texto dá pra ler) vira hook e roda sem pedir. Skill fica pro que é conhecimento: a receita, o formato, o caminho. Whatever must always happen (no API keys in git, no commits to main, readable text) becomes a hook and runs without asking. Skills are for knowledge: the recipe, the format, the path.
placar da helena do criador · sonnet · com e semthe creator's scoreboard · sonnet · with and without
Só fica o que ganha.Only what wins stays.
| tarefatask | semwithout | comwith | o que ficouwhat stayed |
|---|
Empate também é resultado: a skill de rodar local e a de auditoria de API empataram e saíram do contexto. Toda falha é inspecionada antes de virar conclusão, porque o teste também erra. A tie is a result too: the run-locally skill and the API audit skill tied and were taken out of context. Every failure is inspected before it becomes a conclusion, because tests get it wrong too.
instalarinstall
Instala vazia. Na próxima sessão ela já está olhando.Install her empty. By your next session she is watching.
git clone https://github.com/vijcoelho/project-helena.git # verificador de contrastecontrast checker cd project-helena/helena/tools && npm install && cd ../../.. # plugin do Claude CodeClaude Code plugin claude plugin marketplace add ./project-helena claude plugin install helena@helena
Código aberto, licença MIT. O código, o README completo e o benchmark estão no GitHub. Se ela te ajudar, deixa uma estrela: é assim que mais gente acha.Open source, MIT licensed. The code, the full README and the benchmark are on GitHub. If she helps you, leave a star: that is how more people find her.
para empresasfor teams
A Helena do seu time, montada pra ele.Your team's Helena, built for it.
De graça ela aprende uma pessoa. Num time, o ganho vem de todo mundo começar com as mesmas regras, os mesmos kits e a mesma memória do projeto, e de provar com número que valeu o investimento. For free she learns one person. In a team the gain comes from everyone starting with the same rules, the same kits and the same project memory, and from proving with numbers that it paid off.
Instalação no time. Todas as máquinas configuradas, memória compartilhada do projeto num cofre do time, status line e painel ligados.Team rollout. Every machine set up, shared project memory in a team vault, status line and panel on.
Regras da empresa em hook. Branch protegida, padrão de commit, arquivos que nunca sobem, segredos do seu stack. Hook cobra, ninguém precisa lembrar.Company rules as hooks. Protected branches, commit conventions, files that never go up, your stack's secrets. A hook enforces it, nobody has to remember.
Kits sob medida. As skills do seu stack, revisadas por segurança, entrando só quando o pedido precisa. Menos contexto, menos custo.Custom kits. Skills for your stack, security reviewed, loaded only when a request needs them. Less context, lower cost.
Benchmark com as suas tarefas. O trabalho real do time rodando com e sem a Helena. Fica só o que ganha, e você vê o placar.Benchmark on your tasks. Your team's real work run with and without Helena. Only what wins stays, and you see the scoreboard.
Relatório de tokens. Onde o time gasta contexto, o que dá pra cortar e quanto isso vale no fim do mês.Token report. Where the team spends context, what can be cut and what that is worth at the end of the month.
Treinamento. Uma sessão pro time usar Claude Code com a Helena: handoff, memória, sessões curtas.Training. One session for the team to use Claude Code with Helena: handoffs, memory, short sessions.