Pi for design.

What Pi actually is

Pi is an open-source (MIT) AI coding agent for the terminal, part of the earendil-works pi toolkit. It reads your repository, edits files, and runs shell commands — planning and verifying work from natural-language tasks rather than just completing lines. Its core is deliberately small: four default tools — read, write, edit, and bash — plus built-in grep, find, and ls.

For design work, the standout property is that Pi is provider-agnostic. It normalizes across Anthropic, OpenAI, Google and many other providers behind one unified API, so you bring your own keys and choose the model per task — for example a strong multimodal model to read reference screenshots — and switch with /model or Ctrl+L mid-session without changing your workflow.

• Any model, your keys: Pi routes to 20+ providers including Anthropic and OpenAI. You authenticate with your own API keys (BYOK), or sign in to a Claude Pro/Max, ChatGPT Plus/Pro, or GitHub Copilot subscription with /login.
• Skills + Extensions: Pi loads Skills (Markdown capability packages following the Agent Skills standard) and TypeScript Extensions — the natural place to encode your design conventions and add custom tools.
• Branching sessions: Sessions are stored as JSONL trees, so you can branch an exploration and navigate history in a single file without losing earlier passes.

• Vendor: earendil-works (open-source community project)
• Credential: your own provider API key (BYOK — Anthropic, OpenAI, Google, etc.) or a subscription login via /login; stored locally in ~/.pi/agent/auth.json (0600)
• License: MIT, open source

Why a multi-provider, BYOK agent fits design

Pi’s design edge is flexibility, not a single built-in model — but, as with every agent, taste still has to be supplied.

• Pick the right model per task: Because Pi routes to any provider, you can reach for a strong multimodal model to read reference screenshots, then switch to another for refactoring — without leaving the agent.
• Your keys, no lock-in: BYOK means you are not tied to one vendor’s pricing or context limits; choose the model whose strengths fit the design job in front of you.
• Conventions in Skills: A Skill (plus an MCP source like a Figma server) points the agent at your tokens, components, and real specs, so it works against a brand instead of a default look.

The lesson is the same one every agent teaches: Pi does not have taste by default, and no model choice supplies it. It produces good design when you give it constraints — a design system, an aesthetic skill, and concrete references. Open Design packages exactly those inputs, which is why the two fit together (more below).

Set up Pi for design work, from zero

Here is the full path from a clean machine to a Pi that can build and verify UI.

# 1. Install the Pi coding agent CLI (Node)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 2. Authenticate with your own provider key (BYOK)
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY=sk-...
#    (or run /login inside Pi for a Claude / ChatGPT / Copilot subscription)

# 3. Start it in your project
cd your-project
pi

# 4. Switch models any time with /model or Ctrl+L

• Encode your design rules: Put your tokens, primitives, and conventions in a Skill and point Pi at them, so output matches a brand instead of defaulting to a generic look.
• Add browser verification: Wire a Playwright or browser MCP so Pi renders in a real browser and checks its output across breakpoints instead of only confirming the build passes.

The screenshot-to-UI workflow

The highest-leverage design loop with Pi is turning a reference image into working, responsive UI and iterating until it matches — leaning on a multimodal model to compare output back to the reference. Because Pi is provider-agnostic, point it at whichever model reads images best for this pass.

1. Start from the clearest visual references you have — and include multiple states (desktop and mobile, hover, empty, loading), not just one hero shot.
2. Pick a strong multimodal model for the pass with /model, since image understanding is what drives screenshot-to-UI quality.
3. Be specific in the prompt; vague prompts produce generic UI even with a strong model.
4. Keep your design system and conventions in a Skill, and tell Pi where the tokens and canonical primitives live.
5. Run a dev server and have Pi render in a real browser, resizing to breakpoints, then iterate by comparing its implementation back to the screenshots — not merely confirm it builds.

Give the agent the references and concrete constraints up front:

pi
# in the prompt:
> Implement reference-desktop.png and reference-mobile.png in
  React + Vite + Tailwind + TypeScript.
  Reuse my existing design-system components and tokens (see the Skill).
  Match spacing, layout, and hierarchy; make it responsive.
  Render it in the browser and iterate until it matches the references
  across breakpoints.

Keep prompts small and focused, commit good iterations and revert bad ones (telling Pi when you revert), so each pass builds on a clean base. Pi’s branching JSONL sessions also let you explore an alternative without losing the original thread.

Skills, Extensions, and themes

Pi self-extends at runtime through a few layers, and they map cleanly onto an open design workflow.

