← voltar

📖 Documentação

Guia oficial de uso do Polypus — o harness de codificação agêntico que faz qualquer API de IA gerar e aplicar código. Aqui você instala, configura e aprende os recursos de qualidade que fazem modelo barato render como ferramenta cara: prompt caching, diagnósticos pós-edit, checkpoints e TUI.

🇬🇧 Official usage docs: install, configure and learn the quality features (prompt caching, post-edit diagnostics, checkpoints/rewind, polished TUI) that make cheap models perform like expensive tools.

Instalação

Requer Node.js 20+. Instale global via npm:

npm install -g @gaberrb/polypus
polypus --version

Também dá para rodar sem instalar, com npx @gaberrb/polypus <comando>.

Setup & agentes

Um agente é um par provedor + modelo. Rode o assistente interativo, que configura chave, modelo e permissões, ou adicione um agente direto:

# assistente guiado (recomendado na primeira vez)
polypus setup

# ou registre um agente manualmente
polypus add-agent claude \
  --provider anthropic \
  --model claude-sonnet-5 \
  --api-key "${ANTHROPIC_API_KEY}" \
  --set-default

Provedores: openrouter, anthropic, ollama (local) e qualquer endpoint openai-compatible. Prefira referências de ambiente (${VAR}) a segredos inline — as chaves ficam em ~/.polypus/.env. Explore modelos do OpenRouter com polypus models.

Uso básico

Passe a tarefa direto (one-shot) ou abra uma sessão interativa (REPL):

# one-shot: executa e para
polypus run "adicione validação de e-mail no cadastro e um teste"

# sessão interativa (REPL) — sem tarefa
polypus run

# headless (para UIs/scripts): objeto JSON único, ou NDJSON ao vivo
polypus run "corrige o bug do parser" --json --mode bypass
polypus run "..." --json --stream

No REPL, comandos começam com / (ex.: /agent, /mode, /agents). Retome sessões com polypus run --continue ou --resume <id>. Divida uma tarefa grande entre vários agentes em paralelo com polypus swarm.

Modos de permissão

Controlam o que o agente pode fazer sem pedir confirmação. Ajuste com --mode ou /mode:

Modo	Comportamento
plan	Só leitura e planejamento — nenhuma edição é aplicada.
review	Pede confirmação antes de cada escrita, mostrando o diff colorido (aprovar tudo, rejeitar ou escolher hunks).
bypass	Aplica tudo sem perguntar. Combine com checkpoints para desfazer com segurança.

Uma allow/deny-list de caminhos (globs) limita quais arquivos o agente pode ler/escrever, mesmo em bypass.

Perfis quality / fast

O perfil agrupa as alavancas de engenharia que fazem o modelo entregar mais. Padrão: quality.

Perfil	verify	plan-first	auto-context
quality (padrão)	on	on	on
fast	off	off	off

polypus run "..." --quality   # o mais capaz (padrão)
polypus run "..." --fast      # o mais barato/rápido
polypus run "..." --no-verify # sobrescreve um campo do perfil

Prompt caching v0.6.8+

O harness marca pontos estáveis do prompt (tools, system e histórico) para reaproveitar o prefixo entre iterações do loop a ~0.1x do preço de input, em vez de reprocessar tudo a cada passo. É a alavanca de menor esforço/maior retorno da tese custo×qualidade.

Cobre o provedor Anthropic nativo e modelos Claude via OpenRouter (injeção de cache_control). OpenAI/Gemini/DeepSeek cacheiam automaticamente — o Polypus só lê os tokens cacheados do usage. O custo passa a re-precificar cache (leitura 0.1x, escrita 1.25x), e usage.jsonl registra cacheReadTokens/cacheCreationTokens.

Como usar

Ligado por padrão — nada a fazer. Para desligar (ex.: comparar custo):

// ~/.polypus/config.json
{ "caching": "auto" }   // padrão · use "off" para desativar

Diagnósticos pós-edit v0.6.9+

Depois de cada edição, o Polypus roda checagens rápidas e escopadas nos arquivos tocados e realimenta os erros ao modelo — que corrige antes de seguir, em vez de só descobrir no --verify final. O compilador vira revisor gratuito dentro do loop.

