How to Use Piezas in Claude

Once Piezas is connected (see Install Piezas in Claude), you build by describing what you need. Claude plans the app with you, builds it on Piezas, checks it and publishes it. Pick the section that matches how you use Claude.

You need a Piezas account and Node.js (the LTS version, from nodejs.org) on your computer.

In the Claude desktop app

1. Start. Open the Code tab, choose a new, empty folder, and say "Set up this folder for a new Piezas app".
2. Sign in. The first time, Claude posts a Sign in to Piezas link for the project's checks. Open it, check the code matches, and click Approve. Use the same account you connected.
3. Answer the first question: "Starting fresh, or do you already have an app?" Starting fresh, Claude asks for the app's name and creates it in your account. Already have one, tell Claude where its folder is. It copies the app into the new folder and never changes your original.
4. Switch on the checks. If Claude asks whether you trust the folder, click Trust workspace, then start a new session in the same folder.
5. Describe it. Claude asks you one question at a time and writes the plan.
6. Check the preview. You get a clickable preview with sample data. Ask for any changes. When you're happy, reply approve. Only your own reply counts.
7. Let it build. Claude builds the real app. Checks run as it works and stop anything that breaks Piezas's rules.
8. Add any settings. If the app needs a key or setting, Claude tells you what's missing and where to set it: your app's page at app.piezas.ai. Never paste keys into the chat.
9. Go live. Claude publishes the app and gives you its address. The Report a problem button stays on unless you ask to turn it off. If something still needs your decision, Claude pauses once and explains it. Only you can reply deploy anyway.

Later, open a session in the same folder to change the app. If people reported problems with the Report a problem button, Claude tells you and offers to fix them all at once.

You can also plan in an ordinary chat on claude.ai: turn Piezas on under +, then Connectors, and describe your idea. When the plan is ready, continue in the Code tab to build it.

In the terminal (Claude Code)

In the terminal you can work with the Piezas connector, with the Piezas command line (npx piezas), or with both.

With the connector

1. Check the connector is there. Start claude in a new, empty folder and type /mcp. If you added Piezas on claude.ai, it is listed as claude.ai Piezas. If it isn't listed, add it once:

   claude mcp add --transport http piezas https://mcp.piezas.ai/claude

   Then type /mcp, choose piezas, and follow the sign-in link.

2. Start. Say "Set up this folder for a new Piezas app".

3. Switch on the checks. Say yes when Claude Code asks whether you trust the folder, then start a new session in the same folder.

4. Continue as in the desktop app, from step 5: describe it, approve the preview, let it build, add settings and go live.

With the command line

1. Set up the project. In a new, empty folder, run:

   npx piezas@latest login

   npx piezas@latest init

   login opens your browser so you can approve the sign-in. init creates your app, connects the folder to it, and adds the Piezas rules, the checks and a guided spec mode.

2. Describe it. Start claude in the folder and run /piezas-spec followed by your idea. Claude asks you one question at a time, then writes SPEC.md.

3. Build. Say "Build this from SPEC.md." Review and refine in plain words.

4. Check and publish. Ask Claude to check and publish the app, or run:

   npx piezas test

   npx piezas deploy

   test runs the app's checks. deploy publishes the app and prints its address. Set any keys or settings on your app's page at app.piezas.ai, or with npx piezas env set NAME=value. Never paste them into the chat.

Useful commands:

• npx piezas whoami shows which account you are signed in to.
• npx piezas doctor checks the project is ready.
• npx piezas deploy --status shows whether the app is up and which version is live.
• npx piezas deploy --logs shows the app's logs.

Using both

The connector and the command line work together in the same folder. The connector lets Claude list and create apps, read the Piezas rules and publish. The command line adds the checks that run on your computer while Claude works. Every publish goes through the same Piezas checks, whichever one Claude uses.

If something doesn't work

• Claude says Node.js is missing. Install the LTS version from nodejs.org, restart Claude and start a new session.
• Claude says it can't build or publish from a chat. Building needs a folder for the app's files. Continue in the Code tab or in the terminal.
• A change was stopped. That is a Piezas check working. Claude explains why in one sentence and does it the Piezas way instead. If you want it anyway, you decide: say so, and Claude continues.
• Piezas tools show up twice in the terminal. You added Piezas both on claude.ai and with claude mcp add. Remove one: claude mcp remove piezas.

Privacy and support

How Piezas handles your information: Privacy Policy. Questions or problems: Get support.