As processes grow, their rules, fields, and automations deserve a careful review before changes are made. Process Builder helps you assess a pipe and decide what to do next based on its findings.

By the end of this article, you will know how to install the Builder, connect your account, run a first diagnosis, use its five modes, and recognize the steps that require approval or manual setup.

📖 What you will learn:

What Process Builder does

Pipefy Process Builder is a process consultant that runs inside Claude Code, Anthropic's terminal based AI assistant. You can ask it in Portuguese to diagnose an existing pipe, estimate ROI using only figures you provide, and build a PDF deck based on the diagnosis. It can also design and build a new pipe or evolve an existing one after you approve the proposed changes.

A diagnosis checks rules, required fields, automations, conditionals, and AI agents. Findings include severity, impact, and a recommended correction. If the data is insufficient to calculate ROI safely, the Builder says so.

Three principles apply to every mode: nothing is written to Pipefy without your explicit approval; the Builder uses your Pipefy account and its existing permissions; and its work is recorded in local text files so you can review and resume it. It is a set of instructions for Claude Code and a Pipefy MCP connection, rather than a separate desktop app.

Before you begin

• Pipefy account: Access to the pipes you want to analyze. You must be their admin to create or change them.
• Claude Code: Install it and sign in with an eligible paid Anthropic plan. Run the Claude Code version command in your terminal to check the installation.
• Node.js and npm: Run the npm version command in your terminal. If npm is missing, install the LTS version from https://nodejs.org and reopen the terminal.
• Time: Allow about five minutes to install and connect, then approximately two to ten minutes for the first diagnosis.
• Technical experience: You do not need to code for the first diagnosis.

The terminal is PowerShell on Windows or Terminal on Mac. MCP, or Model Context Protocol, connects Claude Code to your Pipefy account. Commands starting with a slash, such as /mcp and /model, belong in the Claude Code conversation. Installation commands belong in the terminal.

Install and run your first diagnosis

Step 1: Install the Builder

In the terminal, run:

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

The global option makes the Builder available from any folder. The installer copies its instructions into Claude Code and registers the Pipefy MCP connection. Check that both confirmations appear. If either is missing, reopen the terminal and retry. You can also install without the global option inside a specific folder, which limits availability to that folder.

Step 2: Open Claude Code and connect Pipefy

Create a working folder, such as PipefyBuilder in Documents, then open a terminal in that folder and run the following command:

claude

If Claude Code asks whether you trust the folder, confirm. In Claude Code, type /mcp, select pipefy, and choose to authenticate. Sign in with the Pipefy account that has access to your target pipes. To test the connection, ask it to list the pipes in your organization whose names contain a word from one of your pipes. You only need to complete the browser sign in once.

Step 3: Ask for a diagnosis

In Claude Code, use /model to select an Opus family model. Type / and start entering pipefy to confirm that the Builder is available; you do not need to choose it manually. Copy the URL of a pipe you can access, then ask in Portuguese:

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

The Builder reads the pipe and reports the number of findings by severity, its three main findings, and recommended next actions. The full report is saved as diagnostico.md under the builds folder in your working directory. You can also ask it to show you the complete diagnosis in the conversation.

What the installation adds

It copies the main instruction file, supporting references, and an optional email template component into the Claude Code skills folder. It also registers the pipefy MCP connection. The login takes place in a browser; no Pipefy password or token is stored locally by this default connection, and no background application needs to keep running.

The five modes

• Diagnose: Inspect an existing pipe, classify findings by severity, and create diagnostico.md. Read only; no extra setup.
• Create: Discover requirements, propose a design, wait for your approval, build, and independently compare the result with the approved design. Requires a local Pipefy AI Toolkit installation with write access.
• Evolve: Diagnose an existing pipe, present changes for your approval item by item, apply them, and check the result. For an active pipe, work on a clone first. Also requires local write setup.
• ROI: Starting from a diagnosis, request investment, benefits, period, and assumptions. Separate cost savings, productivity, revenue, and hours; calculate ROI and payback only when the input supports it. Read only.
• Deck: Turn a diagnosis and any available ROI into a PDF presentation whose figures come from the diagnosis. Read only.

