Instalei o Ponytail e o Claude Code não reconhece: por onde começar o diagnóstico

Fala aí, beleza? Instalou o Ponytail, abriu o Claude Code, digitou a barra esperando ver os comandos e… nada aparece

O impulso natural aqui é o pior possível: desinstalar tudo, limpar pasta, reinstalar, torcer

Isso quase nunca resolve, porque você troca a causa por uma loteria

O Ponytail é um projeto open source de skill/plugin para agentes de código, mantido no GitHub por DietrichGebert, com a descrição "Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote."

O repositório do Ponytail está em cerca de 107 mil estrelas, e o projeto tem adaptadores para vários agentes além do Claude Code: Codex, GitHub Copilot CLI, Cursor, Windsurf, OpenCode e Gemini CLI, entre outros

E aqui vai o ponto que muda todo o diagnóstico: "não reconhece" tem pelo menos três significados bem diferentes

Pode ser o Claude Code que não entende o comando de instalação, podem ser as skills que não carregaram na sessão, ou pode ser a ativação automática que não acontece mesmo com os comandos visíveis

Cada um desses tem uma causa e uma checagem própria

Bora separar qual é o seu?

Sintoma 1: o Claude Code não reconhece o comando /plugin

Esse é o caso mais fácil de resolver, e também o mais comum em quem instalou o Claude Code faz tempo e nunca atualizou

O próprio README do Ponytail registra isso: se o /plugin não for reconhecido, o Claude Code está desatualizado

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

A solução é atualizar e reiniciar:

npm install -g @anthropic-ai/claude-code@latest

Ou, se você instalou via Homebrew:

brew upgrade claude-code

Depois de reiniciar, repita os dois comandos de barra dentro da própria sessão do Claude Code:

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

Repara numa coisa: os dois são comandos de barra, digitados DENTRO da sessão, não no terminal

O erro comum deste passo é tentar rodar isso no shell como se fosse um npm install da vida

Como prevenir: confira a versão antes de abrir issue no repositório, porque metade dos relatos de "não funciona" morre aqui 🙂

Sintoma 2: instalei o plugin, mas os comandos /ponytail não aparecem

A instalação terminou, você digita /pony e a lista não sugere nada

A causa provável é que as skills do plugin não estão sendo carregadas, e isso é um problema comum o suficiente para estar documentado na própria doc do Claude Code

Antes de sair apagando pasta, diagnostique em ordem:

1. Rode /context para ver o que a sessão realmente carregou. O erro comum deste passo é confiar na mensagem de sucesso da instalação: sucesso na instalação não é o mesmo que carregado na sessão
2. Rode /doctor para uma leitura mais detalhada da configuração
3. Rode /reload-plugins para recarregar os plugins ativos sem reiniciar. Ele mostra as contagens de plugins, skills, agents, hooks, servidores MCP de plugin e servidores LSP, e é justamente essa contagem que você quer ler
4. Se o reload avisar que vai reler a conversa e você não quiser isso, use /reload-plugins --force
5. Antes de partir pra destruição, desative e reative o plugin sem desinstalar:

/plugin disable ponytail@ponytail
/plugin enable ponytail@ponytail

6. Só se nada acima resolver, limpe o cache de plugins, reinicie o Claude Code e reinstale o plugin:

rm -rf ~/.claude/plugins/cache

O erro comum deste último passo é começar por ele

Apagar cache resolve às vezes, mas te ensina zero sobre o que estava errado, e se voltar a acontecer você vai apagar de novo

Quando está tudo certo, os comandos de barra que devem aparecer são estes:

• /ponytail
• /ponytail-review
• /ponytail-audit
• /ponytail-debt
• /ponytail-gain
• /ponytail-help

E /ponytail off desliga

Como prevenir: pegue o hábito de rodar /reload-plugins e LER as contagens depois de toda instalação ou atualização

Demora dois segundos e te poupa de descobrir uma semana depois que nunca carregou

Sintoma 3: os comandos funcionam, mas o Ponytail não age sozinho a cada prompt

Esse é o sintoma mais confuso de todos

Os comandos de barra respondem, você jura que instalou certo, mas o comportamento always-on simplesmente não acontece

A causa quase sempre são os dois hooks de ciclo de vida que não estão rodando

Checagem 1: abra o /hooks e confirme que os dois estão lá

