Como usar o Ponytail no Claude Code: instalação, primeiros comandos e como confirmar que funcionou

Fala aí, beleza? Todo mundo que roda agente de código já viu esse filme: você pede um ajuste pequeno e volta uma fábrica de abstração, com camada de serviço, interface, factory e três arquivos novos que ninguém pediu

O Ponytail existe pra cortar exatamente isso

Ele é um conjunto de regras (distribuído como skills e como plugin) que faz agentes de código escreverem o menor código que funciona, seguindo YAGNI e priorizando biblioteca padrão e recursos nativos da plataforma. A regra única é quase simples demais: antes de escrever código, parar na primeira opção que já resolve o problema

É gratuito e open source sob licença MIT, mantido no repositório DietrichGebert/ponytail

E aqui neste post eu vou direto ao caminho mínimo: o que precisa estar pronto, os comandos de instalação, como confirmar que ativou e o que esperar de resultado sem cair no hype 🙂

O que precisa estar pronto antes de instalar

São duas coisas, e a segunda é a que derruba a galera

1) Claude Code funcionando na sua máquina

Se você ainda está montando esse ambiente, vale antes entender o fluxo do primeiro projeto ao deploy e só depois ir empilhando plugin em cima

2) node disponível no PATH

Esse é o pulo do gato

Os plugins de Claude Code e Codex do Ponytail rodam dois hooks de ciclo de vida em Node.js, então o node precisa estar acessível

E tem uma pegadinha declarada na própria documentação: quem usa Nix ou nvm precisa do node no PATH do shell não interativo, não só naquele terminal bonitinho onde tu digita

Sem node, as skills continuam funcionando, só que a ativação sempre ligada não acontece automaticamente

E o que NÃO é pré-requisito? Conta, assinatura, cartão, nada disso

É open source sob licença MIT, sem custo pra usar, modificar ou distribuir

Passo a passo: instalar o Ponytail no Claude Code

O caminho oficial são dois comandos dentro do Claude Code. Os passos 3 e 4 são alternativas, não etapas obrigatórias

1. Adicione o marketplace do repositório

/plugin marketplace add DietrichGebert/ponytail

O erro comum deste passo: rodar isso no terminal do sistema. Não é comando de shell, é comando de barra dentro do Claude Code

2. Instale o plugin

/plugin install ponytail@ponytail

Repare no ponytail@ponytail: é o nome do plugin arroba o nome do marketplace que você acabou de adicionar. O erro comum aqui é digitar só ponytail e ficar olhando pra tela sem entender por que não resolveu

3. Alternativa por CLI de skills

Se você prefere instalar por fora, apontando o agente na mão:

npx -y skills add DietrichGebert/ponytail --agent claude-code

O erro comum: esquecer o --agent claude-code e instalar apontando pra outro agente

4. Alternativa manual, copiando skill por skill

Dá pra criar a pasta em ~/.claude/skills/<nome>/ e copiar o SKILL.md do repositório pra dentro dela

Repare no <nome>: o padrão é uma pasta por skill, com o SKILL.md daquela skill dentro. Ou seja, esse caminho é manual mesmo, repetido pra cada skill que tu quiser ter à mão. Se a ideia é receber o conjunto inteiro de uma vez, os passos 1 e 2 resolvem melhor

O erro comum deste passo (e é o clássico): o nome da pasta precisa ser igual ao nome da skill. Pasta com nome diferente e a skill simplesmente não aparece

Tome cuidado também com o combo dos dois erros: instalar sem node no PATH e depois achar que a instalação falhou. Ela não falhou, é a ativação automática que não sobe

Primeiros comandos e como confirmar que o Ponytail está ativo

Instalou, e agora? Bora ver na prática

O ruleset entra pelo hook SessionStart, que injeta as regras em toda sessão. Ou seja: o começo da sessão é o momento em que o Ponytail se apresenta pro agente

O segundo hook, UserPromptSubmit, rastreia as mudanças de modo quando você roda /ponytail lite, /ponytail full ou /ponytail ultra

O caminho mínimo até ver algo acontecer:

1. Rode /ponytail-help

Ele devolve um cartão de referência rápida com os comandos e níveis

Atenção pra não se confundir: esse comando é apenas informativo, ele NÃO ativa nada. Serve pra você conferir que as skills estão lá e lembrar o que existe