You can simply describe your goal in Portuguese. The Builder selects a mode and asks you to clarify an ambiguous request. ROI and deck require a prior diagnosis.

How the conversation and saved work operate

During discovery, the Builder offers choices and marks its recommendation. Give it any process diagram, spreadsheet, responsibility matrix, or scope document before the questions start. It asks about company size, country, language, and whether AI agents are allowed. For each proposed element it distinguishes native configuration, workaround, manual Pipefy setup, and integration. It waits for explicit approval before building.

Each job creates a folder under builds in the directory where you opened Claude Code. Depending on the mode, it can contain the diagnosis, specification, change plan, independent check, ROI inputs and results, or deck files. To resume, open Claude Code in the same working folder and ask it to continue the job in the appropriate builds subfolder.

For a good result, include the pipe URL, focus on one process per conversation, and choose Opus. When evolving a production pipe, validate on a clone before applying the approved plan to the original. AI agents are optional and require your choice. If your Claude quota runs out, resume from the saved files when it renews.

Manual steps and technical limits

⚠ The default hosted Pipefy MCP connection is read only. Creating or evolving a pipe requires the local Pipefy AI Toolkit installation described in How to set up the Pipefy AI Toolkit in your AI Assistant. That setup uses uv, a Pipefy personal access token, and a configuration file. Complete it before starting a build and seek IT help if needed.

⚠ Newly created pipes have disconnected phases because the Pipefy API cannot set card movement destinations. The Builder gives you the exact phase connections to add in the pipe's Flow tab. Do this before testing.

Some settings, such as the pipe description, editing email templates, applying labels through automation, and Interfaces or Portals layouts, also need manual work in Pipefy. The Builder identifies them before approval. The Builder speaks Portuguese. If your organization uses a custom Pipefy domain, the default connection may need local configuration; contact Pipefy support if you encounter a permission error.

The PDF deck requires Microsoft Edge on Windows or Google Chrome on Mac. Without a supported browser, the Builder provides HTML. To identify the installed package version for support, leave Claude Code with /exit and run the npm list command below.

After a build, you can request a functional test with disposable data, preferably in a clone, because real automations can send messages. You can also request a complete review or another diagnosis. These extras run only when you ask.

Update or remove the Builder

Run these commands in the terminal, outside Claude Code.

To update:

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

To check the installed version:

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

To uninstall:

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

After uninstalling, manually remove the pipefy-process-builder folder from your Claude Code skills directory. To remove its connection, run:

claude mcp remove pipefy

Your own files in builds remain in place. If you installed without the global option, run npm commands without that option from the installation folder.

Frequently asked questions

Can it change my Pipefy account without permission?

No. Diagnosis, ROI, and deck use a read only connection. Create and Evolve require local write setup and your explicit approval.

Do I need to know how to code?

No for installation and diagnosis: run one command, sign in, and converse in Portuguese. The local setup for building is more technical, and your IT team can help.

How much does it cost?

The Builder is free, but Claude Code requires a paid Anthropic plan. Usage depends on the pipe size and mode; building generally consumes more of your plan than diagnosing.

Does it work on Windows and Mac?

Yes, on versions supported by Claude Code. Check its current requirements for your operating system.

Does it build everything by itself?

It proposes a design, waits for approval, builds what the local connection supports, and checks the result. Phase connections and other items still require manual configuration in Pipefy.

Can it work with any kind of process?

It can diagnose and build pipes in different areas. Its pattern catalog is deepest for procurement and supply chain processes.

Which language does it use?

Portuguese.

Does it replace a consultant?

It applies a consultative approach to one process at a time with you in control. For broad transformations, consider Pipefy Professional Services.

Where can I report a problem?

Use the feedback form above. Include the request, response, package version, and relevant file after removing personal or customer information.

Before moving on, confirm that you understand:

☐ Diagnosis, ROI, and deck are read only.

☐ Create and Evolve require local setup and explicit approval.

☐ You must connect the phases in Pipefy before testing a new pipe.