No arquivo de hooks Claude/Codex do Ponytail eles são o SessionStart, que roda o ponytail-activate.js com timeout de 5 segundos em startup, resume e clear, e o UserPromptSubmit, que roda o ponytail-mode-tracker.js com timeout de 5 segundos a cada prompt

O README manda revisar e confiar nos dois hooks e depois iniciar uma nova thread

Esse "iniciar uma nova thread" não é enfeite: o SessionStart roda no começo da sessão, então numa thread que já estava aberta ele não vai rodar de novo por mágica

Checagem 2: os hooks rodam em Node.js, então o node precisa estar no PATH

E atenção pra quem usa nvm ou Nix: precisa estar no PATH do shell NÃO interativo, que é um lugar diferente do seu terminal do dia a dia

"Mas o node funciona aqui no meu terminal", sim, e isso não prova nada sobre o shell que executa o hook

Aqui está o detalhe que explica toda a confusão: sem o node, as skills continuam funcionando normalmente, mas a ativação always-on fica SILENCIOSA em vez de dar erro a cada prompt

Ou seja, você não vê mensagem de falha nenhuma, só sente que a ferramenta não está agindo

Como prevenir: valide o node no PATH do shell não interativo antes de culpar o plugin

Sintoma 4: o modo nunca fica ativo e a statusline não mostra nada

Primeiro, entenda onde o estado mora, porque isso é o que te deixa checar em vez de adivinhar

O modo ativo do Ponytail é gravado em um arquivo .ponytail-active dentro do $CLAUDE_CONFIG_DIR, que por padrão é o ~/.claude

Os hooks usam setMode() e clearMode() pra escrever e limpar esse arquivo, e a statusline lê ele

Agora a parte que pode não ser culpa da sua máquina

Existe uma issue aberta no repositório, a #584, aberta em 2026-07-10, que registra o seguinte: no Claude Code o /ponytail é despachado como skill, e o hook UserPromptSubmit recebe o corpo do SKILL.md em vez do texto do comando

Resultado: o setMode() nunca é chamado, o ~/.claude/.ponytail-active nunca é escrito, e tudo que lê esse arquivo enxerga nenhum modo ativo

Se o comportamento que você vê bate com isso, para de reinstalar

Não tem reinstalação que conserte bug de despacho, o caminho honesto é acompanhar a issue

E tem mais um caso que cai aqui: quem instalou pelo adaptador de servidor MCP

O Ponytail tem esse adaptador, mas em modo MCP a ativação é MANUAL e não é injetada a cada rodada

Se você quer comportamento always-on, o caminho é o modo plugin no Claude Code ou no Codex, não o MCP

Muita gente instala pelo MCP, espera always-on e acha que quebrou

Sintoma 5: a instalação falha antes mesmo de terminar

Dois casos com registro público, pra você saber quando o problema é do seu ambiente e quando não é

A issue #593 registra que um campo commandWindows não reconhecido no hooks.json quebra a validação e derruba o install pelo marketplace de plugins do Claude.ai

Repara no escopo: esse é o marketplace do Claude.ai, não o Claude Code

A issue #19 registra hooks falhando no Windows dentro do Codex, porque o commandWindows usa sintaxe de cmd.exe dentro de um comando PowerShell

De novo, escopo: isso é Codex

Separar de qual produto é o relato evita horas perdidas tentando aplicar solução de um lugar em outro

E se a sua instalação está simplesmente velha, o README indica o caminho de atualização manual:

/plugin marketplace update ponytail
/reload-plugins

Nenhuma das anteriores: como ler os erros que o Claude Code esconde

Passou por todas as checagens e continua estranho? Então é hora da última camada

Suba o Claude Code em modo debug:

claude --debug

O --debug mostra erros de parse de skills, tipo frontmatter YAML malformado no SKILL.md

Isso vale também pras skills pessoais, que ficam em ~/.claude/skills/<nome-da-skill>/SKILL.md

Um YAML quebrado não te dá um erro vermelho na cara: a skill só some da listagem, e você fica achando que a instalação falhou

Outra camada que quase ninguém checa: o /doctor estima o custo de contexto da listagem de skills e mostra os maiores contribuintes

Quando essa listagem estoura o orçamento, o Claude Code encurta ou derruba descrições, começando pelas skills menos usadas, e o aviso vai também pro log de debug visível com --debug

Lê isso de novo, porque é sutil: ter MUITAS skills instaladas pode fazer uma delas sumir da listagem

