Polypus
Harness agêntico que faz qualquer IA escrever e aplicar código — inclusive modelos sem function-calling.
npm i -g @gaberrb/polypus
De onde vem o nome
Polypus é “polvo” em latim — do grego polýpous, “muitos pés”.
A metáfora é o coração do projeto: assim como o polvo tem muitos tentáculos agindo ao mesmo tempo, o Polypus coordena vários agentes de IA em paralelo, cada um numa git worktree isolada, para resolver partes diferentes da mesma tarefa.
Do prompt ao código
Clique em cada etapa do fluxo para entender o que acontece por baixo.
Selecione uma etapa
As explicações de cada etapa aparecem aqui.
🔬 Tools vs. sem tools — simulação passo a passo
… e em paralelo: o Swarm
O truque: fazer qualquer modelo “codar”
Modelos com function-calling usam tools nativas. Os sem tools recebem um protocolo XML no prompt e o Polypus parseia a saída — então até modelos locais escrevem arquivos.
<polypus:tool name="write_file">
<arg name="path">src/index.ts</arg>
<arg name="content">console.log("olá");</arg>
</polypus:tool>Se o modelo enrola (“não posso criar arquivos”), o harness reforça: “SIM, você pode — aja agora”. Mas uma simples conversa não dispara isso; e ESC cancela quando quiser.
Você no controle: 3 modos
🧭 plan
Somente leitura: investiga e propõe, sem tocar em arquivos.
✋ review
Confirma cada escrita/comando antes de executar.
⚡ bypass
Aprova tudo automaticamente — para quando você confia.
Em todos os modos, o acesso é restrito por uma allow-list de caminhos (globs).
Demo
Veja o Polypus em ação no terminal.
O que vem na caixa
🔌 Multi-provider
OpenRouter, Ollama e qualquer endpoint OpenAI-compatible + Anthropic nativo.
🧩 Tools p/ todos
Nativo quando há function-calling; protocolo XML emulado quando não há.
🐝 Swarm paralelo
Decompõe a tarefa e roda agentes em git worktrees isoladas.
🌎 Bilíngue
Interface em português (padrão) e inglês.
🔎 Descoberta de modelos
Detecta modelos do Ollama e navega o catálogo do OpenRouter por preço/tools.
🧮 Tokens & ESC
Mostra tokens gastos ao vivo e cancela o “pensando” com ESC.
🔐 Permissões
Modos plan/review/bypass + allow-list de caminhos.
🪄 Wizard
Onboarding interativo de chaves, modelos e permissões.
🩹 Autocorreção
Quando uma tool falha, o erro volta enriquecido com a causa e o contexto — o modelo se conserta sozinho em vez de entrar em loop.
🧭 PRD bot
Rotule uma issue como accepted e um agente gera um PRD estruturado, comentado na própria issue.
🤖 Review bot
Todo PR aberto recebe uma primeira camada de code review automática, com modelo gratuito do OpenRouter.
⚙️ CI/CD robusto
Build/test, PRs vinculados a issue, review automático e publish no npm — tudo no GitHub Actions.
Comece em 1 minuto
npm i -g @gaberrb/polypuspolypus setuppolypus initpolypus run "crie um servidor HTTP em src/server.ts"export OPENROUTER_API_KEY=sk-or-...
polypus add-agent or --provider openrouter \
--model "anthropic/claude-3.5-sonnet" --api-key '${OPENROUTER_API_KEY}'
polypus models --tools --max-price 1 # explore modelos por preço/toolsComo contribuir
O fluxo é issue-gated: nada de PR sem uma issue triada.
Descreva o bug ou a ideia — há templates de bug e feature.
acceptedO mantenedor tria e aplica a label accepted — o sinal verde.
Crie a branch e abra o PR referenciando a issue com Closes #N.
O CI roda build/test, o require-issue confere a label e o bot comenta um review.
Com tudo verde, o merge entra na main — e a issue fecha sozinha.
📂 Arquivos essenciais (leia antes)
Principalmente se você usa IA para codar: leia o
context.md
(resumo do projeto, sempre atualizado) e o
rules.md
(padrões e o que é/não é esperado). Eles são a fonte de verdade — e também alimentam
os bots de PRD e de review.
Changelog
Todas as mudanças relevantes, versão a versão.
Seguimos o formato Keep a Changelog + SemVer. As adições mais recentes (autocorreção, agentes de PRD e review, hardening) estão na seção Unreleased.