Como instalar e usar o Pipefy Process Builder

Quando um processo cresce, revisar suas regras, campos e automações ajuda a identificar o que pede atenção antes de fazer mudanças. O Process Builder permite analisar um pipe e planejar os próximos passos com base no que encontra.

Ao terminar este artigo, você vai saber instalar o Builder, conectar sua conta, fazer um primeiro diagnóstico e entender os cinco modos de uso e seus limites.

📖 O que você vai entender aqui:

O que é Pipefy Process Builder?

O Pipefy Process Builder é um consultor de processos que roda dentro do Claude Code, o assistente de IA da Anthropic que funciona no terminal do seu computador. Depois de instalado, você conversa com ele em português, como conversaria com um consultor, e ele:

• Diagnostica um processo que já existe no seu Pipefy. Encontra o que está quebrado (regras que nunca disparam, campos obrigatórios escondidos que travam cards sem erro visível, automações apontando para fases ou campos que não existem mais, agentes de IA que nunca rodam ou que rodam sem ninguém pedir), avalia conformidade com boas práticas e sugere melhorias, cada uma com severidade e correção recomendada.
• Calcula o ROI do processo de forma conservadora, usando só dados que você fornecer. Se faltar dado, diz que não dá para calcular com segurança em vez de inventar.
• Monta um deck em PDF com o diagnóstico (e o ROI, se houver) para você apresentar internamente.
• Cria um processo novo do zero e evolui um pipe existente: faz a descoberta com perguntas de múltipla escolha, propõe o desenho, pede sua aprovação e só então constrói fases, campos, automações e condicionais. Estes dois modos têm um pré-requisito a mais, explicado na seção 6.

Três regras valem para tudo:

1. Nada é escrito no seu Pipefy sem a sua aprovação explícita. Diagnóstico, ROI e deck são 100% leitura.
2. Ele usa a sua conta do Pipefy. Só enxerga e altera o que você já pode enxergar e alterar.
3. Tudo fica documentado em arquivos de texto numa pasta do seu computador. Dá para revisar, auditar e retomar um trabalho interrompido.

O que ele não é: não é um programa com janela própria. É um conjunto de roteiros (uma "skill") que ensina o Claude Code a se comportar como consultor de processos Pipefy, mais a conexão que liga o Claude Code ao seu Pipefy. Por isso a instalação passa pelo terminal.

Antes de começar

Duas palavras que você vai ver:

• Terminal: a janela onde você digita comandos em texto. No Windows chama-se PowerShell; no Mac, Terminal. Para abrir no Windows, aperte a tecla Windows, digite PowerShell e aperte Enter (não precisa ser "como administrador"). No Mac, aperte Cmd + Espaço, digite Terminal e aperte Enter.
• MCP: sigla de Model Context Protocol, o padrão que permite a um assistente de IA usar as ferramentas de outro sistema. A "conexão MCP do Pipefy" é o que deixa o Claude Code enxergar seus pipes. Ela é registrada automaticamente na instalação; você só faz o login.

Regra de ouro para não se perder: comandos que começam com / (como /mcp, /model, /exit) e as frases em português que aparecem nos blocos de código (pedidos ao Builder) são digitados dentro do Claude Code, na caixa de conversa. Todos os outros comandos são digitados no terminal, antes de abrir o Claude Code ou depois de sair dele com /exit. Cada passo abaixo diz onde digitar.

Nos comandos de terminal: copie a linha inteira, cole, aperte Enter e espere terminar (o cursor volta a piscar numa linha nova) antes de colar o próximo.

Instalação e primeiro uso

Passo 1: Instale o Builder (1 minuto)

No terminal, cole:

npm install -g @pipefy/pipefy-process-builder

O -g significa "global": o Builder fica disponível em qualquer pasta do seu computador. O instalador faz duas coisas: copia os roteiros do Builder para a pasta de skills do Claude Code e registra no Claude Code a conexão com o Pipefy (MCP). Ao terminar, procure na saída a confirmação das duas. A primeira é parecida com esta:

[pipefy-process-builder] skill installed to C:\Users\SEU_USUARIO\.claude\skills\pipefy-process-builder

(no Mac o caminho será /Users/seu_usuario/.claude/skills/pipefy-process-builder)

