Ponytail no Claude Code: o que ele lê do seu projeto antes de você aprovar?

Fala aí, beleza? Instalar plugin no Claude Code é instalar código que roda na TUA máquina, com as tuas permissões, e o Ponytail ainda chega pedindo pra varrer o repositório inteiro

A pergunta que interessa aqui não é se o Ponytail é bom

É o que ele enxerga do teu projeto antes de você clicar em aprovar

E se você precisa justificar a ferramenta no trabalho, essa é exatamente a pergunta que o time de segurança vai te fazer, então bora mapear o que dá pra conferir de verdade

O que é o Ponytail e quem está por trás dele

O Ponytail é um projeto open source hospedado no GitHub sob a conta DietrichGebert, no repositório DietrichGebert/ponytail

A proposta é fazer o agente de IA pensar como o dev sênior mais preguiçoso da sala (e isso é bom!): menos código escrito, menos gambiarra, mais uso do que já existe

Ele é distribuído sob licença MIT e é gratuito

No Claude Code, a instalação sai pelo marketplace de plugins, com os comandos de barra do próprio Claude Code:

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

Depois de instalado, o pacote expõe as skills por comando de barra: /ponytail, /ponytail-review, /ponytail-audit, /ponytail-debt, /ponytail-gain e /ponytail-help

E tem níveis de intensidade que controlam o quanto ele atua: lite, full, ultra e off

Repara que isso já responde a primeira pergunta de qualquer aprovação interna: de que fonte vem o código? Da conta DietrichGebert no GitHub, sob licença MIT

Não é bom nem ruim por si só, é só o fato que você vai ter que colocar na mesa 🙂

O que cada comando do Ponytail precisa ler para funcionar

Aqui é onde a conversa fica concreta, porque "plugin de IA" é vago e superfície de leitura não é

A skill que varre tudo: ponytail-audit

O /ponytail-audit varre o repositório inteiro, e não apenas o diff

A saída é uma lista ranqueada por impacto, uma linha por achado, do que dá pra apagar, simplificar ou trocar por recurso nativo, fechando com o cálculo líquido de linhas e dependências removíveis

E tem uma característica importante pra quem vai vender isso internamente: é um relatório one shot, ele não aplica mudanças

O que fica FORA do escopo dele também está declarado: correção de bugs, falhas de segurança e performance

Ou seja, não adianta você levar pro time dizendo que é um scanner de segurança, porque não é

Os hooks: o que roda sem você pedir

O plugin registra dois hooks de ciclo de vida, e cada um executa um script Node na sua máquina:

SessionStart      node "${CLAUDE_PLUGIN_ROOT}/hooks/ponytail-activate.js"
UserPromptSubmit  node "${CLAUDE_PLUGIN_ROOT}/hooks/ponytail-mode-tracker.js"

O que é um hook de ciclo de vida? É um gancho: em vez de você chamar o comando, o Claude Code dispara o script sozinho quando o evento acontece

SessionStart roda ao abrir a sessão, UserPromptSubmit roda toda vez que você manda uma mensagem

O hook de ativação grava um arquivo de flag em $CLAUDE_CONFIG_DIR/.ponytail-active (por padrão ~/.claude) e lê a configuração de intensidade da variável de ambiente PONYTAIL_DEFAULT_MODE ou do campo defaultMode em ~/.config/ponytail/config.json (no Windows, %APPDATA%\ponytail\config.json)

Se liga nisso: essa leitura e essa escrita acontecem FORA do repositório, na tua pasta de configuração

O que dá pra confirmar olhando o script é isso: escrita do flag e leitura da config do próprio Ponytail

E se algum dado do repositório sai da tua máquina? Essa parte não aparece documentada no projeto, então não entra como argumento nem a favor nem contra

O resto das skills

As outras skills operam dentro da mesma sessão do Claude Code, com as permissões que essa sessão tiver naquele momento

Quer dizer: a fronteira não é do Ponytail, é da tua sessão

Quem define o que pode ser lido e escrito continua sendo a tua configuração de permissões, e é nela que você vai mexer daqui a pouco

Se você já brigou com skill do Claude Code que não ativa, a lógica é a mesma de sempre: a skill existe, mas quem manda no acesso é a sessão em volta dela

Quem aprova o que hoje: auto mode, plan mode e modo Manual

Antes de travar qualquer coisa, você precisa saber quem está aprovando as ações na tua máquina neste momento

Desde 14 de agosto de 2026, o auto mode é o modo de permissão padrão para novas sessões nos planos Pro, Max e Team

E no auto mode quem revisa as ações no seu lugar é um segundo modelo, o classificador

Isso muda o desenho da conversa com o time: não é mais "o dev aprova cada passo", é "um modelo aprova e o dev acompanha"

Agora o ponto que salva a aprovação interna: mesmo no auto mode, as regras deny e as regras ask explícitas são avaliadas ANTES do classificador, e continuam bloqueando ou perguntando

E a organização pode desligar o auto mode

Modo Manual

O modo Manual aparece como default no valor de configuração e é chamado de Manual na interface: na CLI, no claude --help, nas extensões de VS Code e JetBrains e no app de desktop

