Penpot Wizard

An AI-powered chat assistant plugin for Penpot that uses a multi-agent architecture to help with design tasks, provide guidance, and create designs directly in projects.

Table of Contents

• What is Penpot Wizard?
• Try it Out
• Getting Started
  • Prerequisites
  • Installation
  • Configure API Keys
• Architecture
• Extending the Plugin
  • Agents
  • Tools
  • RAG Tools
  • Plugin Communication
  • Shape Reference
  • Path Commands
• Development
• Troubleshooting
• Resources
• License & Contributing

---

What is Penpot Wizard?

Penpot Wizard is a plugin for Penpot that brings AI assistance into your design workflow. It includes:

• Multi-Agent Architecture: Director agents orchestrate coordinators, specialized agents, and tools
• AI Integration: Supports OpenAI and OpenRouter
• RAG System: Search Penpot documentation and design styles
• Direct Drawing: Create shapes, paths, text, boards, components, and icons in Penpot
• Chat Interface: Streaming responses, conversation history, multiple agents

---

Try it Out

We have a small website explaining the project at aipenpotwizard.app.

A free hosted version of the plugin is available at penpot-ai-wizard-plugin-website.vercel.app — no local setup required.

For installation instructions, visit aipenpotwizard.app/install.

---

Getting Started

Prerequisites

• Node.js 18 or higher
• npm or yarn
• OpenAI API key or OpenRouter API key
• Penpot account

Installation

1. Clone and install

   git clone <repository-url>
   cd penpot-wizard
   npm install

2. Build for Penpot

   npm run dev:penpot

   This builds the plugin and watches for UI changes. The UI is served at http://localhost:5174.

3. Load the plugin in Penpot

   • Open Penpot and go to a project
   • Menu → Plugins → Manage plugins
   • Install from file
   • Select the dist folder from this project

Configure API Keys

• Click the settings icon in the plugin
• Enter your OpenAI or OpenRouter API key
• Click "Check API Keys" and select a model from the dropdown

---

Architecture

The system has three layers: the Plugin (runs in Penpot, creates shapes, accesses data), the UI (React app in an iframe), and Stores (nanostores for state). Director agents orchestrate tools, capability agents, coordinators, and specialized agents. Communication between UI and plugin uses postMessage.

See docs/ARCHITECTURE.md for diagrams and details.

---

Extending the Plugin

Agents

There are four agent types: Director (main orchestrator, e.g. PenpotWizard), Capability (domain experts in src/assets/agents/: designer, planner, drawer, component-builder, prototyper, illustrator, modifier), Coordinator (project orchestration), and Specialized (legacy domain experts). Agent definitions are consolidated in src/assets/agents/agents.js. Image generation and placement are handled by tools (generate-image, set-image-from-url) in imageTools.js. Agents use toolIds and specializedAgentIds to compose tools and sub-agents.

See docs/AGENTS_GUIDE.md for how to create custom agents.

Tools

Tools are defined in src/assets/ (functionTools, toolsCreateShapes, toolsModifyShapes, toolsCompoundShapes, toolsLayoutShapes, toolsInteractions, toolsFlows, toolsReorderShapes, toolsTokens, ragTools, iconsTool). All tools share the structure: id, name, description, inputSchema, function. Shape tools include create-rectangle, create-ellipse, create-text, create-path, create-board, modify-*, create-boolean, group-shapes, align-shapes, interactions, flows, design tokens (get/create/modify/apply), draw-icon, and more.

See docs/EXTENDING_TOOLS.md for how to add new tools.

RAG Tools

RAG tools search vector databases (Orama) for documentation. Databases are generated by orama-persistence-generator and placed in public/. Existing RAGs: penpot-user-guide-rag, design-styles-rag. Icons are searched via iconsTool.js using a separate icons RAG (iconsRagToolContents.zip). Embedding models: Orama (browser) or OpenAI (precomputed).

See docs/CREATING_RAGS.md for creating and adding RAG tools.

Plugin Communication

The UI sends queries via postMessage using ClientQueryType. Handlers live in mainHandlers.js and drawHandlers/ (folder with specialized handlers). To add a new operation: define a ClientQueryType, implement a handler, and create a tool that calls sendMessageToPlugin.

See docs/PLUGIN_COMMUNICATION.md for the full protocol and examples.

Shape Reference

Shapes use schemas from src/types/shapeTypes.js: fills (color, gradient, image), strokes, shadows, blur, flex/grid layouts. Key rule: create foreground elements first, backgrounds last. Types: rectangle, ellipse, path, text.

See docs/SHAPE_REFERENCE.md for schema details.

Path Commands

Path shapes use a content array of commands (M, L, H, V, C, S, Q, T, A, Z). Use pathCommandsToSvgString() in the plugin to convert to SVG.

See docs/PATH_COMMANDS_GUIDE.md for syntax and examples.

---

Development

Scripts: npm run dev (UI only), npm run dev:penpot (plugin + watch), npm run build, npm run test, npm run lint. Project structure: src/assets (agents, tools), src/plugin (Penpot handlers), src/stores (state), src/types (schemas).

See docs/DEVELOPMENT.md for full setup and structure.

---

Troubleshooting

Issue	Solution
"Not connected"	Check API key, click "Check API Keys", verify credits
Streaming stops	Check network, rate limits, reload plugin
Tool not available	Verify tool ID in agent's toolIds, reload plugin
RAG returns nothing	Ensure .zip in public/, use specific English queries
Path drawing error	Use valid path commands, ensure Z has no params; see PATH_COMMANDS_GUIDE.md
Plugin not loading	Rebuild with npm run build, check dist/, re-add plugin in Penpot

---

Resources

• Penpot Plugin API
• Vercel AI SDK
• nanostores
• Orama
• Zod

---

License & Contributing

This project is licensed under the MIT License. For contributions, please read the contribution guidelines and submit pull requests.