Se alguma das confirmações não apareceu, feche e abra o terminal e rode o comando de novo. Se persistir, registre pelo formulário de feedback (veja “Feedback”).

Alternativa sem instalação global: se preferir que o Builder exista só numa pasta específica, entre nessa pasta no terminal (com cd, como no Passo 2) e rode o mesmo comando sem o -g. Ele instala em .claude/skills/ dentro dessa pasta, e o Builder só aparece quando você abre o Claude Code a partir dela. Útil no Mac se o comando global der erro de permissão.

Passo 2: Abra o Claude Code e entre com a sua conta Pipefy (3 minutos)

No terminal, crie uma pasta de trabalho e entre nela. É onde o Builder vai guardar os arquivos de cada análise. Os comandos abaixo criam a pasta PipefyBuilder dentro de Documentos e entram nela (mkdir cria, cd entra):

Windows:

mkdir $HOME\Documents\PipefyBuilder; cd $HOME\Documents\PipefyBuilder

Mac:

mkdir -p ~/Documents/PipefyBuilder && cd ~/Documents/PipefyBuilder

Nas próximas vezes, basta o cd (a parte depois do ; no Windows ou do && no Mac).

Abra o Claude Code dentro dela:

claude

Se ele perguntar se você confia nos arquivos da pasta, responda que sim (a pergunta existe porque o Claude Code lê e escreve arquivos na pasta em que foi aberto; esta pasta é sua e está vazia).

Faça o login no Pipefy. Digite /mcp e aperte Enter. Aparece a lista de conexões; use as setas do teclado para selecionar pipefy e Enter para escolher autenticar. O navegador abre para você entrar com a sua conta Pipefy e aprovar o acesso. Use a conta que tem acesso aos pipes que você quer analisar. Esse login é feito uma vez; nas próximas conversas ele já vale.

Teste. Na caixa de conversa, escreva (troque "Compras" por parte do nome de um pipe seu):

Liste os pipes da minha organização cujo nome contém "Compras"

Se ele listar seus pipes, está tudo conectado.

Passo 3: Primeiro diagnóstico (2 a 10 minutos)

Escolha o modelo. Digite /model, aperte Enter e selecione um modelo da família Opus. Os roteiros do Builder foram desenhados para esse nível de modelo; com modelos menores a qualidade do resultado cai.

Confirme que o Builder está lá: digite / e comece a escrever pipefy. Deve aparecer /pipefy-process-builder na lista de sugestões. Aperte Esc para fechar a lista; não precisa selecionar. O Builder entra sozinho quando o pedido tem a ver com processo no Pipefy.