• Skills: Markdown capability packages following the Agent Skills standard — the durable, portable home for your design conventions, tokens, and review checklists. The same Skill works across compatible agents, not just Pi.
• Extensions and prompt templates: TypeScript Extensions add custom tools, commands, and UI; reusable prompt templates run via /name. Both let you script the verification loop without leaving the terminal.
• MCP and themes: Pi connects to MCP servers to bring in external design context (most relevantly a Figma MCP server), and themes hot-reload so the terminal UI stays readable while you work.

These are portable capabilities — Skills and MCP especially — exactly the kind of thing Open Design is built to orchestrate, rather than re-create per project.

Pi vs Codex vs Claude Code vs Cursor vs Gemini CLI for design

There is no single winner for design work — each agent has a different strength, and experienced teams stack them. A fair summary:

Pi’s angle is orthogonal to the others: it is the agent that lets you use any of those underlying models on your own keys. The recurring community verdict still holds — taste comes from humans: all of them default to a generic aesthetic without skills, references, and constraints. That is the real problem to solve, and it is design-tool-shaped, not model-shaped.

Pitfalls, and how to avoid the “AI slop” look

The most common complaint about AI-generated design is that it looks generic — soft gradients, floating panels, oversized rounded corners, dramatic shadows, an Inter-and-purple vibe that “screams an AI made this.” Other reported issues include broken mobile layouts and instructions leaking into UI copy. None of these are unique to Pi or to any one model; they are what happens when any agent runs without a curated design context.

• Add an aesthetic skill: A curated design skill forces the agent to commit to a real direction instead of the default look — and since it is a portable Skill, it travels with you across models.
• Verify in a real browser: Pick a multimodal model and have Pi render and self-check across breakpoints so layouts do not silently break on mobile.
• Supply tokens and references: Real design tokens and reference screenshots are the single biggest lever on output quality.
• Encode rules where Pi reads them: Put “no hero cards, max two typefaces, brand-first hierarchy” style rules in a Skill the agent loads every run.

Notice that every mitigation is about giving the agent a curated design context — independent of which provider you route to. Maintaining that context by hand, per project, is the toil Open Design removes.

Designing with Pi inside Open Design

Open Design is the open-source design layer the workflow above keeps asking for. It treats Pi as a first-party adapter and wraps it in a curated skill and design-system library, a structured render pipeline, and a local desktop UI — so the design context that makes Pi good is there from the first run, not assembled by hand each time. Both are open-source and local-first, which makes the pairing a natural fit.

1. Install Open Design and select Pi as your agent.
2. Authenticate with your own provider API key (BYOK) or a subscription login — credentials stay on your machine in ~/.pi/agent/auth.json and are never proxied through us.
3. Pick a design system and a skill, then generate decks, prototypes, and landing pages with consistent taste.
4. Every artifact and DESIGN.md file lives in your own repo, not a hosted cloud.

Same Pi agent, same keys, same freedom to switch models — plus a real, portable, open-source design workflow around it. It is local-first and MIT, so nothing about your work or your credentials leaves your machine.

Frequently asked questions

1. 01 Can Pi really do design work? +

   Yes — with an aesthetic skill, a design system, and real reference images in context, Pi produces production-quality, responsive UI, and you can route it to a strong multimodal model to verify output against references. Without that context it tends to default to a generic look, which is the gap Open Design fills.

2. 02 Do I need to pay to design with Pi? +

   Pi itself is free and open source (MIT). You pay only for the underlying model — bring your own provider API key (BYOK), or use a Claude Pro/Max, ChatGPT Plus/Pro, or GitHub Copilot subscription via /login. Open Design never proxies your credentials either way.

3. 03 What makes Pi good for design specifically? +

   It is provider-agnostic: you bring your own keys and route to any of 20+ providers, picking the model whose strengths fit the task and switching mid-session. But taste still comes from the design system, skill, and references you supply, not from the model.

4. 04 Which model should I use with Pi for frontend design? +

   Pi routes to many providers, so choose per task — a strong multimodal model reads reference screenshots well, while others may suit refactoring. The advantage of Pi is that you can switch without changing your workflow. Open Design lets you keep the same design context across whichever model you pick.

5. 05 How do I connect Pi to Figma? +

   Pi supports MCP servers, so you can add a Figma MCP server and pull real design context — components, variables, layout data — so the generated code matches the source instead of approximating it.

6. 06 Is Open Design affiliated with Pi? +

   No. Pi is an independent open-source project from earendil-works; Open Design is a separate independent open-source project that supports Pi as a first-party adapter.

7. 07 Are my files and credentials safe? +

   Yes — Open Design is local-first and open source. Your files, artifacts, and DESIGN.md stay in your own repo, and your provider keys are used directly by Pi (stored locally in ~/.pi/agent/auth.json), never routed through Open Design servers.