2. Rode /ponytail numa tarefa real

Nada de tarefa de brincadeira, pega algo do teu projeto mesmo

/ponytail adicione um endpoint que retorna o status do serviço

3. Observe o comportamento, não a mensagem

A confirmação de que funcionou é o agente se comportando conforme a regra única: parar na primeira opção que já resolve, usar biblioteca padrão antes de puxar dependência e não criar abstração que você não pediu

Se voltou uma solução curta e sem camada extra, o ruleset está agindo

Se voltou aquele combo de interface + adapter + config pra um endpoint de status, alguma coisa não entrou

Travou no começo? Os problemas mais prováveis

Na partida, quase tudo cai em dois sintomas

As regras não entram sozinhas a cada sessão

Sintoma: você instalou, mas o comportamento sempre ligado não aparece em cada sessão nova

Causa provável: node ausente no PATH do shell não interativo. É o cenário típico de quem usa Nix ou nvm, onde o node só existe depois que o shell interativo carrega o ambiente

Solução: deixar o node acessível também no shell não interativo. Sem ele, as skills seguem funcionando, mas a ativação automática não acontece

Como prevenir: conferir o node ANTES de instalar, não depois de perder meia hora achando que o plugin está quebrado

A skill instalada na mão não aparece

Sintoma: você criou a pasta em ~/.claude/skills/, copiou o SKILL.md, e o comando não existe

Causa provável: o nome da pasta está diferente do nome da skill

Solução: renomear a pasta pra bater exatamente com o nome da skill

Como prevenir: conferir o nome no momento de criar a pasta, que é quando custa dez segundos 😀

Os seis comandos do Ponytail e quando usar cada um

O Ponytail expõe seis skills em forma de comando de barra. Cada uma entra num momento diferente do trabalho

• /ponytail: o modo preguiçoso. É o que tu usa no dia a dia, quando quer a solução mais simples que funciona pra tarefa da vez
• /ponytail-review: revisão de over-engineering com feedback inline. Ele aponta o excesso, e olha que detalhe importante: ele apenas lista, não aplica. Quem decide é você
• /ponytail-audit: auditoria do repositório inteiro, com lista ranqueada do que dá pra apagar. Esse é pra quando você herda um projeto e quer o mapa do inchaço
• /ponytail-debt: junta os comentários de atalho num registro rastreado. Aquele monte de "depois eu arrumo" espalhado vira uma lista só
• /ponytail-gain: placar de impacto medido, com menos código, menos custo e mais velocidade
• /ponytail-help: o cartão de referência rápida. Informativo, não ativa nada

Se você conhece a ideia de linter, a dupla review + audit é bem parecida na cabeça: uma olha o que você acabou de mexer, a outra varre a casa inteira

Como escolher o nível: lite, full, ultra ou off

São quatro níveis de aplicação das regras:

Nível	O que faz
lite	Sugere a opção mais simples
full	Padrão, aplica as regras
ultra	Extremista de YAGNI, prefere apagar código a adicionar
off	Desliga

O ultra é aquele colega que olha teu PR e pergunta se dá pra resolver deletando arquivo em vez de criando. Às vezes é exatamente o que o projeto precisa, às vezes não é a hora 🙂

Pra fixar o nível padrão das novas sessões, tem dois caminhos

1. Variável de ambiente

PONYTAIL_DEFAULT_MODE=lite

Aceita lite, full, ultra ou off

2. Arquivo de configuração

O campo defaultMode em ~/.config/ponytail/config.json, ou %APPDATA%\ponytail\config.json no Windows

E se você não vive só dentro do Claude Code, o mesmo ruleset é distribuído em vários formatos: plugin pra Claude Code e Codex, extensão pro Gemini CLI, marketplace pro Copilot CLI e arquivo de regras simples pra Cursor, Windsurf, Cline, Aider, Kiro, Zed e outros

Que resultado esperar depois da primeira sessão

Agora a parte honesta, porque esse projeto teve uma treta boa de benchmark

A alegação inicial era de 80 a 94 por cento menos código

Só que esse número vinha de uma linha de base falha: a comparação era contra um modelo de chat puro. Um contribuidor apontou o erro, o mantenedor refez o benchmark como execução agêntica real e publicou um número menor

O número oficial atual é esse:

Medição	Menos código	Custo	Tempo
Benchmark oficial corrigido	~54% na média	~20% mais barato	~27% mais rápido
Teste independente da JetBrains	15%	10,3% de economia	11% de ganho

O oficial foi medido em sessões reais de Claude Code num repositório open source (FastAPI + React), média de 12 tarefas

E tem uma nuance na média que vale MUITO mais que a média: a redução chega a 94% em casos de over-engineering pesado e fica perto de zero quando o código já estava enxuto

Ou seja: se o teu projeto já é limpo, não espera milagre

Se o teu projeto é uma catedral de abstração, aí o ganho aparece

Sobre a economia de custo, ela conversa direto com a escolha de qual modelo usar em cada tarefa: menos código gerado é menos token gasto, e as duas decisões se somam

Vale notar que o teste independente da JetBrains mediu ganhos bem menores que os oficiais. Não é contradição necessariamente, é lembrete de que o resultado depende muito do repositório e das tarefas

Próximo passo depois de instalar

O caminho curto é esse: instalou, rodou /ponytail numa tarefa real, viu o comportamento mudar

Agora vira pro que já existe

Roda /ponytail-review no código que você acabou de escrever, e depois /ponytail-audit pra ver a lista ranqueada do que dá pra apagar do repositório

E ajusta o nível conforme o teu gosto: se full estiver conservador demais pro teu caso, testa ultra e vê até onde tu aguenta a régua haha

Sobre tração do projeto, pra você calibrar o quanto isso pegou: o repositório foi publicado no GitHub em 12 de junho de 2026 e já passou de 100 mil estrelas, com um agregador registrando 106,1 mil em meados de agosto de 2026. A versão mais recente publicada no registro npm é a 4.9.0

Pra um conjunto de regras que cabe num arquivo de texto, é bem insano o tanto de gente que resolveu instalar

Matheus Battisti, Hora de Codar

até o próximo post!

Perguntas frequentes

O Ponytail é pago ou tem alguma versão paga no Claude Code?

Não, o Ponytail é gratuito e open source sob licença MIT. Dá pra usar, modificar e distribuir sem custo, e isso vale tanto pro plugin do Claude Code quanto pras skills instaladas na mão.

Qual a diferença entre os modos lite, full e ultra do Ponytail?

São níveis de aplicação das regras, do mais suave ao mais radical. O lite só sugere a opção mais simples, o full (padrão) aplica as regras, e o ultra é o extremista de YAGNI, que prefere apagar código a adicionar. Tem ainda o off, que desliga tudo, e a troca entre eles é feita com /ponytail lite, /ponytail full ou /ponytail ultra.

Dá pra definir o modo padrão do Ponytail pra toda sessão nova do Claude Code?

Dá sim, de duas formas. Uma é a variável de ambiente PONYTAIL_DEFAULT_MODE (lite, full, ultra ou off), a outra é o campo defaultMode dentro de ~/.config/ponytail/config.json (no Windows fica em %APPDATA%\ponytail\config.json).

O Ponytail funciona em outros agentes além do Claude Code?

Sim, o mesmo ruleset é distribuído pra vários agentes. Tem plugin pra Claude Code e Codex, extensão pra Gemini CLI, marketplace pra Copilot CLI, e um arquivo de regras simples pra Cursor, Windsurf, Cline, Aider, Kiro, Zed e outros.

Os números de redução de código do Ponytail são confiáveis?

O número atual já passou por correção. A alegação inicial de 80 a 94% menos código vinha de uma linha de base falha, comparando contra um modelo de chat puro, e depois de um contribuidor apontar o erro, o mantenedor refez o benchmark com execução agêntica real. O número oficial corrigido ficou em cerca de 54% menos código na média (chegando a 94% em casos de over-engineering), cerca de 20% mais barato e cerca de 27% mais rápido, medido em sessões reais de Claude Code num repositório open source (FastAPI + React), média de 12 tarefas. Um teste independente da JetBrains mediu números menores: 15% menos código, 10,3% de economia de custo e 11% de ganho de tempo.

Quem mantém o Ponytail e é seguro confiar no projeto?

O Ponytail é mantido no GitHub pelo usuário DietrichGebert, no repositório DietrichGebert/ponytail, publicado em 12 de junho de 2026. O repositório passou de 100 mil estrelas no GitHub em agosto de 2026 (o agregador registrava 106,1 mil em meados do mês), o que dá um sinal de tração real da comunidade.