Pegue a URL do seu pipe: abra o pipe no Pipefy e copie o endereço da barra do navegador (algo como https://app.pipefy.com/pipes/301234567).

Peça o diagnóstico, na caixa de conversa:

Diagnostica o pipe https://app.pipefy.com/pipes/SEU_ID_AQUI

O Builder confirma em uma linha o que vai fazer, lê o pipe inteiro (fases, campos, automações, condicionais, agentes) e devolve um resumo executivo: quantos defeitos por severidade, os três achados mais importantes e o que você pode fazer em seguida. Dependendo do tamanho do pipe, leva de 2 a 10 minutos.

O relatório completo fica no arquivo diagnostico.md, dentro de Documentos > PipefyBuilder > builds > <nome-do-trabalho>. Ele abre em qualquer editor de texto (Bloco de Notas, TextEdit) e fica melhor formatado em editores que entendem Markdown (o formato de texto com marcações simples usado nesses arquivos), como o Visual Studio Code. Você também pode pedir ao Builder: "me mostra o diagnóstico completo".

O que a instalação coloca no seu computador

A instalação copia 22 arquivos de texto para a pasta .claude/skills/pipefy-process-builder/ do seu usuário e registra, nas configurações do Claude Code, a conexão com o servidor MCP da Pipefy. Nenhum programa fica rodando em segundo plano e nenhuma senha ou token do Pipefy é gravado no seu computador: o acesso é feito pelo login no navegador.

Como usar no dia a dia os cinco modos

Você não precisa escolher um modo. Peça em português; o Builder identifica o que você quer e confirma em uma linha. Se o pedido for ambíguo, ele oferece as opções.

• A — Diagnosticar: Um pipe já existe e você quer saber o que está quebrado, fora do padrão ou pode melhorar. Lê o pipe inteiro, lista defeitos por severidade com impacto e correção recomendada, avalia conformidade e aponta oportunidades. Gera diagnostico.md. Exemplo: "Diagnostica o pipe https://app.pipefy.com/pipes/123". Escreve no Pipefy? Não. Pré-requisito adicional: Nenhum.
• B — Criar: O processo ainda não existe no Pipefy. Descoberta com perguntas de múltipla escolha e recomendação marcada, proposta de desenho, resumo executivo, sua aprovação, construção, e uma conferência independente compara o construído com o aprovado. Exemplo: "Quero montar um processo de onboarding de fornecedores do zero". Escreve no Pipefy? Sim, só depois do seu "aprovado". Pré-requisito adicional: Instalação local do toolkit (veja “Limites que você precisa conhecer”).
• C — Evoluir: Um pipe existe e precisa mudar. Diagnóstico, plano de mudanças (adicionar, alterar, remover, manter) para você aprovar item a item, construção e conferência. Recomenda trabalhar numa cópia (clone) quando o pipe está em produção. Exemplo: "Preciso ajustar o pipe de Reembolso: https://app.pipefy.com/pipes/456". Escreve no Pipefy? Sim, só depois do seu "aprovado". Pré-requisito adicional: Instalação local do toolkit (veja “Limites que você precisa conhecer”).
• D — ROI: Você quer quantificar o retorno do processo. Parte do diagnóstico, pergunta investimento, benefício, período e premissas, e calcula ROI e payback (tempo de retorno). Separa economia de custo, ganho de produtividade, receita e horas economizadas. Sem dado suficiente, responde "ROI não calculável com segurança" e diz o que falta. Exemplo: "Quanto esse processo já economizou?". Escreve no Pipefy? Não. Pré-requisito adicional: Nenhum.
• E — Deck: Você precisa apresentar o resultado. Transforma o diagnóstico (e o ROI, se houver) num PDF: contexto, visão geral, achados, recomendações, roadmap e próximos passos. Todo número do deck vem do diagnóstico. Exemplo: "Monta um deck com esse diagnóstico para eu apresentar". Escreve no Pipefy? Não. Pré-requisito adicional: Nenhum.

Os modos D e E dependem de um diagnóstico feito antes (é o que impede o Builder de falar de um processo que ele não leu).

Como é a conversa

• Ele pergunta com opções. Em vez de perguntas abertas, oferece alternativas com a recomendação dele marcada. Você escolhe ou escreve o que preferir.
• Ele pede material primeiro. Se você tem um desenho do processo (fluxograma, ou BPMN, que é a notação padrão de desenho de processos), planilha, matriz de responsabilidades ou documento de escopo, copie o arquivo para a pasta PipefyBuilder (pelo Explorador de Arquivos ou Finder) e diga que está lá. Ele lê antes de perguntar, e o resultado melhora muito.
• Ele pergunta o perfil da empresa. Porte, país e idioma, e se a empresa permite agentes de IA. Isso define, por exemplo, idioma e fuso dos e-mails e se ele vai propor agentes de IA.
• Ele diz o que consegue entregar antes de você aprovar. Cada item do desenho recebe uma marca: Nativo (ele configura sozinho), Contorno (configura por caminho alternativo), Manual na UI (você configura à mão no Pipefy) ou Integração (exige a ferramenta de integrações do Pipefy). Sem surpresa depois.
• Nada é construído sem o seu "aprovado". Ele apresenta um resumo executivo do desenho e espera você aprovar explicitamente.
• A entrega diz o que foi feito e o que falta. Link do pipe, o que foi configurado (fases, campos, automações, agentes), as pendências manuais em destaque e a pasta de trabalho. Ele nunca diz só "pronto".
• Ele é consultivo. Se você discordar de uma proposta, ele avalia o seu argumento e responde com fundamento, em vez de concordar automaticamente.

A pasta de trabalho

Cada trabalho cria uma pasta builds/<cliente>-<dominio>-<data>/ dentro da pasta onde você abriu o Claude Code. O Builder chama a sua empresa de "cliente" no nome da pasta, e "domínio" é a área do processo (por exemplo, acme-compras-2026-09-24); ele define os dois a partir da conversa. Dentro ficam, conforme o modo:

• diagnostico.md (A, C, D, E)
• spec.md, changes.md, conferencia.md (B e C)
• roi-inputs.md, roi.md (D)
• deck.md, deck.html, deck.pdf (E)

Quais arquivos existem indica onde o trabalho parou. Para retomar um trabalho interrompido (a conversa caiu, o dia acabou, a cota do plano terminou), abra o Claude Code na mesma pasta e diga: "Continua o trabalho da pasta builds/acme-compras-2026-09-24" (o nome exato você vê abrindo a pasta builds no Explorador ou Finder). Ele segue da etapa pendente.

Depois de construir um pipe: a pendência mais importante

A API do Pipefy (a interface que o Builder usa para ler e escrever no Pipefy) não permite configurar para onde um card pode ser movido. Por isso todo pipe recém-criado nasce com as fases desconectadas: a estrutura está completa, mas nenhum card anda do início ao fim até alguém ligar as fases na aba Fluxo, nas configurações do pipe, na interface do Pipefy. O Builder entrega a lista exata de ligações a fazer (origem para destino, na ordem do fluxo). Faça isso antes de testar o pipe ou de pedir o teste funcional.

Extras que você pode pedir depois de uma construção

• Teste funcional: cria um card de teste e exercita o fluxo de verdade (obrigatórios travando, condicionais aparecendo, automações disparando). Como automações reais disparam (e-mails, por exemplo), use dados descartáveis e prefira fazer isso no clone, não no pipe de produção. Vale quando o processo vai direto para produção.
• Review completo: conferência de nomenclatura, boas práticas, coerência entre o aprovado e o construído e segurança, com veredito. Vale em entregas formais.
• Novo diagnóstico do pipe recém-criado, para uma varredura completa.

Ele oferece esses extras ao entregar, mas só roda se você pedir.

Dicas para bons resultados

1. Modelo Opus. Confira com /model no início de cada conversa.
2. Cole a URL do pipe, não só o nome. Evita ambiguidade quando há pipes com nomes parecidos.
3. Um processo por conversa. Para outro processo, digite /clear ou saia e entre de novo.
4. Pipe em produção? Aceite o clone. No modo C, o Builder recomenda aplicar as mudanças numa cópia quando o pipe tem volume de cards ou usuários ativos. Depois de validar no clone, peça para aplicar o mesmo plano no pipe original.
5. Agentes de IA só se você quiser. Ele recomenda de 2 a 3 pontos onde um agente agrega, com o ganho concreto de cada um, e você decide entrar. Nunca inclui por conta própria.
6. Consumo do plano Claude. O diagnóstico é o modo mais leve; ROI e deck quase não consultam o Pipefy; a construção (modo B) é a operação mais pesada. No plano Pro, faça construções num momento em que você não precise do Claude para outras coisas. Se a cota acabar no meio, nada se perde: o progresso fica registrado na pasta de trabalho e você retoma quando a cota renovar.

Limites que você precisa conhecer

• Criar e alterar pipes exige um passo a mais. A conexão que vem com a instalação usa o servidor MCP hospedado pela Pipefy, que é somente leitura: com ela o Builder diagnostica, calcula ROI e monta deck. Para os modos Criar e Evoluir, é preciso instalar o Pipefy AI Toolkit no seu computador, seguindo a seção de instalação local do post Como configurar o Pipefy AI Toolkit no seu assistente de IA . Envolve passos mais técnicos (um gerenciador de pacotes Python chamado uv, um token de acesso pessoal gerado em Meu Perfil no Pipefy e um arquivo de configuração), então peça ajuda ao TI se precisar. Se você pedir para criar ou alterar algo sem esse passo, o Builder não constrói: ele avisa que a conexão não permite escrita, ou você vê a mensagem "ferramenta não disponível". Como ele pode conduzir toda a conversa de descoberta antes de chegar nesse ponto, faça a instalação local antes de pedir uma construção.
• Ligação das fases é sempre manual (veja “Depois de construir um pipe”).
• Alguns itens a API do Pipefy não configura e ficam para você na interface: por exemplo, a descrição do pipe, a edição de templates de e-mail, aplicar etiqueta por automação e o layout de Interfaces e Portais. O Builder marca cada um como "Manual na UI" antes de você aprovar, então você sabe de antemão o que vai sobrar.
• Idioma: o Builder conversa em português.
• Pipefy com endereço próprio (suaempresa.pipefy.com em vez de app.pipefy.com): a conexão padrão pode não enxergar seus pipes e devolver "PERMISSION_DENIED". Nesse caso a conexão precisa ser configurada para o seu endereço, pela instalação local. Abra um chamado com o suporte da Pipefy.
• Deck em PDF depende de um navegador instalado. O modo E gera o PDF com o Microsoft Edge (Windows, já vem instalado) ou o Google Chrome (Mac). Sem eles, você recebe o deck em HTML, que abre em qualquer navegador.
• Codex e outros assistentes. A instalação coloca o Builder na pasta do Claude Code. No Codex, em princípio é possível copiar a pasta da skill manualmente e configurar o MCP por lá, mas esse caminho ainda não foi testado nem documentado. Comece pelo Claude Code.
• Versão. Se você perguntar ao Builder "qual versão está rodando", ele responde com a versão dos roteiros (por exemplo, "3.03"). A versão do pacote instalado, que é a que interessa para reportar problemas, você vê no terminal (depois de sair do Claude Code com /exit) com npm list -g @pipefy/pipefy-process-builder.

Atualizar ou remover

Os comandos desta seção são digitados no terminal, fora do Claude Code.

O time da Pipefy publica melhorias no mesmo pacote. Para atualizar (o instalador substitui os arquivos e remove os que deixaram de existir):

npm install -g @pipefy/pipefy-process-builder@latest

Para ver a versão instalada:

npm list -g @pipefy/pipefy-process-builder

Para remover o pacote:

npm uninstall -g @pipefy/pipefy-process-builder

Depois, apague a pasta pipefy-process-builder que está em C:\Users\SEU_USUARIO\.claude\skills\ (Windows) ou /Users/seu_usuario/.claude/skills/ (Mac): o npm uninstall remove o pacote, mas não essa cópia. A pasta .claude fica oculta por padrão; no Windows, ative "Itens ocultos" no Explorador; no Mac, aperte Cmd + Shift + . no Finder. Para remover também a conexão com o Pipefy:

claude mcp remove pipefy

Os arquivos em builds/ são seus e não são afetados. Se você instalou sem -g (alternativa do Passo 1), rode os comandos npm sem -g, dentro da pasta onde instalou.

Perguntas frequentes

Ele pode mexer no meu Pipefy sem autorização?

Não. Diagnóstico, ROI e deck usam a conexão de leitura. Criar e evoluir exigem configuração local de escrita e aprovação explícita.

Preciso saber programar?

Não para instalar e diagnosticar: você executa um comando, entra na sua conta e conversa em português. A configuração local necessária para construir tem passos técnicos e pode exigir ajuda do TI.

Quanto custa?

O Builder é gratuito, mas exige Claude Code em um plano pago da Anthropic. O consumo varia conforme o tamanho do pipe e o modo; a construção consome mais que o diagnóstico.

Funciona no Windows e no Mac?

Sim, em versões compatíveis com o Claude Code. Consulte os requisitos atuais dele para o seu sistema.

Ele constrói o processo sozinho?

Ele propõe um desenho, espera sua aprovação, constrói o que a conexão local permite e confere. A ligação entre fases e alguns outros ajustes precisam ser feitos na interface do Pipefy.

Funciona em qualquer tipo de processo?

Ele pode diagnosticar e construir diferentes tipos de pipe. Seu catálogo de padrões é mais aprofundado em compras e suprimentos.

Em que idioma conversa?

Em português.

Substitui um consultor?

Ele aplica uma abordagem consultiva a um processo por vez, com você no controle. Para transformações grandes, considere o time de Professional Services da Pipefy.

Onde reporto problemas?

Use o formulário de feedback indicado acima. Informe o pedido, a resposta, a versão do pacote e, se possível, o arquivo correspondente da pasta de trabalho, removendo dados pessoais e de clientes.

Antes de avançar, confirme que você entende:

☐ Diagnóstico, ROI e deck usam apenas leitura.

☐ Criar e evoluir exigem configuração local e sua aprovação.

☐ A ligação das fases precisa ser feita na interface antes do teste.