Nele, a escrita fica limitada à pasta onde o Claude Code foi iniciado e às subpastas dela

E pra ler caminho fora dessa fronteira com Read, Grep e Glob, ele pergunta antes

Plan mode

No plan mode o Claude lê arquivos e roda comandos read only pra explorar, mas não edita o código-fonte

E tem uma garantia forte aqui: edição nunca é auto aprovada no plan mode, mesmo que exista uma regra allow correspondente

Você entra com Shift+Tab ou prefixando o prompt com /plan, e dá pra fixar via defaultMode no .claude/settings.json

Pra primeira sessão com um plugin novo, esse é o modo mais barato de olhar o comportamento dele sem risco de edição

Como limitar o que o Ponytail lê e altera com /permissions, passo a passo

O comando que centraliza essa parte é o /permissions: é ele que mostra e gerencia as regras de permissão, indicando de qual arquivo settings.json cada uma veio

Então a receita é: escreve a regra, confere no /permissions, e só depois instala

1. Leia a seção Will install antes de confirmar a instalação. Antes de instalar um plugin, o Claude Code mostra uma seção "Will install" que lista o que será adicionado: comandos, agents, skills, hooks e servidores MCP e LSP. É ali que os dois hooks do Ponytail aparecem pra você, antes de rodarem. O erro comum deste passo: passar batido no enter porque "é só um plugin". A própria documentação do Claude Code diz que plugins e marketplaces são componentes altamente confiáveis, que podem executar código arbitrário na máquina com os privilégios do seu usuário, e que só se deve instalar de fontes confiáveis

2. Escolha o escopo da instalação. A instalação tem escopos distintos: usuário (vale em todos os projetos), projeto (vale pra todos os colaboradores do repositório) e local (só você, naquele repositório). O erro comum deste passo: instalar no escopo de projeto pra "testar", e o teste virar decisão pra equipe inteira sem ninguém ter aprovado. Pra experimentar, local resolve. E vale lembrar que config de projeto envelhece calada, do mesmo jeito que projeto que ainda aponta pra um modelo aposentado e ninguém percebeu

3. Escreva as regras deny de leitura pros arquivos sensíveis no settings.json. Os padrões seguem o formato Tool(especificador), assim:

Read(./.env)
Read(./.env.*)
Read(./secrets/**)

O que casa com esses padrões fica de fora da descoberta de arquivos e dos resultados de busca, não é só um bloqueio na hora de abrir. O erro comum deste passo: achar que a regra mais específica ganha. Não ganha. A avaliação é deny, depois ask, depois allow, e vale a PRIMEIRA que casar, independentemente de ser mais específica

4. Não confunda o alcance do deny. As regras deny de Read e Edit valem para as ferramentas internas de arquivo e para comandos de arquivo que o Claude Code reconhece no Bash, tipo cat, head, tail e sed. Só que elas não valem pra subprocesso arbitrário que abre o arquivo por conta própria. O erro comum deste passo: escrever o deny do .env e apresentar isso internamente como garantia absoluta. Um script Node que abre o arquivo sozinho não está coberto por essa regra

5. Veja e gerencie tudo com /permissions. É o comando que mostra e gerencia as regras, indicando de qual arquivo settings.json cada regra vem. O erro comum deste passo: ter regra de usuário e regra de projeto brigando e você olhando só uma delas. Ver a origem de cada regra é metade do diagnóstico

6. Considere o sandbox de Bash junto do deny. As restrições de sistema de arquivos do sandbox combinam as configurações de sandbox.filesystem com as regras deny de Read e Edit, e as duas coisas são fundidas na fronteira final do sandbox. O erro comum deste passo: tratar sandbox e deny como alternativas. Eles se somam

7. Não inicie o Claude Code direto na pasta home. Quando o diretório é a home, a aceitação de confiança vale só pra sessão atual e não é gravada em disco, então o aviso reaparece a cada início. Iniciando a partir de um subdiretório de projeto, a confiança fica salva por diretório. O erro comum deste passo: abrir na home "pra ver rapidinho" e dar ao agente uma fronteira de trabalho muito maior do que o projeto que você queria auditar

Ganho anunciado x ganho medido por terceiros

Agora a parte que decide a aprovação: o número

O projeto anuncia um conjunto de ganhos, e o blog de IA da JetBrains publicou um teste independente com resultados bem menores

Métrica	Anunciado pelo projeto	Medido pela JetBrains
Código gerado	54% menos	15% menos
Tokens	22% menos	sem valor medido citado
Custo	20% menos	10,3% menos
Tempo	27% menos	11% menos

Como ler essa tabela: a DIREÇÃO é a mesma nos dois casos, a MAGNITUDE não

O ganho existe e aponta pro mesmo lado, só que na medição independente ele fica na casa de um dígito a quinze por cento, não perto da metade

E pra pedido de aprovação interno, é o número medido por terceiro que sustenta a conversa

Se você levar o número anunciado e alguém do time achar o teste da JetBrains em cinco minutos, a discussão deixa de ser sobre a ferramenta e passa a ser sobre a tua fonte 😛

Vale instalar? Depende do que você consegue travar antes

Veredito honesto: o ganho é real, e é menor que o anunciado

Já o custo de confiança é concreto e está escrito na documentação oficial, não é paranoia de quem não gosta de IA: plugin executa código arbitrário com os privilégios do seu usuário, e a recomendação é instalar apenas de fontes confiáveis

Tem mais um item que precisa entrar no teu documento de aprovação: prompt injection

A documentação de segurança do Claude Code reconhece o risco de o comportamento ser influenciado pelo conteúdo processado, e o exemplo citado é justamente um README de repositório com instruções incomuns

Olha a ironia: uma skill cuja função é varrer o repositório inteiro aumenta, por definição, a quantidade de conteúdo lido

A mitigação citada na documentação é o sandbox, onde comandos Bash podem rodar em ambiente que restringe acesso a arquivos e rede

Então, na prática:

• Faz sentido aprovar quando o repositório é teu ou da empresa, as regras deny dos arquivos sensíveis já estão escritas e conferidas no /permissions, e o objetivo é o relatório do /ponytail-audit, que não aplica mudança nenhuma
• Não faz sentido aprovar quando você vai rodar em código de terceiro que você não leu, ou quando a sessão está em auto mode sem nenhuma regra deny desenhada, ou quando a expectativa que venderam lá dentro foi "metade do código a menos"

Conclusão

O Ponytail é open source sob MIT, instala pelo marketplace de plugins do Claude Code e traz duas coisas que você precisa declarar antes de aprovar: hooks que rodam script Node na tua máquina a cada sessão e a cada prompt, e uma skill que varre o repositório inteiro

O valor existe, e o teste independente mostra que ele é mais modesto do que a divulgação sugere

O próximo passo concreto é este, e ele vem ANTES de adicionar qualquer plugin: roda /permissions, olha de onde vem cada regra e desenha os deny de leitura do teu projeto

Depois disso, primeira sessão com o Ponytail em plan mode ou em modo Manual, só pra ver o que ele pede pra ler

Controle primeiro, produtividade depois… na ordem inversa é que a conversa com o time de segurança costuma acabar mal

até o próximo post! =)

Perguntas frequentes

O Ponytail é seguro para instalar num repositório de trabalho?

Não existe uma resposta pronta pra isso: a documentação do Claude Code é clara que plugins e marketplaces executam código arbitrário com os privilégios do seu usuário, e a recomendação é instalar só de fontes confiáveis. O Ponytail vem da conta DietrichGebert no GitHub, sob licença MIT. Isso não é bom nem ruim por si só, é o dado que você precisa levar pra aprovação interna antes de instalar.

O ponytail-audit conserta os problemas que encontra?

Não. O ponytail-audit é um relatório one-shot: ele varre o repositório inteiro e devolve uma lista ranqueada por impacto do que dá pra apagar, simplificar ou trocar por recurso nativo, mas não aplica nenhuma mudança sozinho. Correção de bugs, falhas de segurança e performance também ficam explicitamente fora do escopo dele.

As regras deny do settings.json bloqueiam os hooks do Ponytail?

As regras deny de Read e Edit cobrem as ferramentas internas de arquivo e comandos reconhecidos no Bash, como cat, head, tail e sed, mas não cobrem um script Node que abre arquivo por conta própria. Os hooks do Ponytail (ponytail-activate.js e ponytail-mode-tracker.js) são exatamente scripts Node disparados por SessionStart e UserPromptSubmit, fora do caminho de Read/Edit. Então trate o deny pelo que ele é: fronteira das ferramentas de arquivo do Claude Code, não uma trava sobre tudo que roda na sua máquina.

Em qual escopo devo instalar o Ponytail: usuário, projeto ou local?

O Claude Code tem três escopos de instalação de plugin: usuário (vale em todos os seus projetos), projeto (vale para todos os colaboradores do repositório) e local (só você, naquele repositório). Pra testar um plugin novo como o Ponytail antes de generalizar, o escopo local reduz o raio de quem é afetado. A decisão de subir pra projeto é conversa pra depois de já ter lido a seção Will install e conferido os hooks.

O auto mode do Claude Code aprova as ações do Ponytail sem eu perceber?

Desde 14 de agosto de 2026, o auto mode é o padrão de permissão em novas sessões nos planos Pro, Max e Team, e nele um segundo modelo, o classificador, revisa as ações no seu lugar. Mas as regras deny e as regras ask explícitas continuam sendo avaliadas antes do classificador, então elas seguem bloqueando ou perguntando mesmo nesse modo. A organização também pode desligar o auto mode inteiro.

Onde ficam gravados os arquivos que o Ponytail cria fora do repositório?

O hook de ativação grava um arquivo de flag em $CLAUDE_CONFIG_DIR/.ponytail-active, que por padrão é ~/.claude. A configuração de intensidade é lida da variável PONYTAIL_DEFAULT_MODE ou do campo defaultMode em ~/.config/ponytail/config.json (no Windows, %APPDATA%\ponytail\config.json). Essa leitura e escrita acontecem fora do repositório, na sua pasta de configuração, não dentro do projeto.