O plugin está lá, instalado, carregado, e mesmo assim invisível

E mais uma armadilha documentada: plugins são copiados para um cache, então caminhos que apontam pra arquivos fora do diretório do plugin não são encontrados depois da instalação

Se você mexeu no plugin apontando pra algum arquivo seu de fora, é por aí

Esse tipo de leitura de saída vale pra tudo no Claude Code, não só pra plugin: entender o que ele respondeu antes de aceitar é metade do trabalho

Como prevenir: mantenha a listagem de skills enxuta e rode /doctor de tempos em tempos, não só quando quebra

O que aprendi instalando skill de agente no Claude Code na prática

Aqui é bastidor, e vou ser transparente no escopo: o vídeo abaixo não é sobre o Ponytail, é sobre outro framework, o GSD

Mas a parte de INSTALAR e de CONFIRMAR que o Claude Code reconheceu é exatamente o que interessa nesse diagnóstico, e foi aí que eu me confundi na época

No vídeo eu conto que esperava instalar por dentro do Claude Code, do jeito que faço com plugin, e descobri que a instalação daquele framework acontece FORA da sessão, no terminal

Essa é a confusão número um de quem acha que "não reconhece": rodar o comando no lugar errado e concluir que a ferramenta está quebrada

Outra coisa que eu mostro é que peguei o comando de instalação na documentação oficial do projeto, não de memória

Parece bobagem, mas comando de instalação lembrado de cabeça é uma das maiores fontes de erro em ferramenta nova

Durante a instalação, o instalador me perguntou pra qual runtime/assistente de IA instalar, e dava pra marcar mais de um: naquele momento eu marquei só o Claude Code

Ele também perguntou se a instalação era global ou local, e eu escolhi global, comentando no vídeo que isso não faz o framework agir sozinho, ele só entra quando eu peço

E a forma como eu confirmei que tinha dado certo foi a mais simples possível: abri o Claude Code, digitei o prefixo de barra do próprio framework e vi a lista de comandos aparecer

É o mesmo teste que vale aqui: comando de barra aparecendo na lista é prova de que carregou

Depois disso eu rodei o comando de novo projeto e o fluxo respondeu com a entrevista inicial, o que pra mim fechou a prova de que estava funcionando de verdade, não só listado

No vídeo eu subo a sessão com a flag de pular permissões, porque a fase de planejamento gera MUITO arquivo, e comento que dá pra trabalhar sem a flag, só fica mais lento

Detalhe que achei massa: a ferramenta percebeu que eu escrevia em português e seguiu a conversa em português

E o sinal visível final foi a pasta de planejamento criada ali na minha máquina, mostrando que o framework tinha realmente agido no projeto

A lição que sobra é essa: instalado, listado e agindo são três estados diferentes

Checar em ordem economiza muito mais tempo que reinstalar no escuro

Se você ainda está pegando o jeito da ferramenta, vale começar a aprender o Claude Code pelos comandos de sessão antes de empilhar plugin em cima

No vídeo você vê a instalação inteira e, principalmente, como eu confirmo dentro da sessão que o Claude Code reconheceu a skill

Próximo passo: confirme se ele está mesmo agindo, não só instalado

Recapitulando o diagnóstico, porque no fim das contas "o Claude Code não reconhece o Ponytail" quase sempre é uma dessas três coisas:

• Claude Code velho, que nem entende o /plugin
• skills do plugin que não carregaram na sessão
• hooks que não rodam, por falta de node no PATH ou por não terem sido revisados e confiados no /hooks

O próximo passo concreto é o mais barato: rode /ponytail-help

Ele é um cartão de referência rápida de modos, skills e comandos, e aciona tanto pelo /ponytail-help quanto por frases como "ponytail help"

Uma observação pra não te confundir: ele é exibição única, não um modo persistente, então ver o cartão prova que a skill responde, não que existe modo ativo

E quando quiser desligar, /ponytail off

Sobre expectativa, vou deixar os números como o que eles são: afirmações de quem mediu

Os números do projeto vêm de sessões reais de Claude Code contra o mesmo agente sem a skill, e o teste independente da JetBrains mediu ganhos menores que os anunciados

Os dois podem ser verdade em contextos diferentes, e nenhum deles vai acontecer se o plugin nem estiver carregando na sua sessão 😀

primeiro faz ele funcionar, depois discute o quanto ele entrega…

até o próximo post!