TypeScript via tsc --noEmit --incremental (com build-info por workspace para acelerar execuções repetidas); Python via ruff quando configurado. Best-effort: cada checagem tem timeout (padrão 10s) e nunca trava o loop. Filtra a saída para os arquivos da sessão, evitando ruído de erros pré-existentes.

Como usar

Automático quando um toolchain é detectado. Configuração:

// ~/.polypus/config.json
{ "diagnostics": "auto" }   // padrão · "on" força · "off" desativa

Checkpoints & rewind v0.6.10+

Antes de cada edição, o Polypus tira um snapshot do estado anterior do arquivo (content-addressed, deduplicado por hash) em ~/.polypus/checkpoints/<sessão>. Assim você desfaz mudanças do agente mesmo sem git ou com a árvore suja — a rede de segurança que deixa rodar em bypass sem medo.

Cobre write_file, edit_file, apply_patch, move_file e delete_file — deletes e moves são reversíveis. GC automático remove snapshots com mais de 7 dias. Independente de git; não toca no seu index/stash.

Como usar

# liste os checkpoints de uma sessão
polypus checkpoints <id-da-sessão>

# volte o workspace ao estado antes do checkpoint N
polypus checkpoints <id> --restore 3

# restaure só um arquivo, ou escolha a raiz do workspace
polypus checkpoints <id> --restore 3 --file src/foo.ts
polypus checkpoints <id> --restore 3 --dir /caminho/do/projeto

Descubra o <id> com polypus sessions. Desative com { "checkpoints": "off" }.

⚠ O rewind restaura estado de arquivos, não efeitos de run_command (ex.: npm install, migrations). Mesma limitação de ferramentas equivalentes.

TUI — experiência no terminal v0.6.11+

O CLI foi polido para acompanhar o agente com clareza:

Markdown na resposta final — títulos, negrito/itálico, código, blocos com moldura e listas renderizados no terminal.
Timeline de tool calls com status e duração (✓ edit_file … (0.4s)).
Diff colorido nas confirmações de review, com truncamento de hunks longos (… +N linhas).

Respeita NO_COLOR e saída em pipe (--json): sem ANSI quando não há terminal interativo.

Referência de configuração

A config fica em ~/.polypus/config.json (segredos em ~/.polypus/.env). Campos principais:

Campo	Valores	O que faz
caching	`auto` · `off`	Prompt caching (breakpoints de `cache_control`).
diagnostics	`auto` · `on` · `off`	Checagens de tipo/lint pós-edit realimentadas ao modelo.
checkpoints	`auto` · `off`	Snapshot pré-edição para `polypus checkpoints --restore`.
execution.profile	`quality` · `fast`	Agrupa verify / plan-first / auto-context.
permissions.mode	`plan` · `review` · `bypass`	Nível de confirmação para escritas.
locale	`pt-BR` · `en`	Idioma da interface.
defaultAgent	nome	Agente usado quando `--agent` é omitido.

Flags de CLI sempre têm precedência sobre a config; a config tem precedência sobre o preset do perfil.

Comandos

Comando	O que faz
polypus setup	Assistente interativo (agentes, chaves, permissões).
polypus run [tarefa]	Executa uma tarefa; sem tarefa, abre o REPL.
polypus swarm <tarefa>	Divide a tarefa entre vários agentes em worktrees paralelas.
polypus models	Explora modelos do OpenRouter (preço, contexto, tools).
polypus usage	Analytics de tokens/custo por modelo e por dia.
polypus estimate <tarefa>	Estima esforço/custo sem fazer mudanças.
polypus sessions	Lista sessões salvas que podem ser retomadas.
polypus checkpoints <id>	Lista/restaura checkpoints de arquivo de uma sessão.
polypus index / retrieve	Índice semântico do repositório (RAG) e busca.
polypus prd <issue>	Gera um PRD a partir de uma issue (modelo grátis do OpenRouter).
polypus review <pr>	Revisa o diff de um PR (modelo grátis do OpenRouter).

Rode polypus <comando> --help para todas as flags.

Veja também: Hooks (scripts no ciclo do agente), CI/CD (agente autônomo em issues), Extensão VSCode e Extensão Chrome.