<div align="center">

🎨 Picasso Orchestrator

1. Gate-scored bidirectional loop: Claude Code ↔ Claude Design. Brief → DESIGN.md → Generate → Implement → Score → Refine.<br/>2. Runs locally with <a href="https://github.com/nexu-io/open-design">open-design</a> — no Pro+ required · 71 brand systems · auto-detected engine.

<br/>

<img src="docs/banner.svg" alt="Picasso · Claude Design ↔ Claude Code Bridge Loop" width="100%"/>

<br/><br/>

<br/>

<br/>

</div>

Stop guessing if your implementation matches the design. Let the loop prove it.

>

Picasso connects Claude Code to Claude Design in a closed feedback loop — structured brief in, verified code out, with a mathematically scored fidelity gate between them. No more "looks close enough." Either the score hits 9.0 / 10 or the loop keeps going.

⚡ Quick start — 3 steps, 30 seconds

# 01 · Install (one-liner — patches ~/.claude automatically)
curl -fsSL https://cdn.jsdelivr.net/gh/RazvanGabrielNiculae/picasso-claude-design-claude-code-bridge-loop@main/scripts/install-oneliner.sh | bash

# 02 · Verify everything is wired correctly
picasso-bridge verify --smoke

# 03 · Run your first bridge loop
/picasso --design-loop "hero cinematic for B2B SaaS" --scope complex

💡 Need a guided setup? Add --wizard to the install command. It walks you through gate, max rounds, and hook wiring interactively.

🔁 How it works

flowchart LR
    A([picasso]) --> B[ASSUMPTIONS] --> C[DESIGN.md] --> D[Claude Design] --> E[Implement] --> F[Render] --> G[Score] --> H{Gate 9.0}
    H -- "✅" --> I([APPROVED])
    H -- "📉" --> J([STAGNATED])
    H -- "🔄 refine" --> D

    style A fill:#ff2d95,stroke:#ff4fa8,color:#fff
    style B fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style C fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style D fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style E fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style F fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style G fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style H fill:#2a2000,stroke:#ffd83d,color:#fff59d
    style I fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style J fill:#2e1a0d,stroke:#ff9800,color:#ffb14a

1. Brief → Describe your design goal in plain language (/picasso --design-loop "hero for B2B SaaS")
2. ASSUMPTIONS → Picasso surfaces inferred tokens as an explicit block before any browser call — you correct inline
3. DESIGN.md → Structured 9-section spec is generated: colors · typography · layout · motion · responsive · accessibility
4. Claude Design → Picasso sends a structured prompt, captures the visual proposal via screenshot
5. Implement → Zero-context subagent applies only the changed DESIGN.md sections (~200 tok vs 2,000 naive)
6. Render → Desktop always · mobile only if previous responsive score < 8.0
7. Score → Weighted gate: ΔE colors (25%) · typography (20%) · layout (20%) · components (15%) · motion (10%) · responsive (10%)
8. Gaps → 3 lines max · goal-declared format: current → target · passed to next round
9. Gate → score ≥ 9.0 → ✅ APPROVED · plateau → STAGNATED · else → refine and repeat from step 4

📊 By the numbers

🔧 Prerequisites

🔄 The loop — 7 steps per round

flowchart LR
    S1[Request] --> S2[Extract] --> S3[Implement] --> S4[Render] --> S5[Score] --> S6[Gaps] --> S7{Gate}
    S7 -- "✅ ≥9.0" --> AP([APPROVED])
    S7 -- "📉 plateau" --> ST([STAGNATED])
    S7 -- "🔄 retry" --> S1

    style S1 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style S2 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style S3 fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style S4 fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style S5 fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style S6 fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style S7 fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style AP fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style ST fill:#2e1a0d,stroke:#ff9800,color:#ffb14a

🏗️ Architecture — component map

flowchart LR
    subgraph CC["Claude Code"]
        PC[picasso] --> PDL[pdl-conductor]
        HK[6 hooks] --> PDL
        PDL --> DM["DESIGN.md"]
    end
    subgraph MCP["MCP"]
        CMCP[chrome-mcp]
        WMCP[webdesign-mcp]
    end
    CD[Claude Design]

    PDL --> CMCP --> CD
    CD --> CMCP --> PDL
    PDL --> WMCP

    style CC fill:#1b0d14,stroke:#ff2d95,color:#ffa2cf
    style MCP fill:#0a1520,stroke:#5ce1ff,color:#8eecff
    style PC fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style PDL fill:#ff2d95,stroke:#ff4fa8,color:#fff
    style HK fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style DM fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style CMCP fill:#0a1520,stroke:#5ce1ff,color:#8eecff
    style WMCP fill:#0a1520,stroke:#5ce1ff,color:#8eecff
    style CD fill:#0d2e1a,stroke:#7cf0a0,color:#7cf0a0
    linkStyle 0 stroke:#ffd83d,stroke-width:2px
    linkStyle 1 stroke:#ffd83d,stroke-width:2px
    linkStyle 2 stroke:#ffd83d,stroke-width:2px
    linkStyle 3 stroke:#ffd83d,stroke-width:2px
    linkStyle 4 stroke:#ffd83d,stroke-width:2px
    linkStyle 5 stroke:#ffd83d,stroke-width:2px
    linkStyle 6 stroke:#ffd83d,stroke-width:2px
    linkStyle 7 stroke:#ffd83d,stroke-width:2px

🎛️ Modes — 5 ways to use the bridge

flowchart LR
    S([picasso]) --> LOOP[design-loop]
    S --> SOLO[design-solo]
    S --> CRIT[design-critique]
    S --> REF[design-reference]
    S --> SRC[from-site or from-figma]
    LOOP --> AP{APPROVED}
    AP -- "polish" --> ITER[design-iterate]
    AP -- "ship" --> DONE([Done])
    ITER --> DONE

    style S fill:#ff2d95,stroke:#ff4fa8,color:#fff
    style LOOP fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style SOLO fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style CRIT fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style REF fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style SRC fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style ITER fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style AP fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style DONE fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0

🆕 Design source flags (v0.2)

# Seed from live site (no Claude Design Pro needed for the design foundation)
/picasso --from-site https://stripe.com "pricing page for fintech"

# Use Figma as source
/picasso --from-figma --figma ABC123xyz "implement hero from Figma"

# Include designer browser annotations in the loop
/picasso --design-loop --feedback drawbridge "hero for B2B SaaS"

# Multi-page site with cross-page consistency
/picasso --design-loop --multi-page --scope mega "5-page marketing site"

📏 Scope presets — complexity-based auto-routing

/picasso --design-loop "hero cinematic for a B2B SaaS, dark elite"
/picasso --design-solo "sticky promo banner, warm palette"
/picasso --design-critique ./src/components/hero
/picasso --design-reference https://linear.app
/picasso --design-iterate "tighten motion choreography"
/picasso --scope complex "full marketing landing"

🏆 Gate scoring — mathematically verified fidelity

pie title Gate Score Weights
    "Colors - ΔE CIE2000" : 25
    "Typography" : 20
    "Layout and Spacing" : 20
    "Components" : 15
    "Motion" : 10
    "Responsive" : 10

🎯 Default gate: 9.0 / 10. Raise to 9.5 for critical landings (increases stagnation risk). Lower to 8.5 for fast prototypes.

🧠 Context backpressure — graceful degradation, never silent failure

The loop degrades gracefully as context fills. It never crashes silently — it checkpoints and exits PAUSED so you can resume in a fresh session.

flowchart LR
    N([NORMAL]) -- "60pct" --> W([WARN]) -- "75pct" --> D([DEGRADE]) -- "85pct" --> SW([SWITCH]) -- "95pct" --> P([PAUSED])

    style N fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style W fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style D fill:#2a1800,stroke:#ff9800,color:#ffb14a
    style SW fill:#2e0d0d,stroke:#f44336,color:#ff8a80
    style P fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0

🧬 Four Karpathy principles — baked into every round

Not guidelines. Mechanisms. Every one maps to a concrete component in the conductor. Inspired by Andrej Karpathy's public notes on LLM coding pitfalls — specifically his observations on silent assumptions, minimal code, surgical edits, and goal-declared targets.

flowchart LR
    K1[Think First] --> K2[Simplicity] --> K3[Surgical Edits] --> K4[Goal-Led State]

    style K1 fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style K2 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style K3 fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style K4 fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    linkStyle 0 stroke:#ffd83d,stroke-width:2px
    linkStyle 1 stroke:#ffd83d,stroke-width:2px
    linkStyle 2 stroke:#ffd83d,stroke-width:2px

🧩 Nine orchestration patterns

Every pattern exists to solve a specific failure mode in naive "loop and hope" approaches.

flowchart TD
    subgraph TOK["Token Efficiency"]
        direction LR
        P01[Structured] --> P04[Lazy reads] --> P05[Model route] --> P06[Adaptive] --> P07[Zero-ctx]
    end
    subgraph DED["Dedup and Cache"]
        direction LR
        P02[Hash cache] --> P03[Fingerprint] --> P08[Idempotent]
    end
    subgraph RES["Resilience"]
        direction LR
        P09[Backpressure]
    end

    style P01 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style P04 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style P05 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style P06 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style P07 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style P02 fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style P03 fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style P08 fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style P09 fill:#0d2e1a,stroke:#7cf0a0,color:#7cf0a0
    linkStyle 0 stroke:#ffd83d,stroke-width:1.5px
    linkStyle 1 stroke:#ffd83d,stroke-width:1.5px
    linkStyle 2 stroke:#ffd83d,stroke-width:1.5px
    linkStyle 3 stroke:#ffd83d,stroke-width:1.5px
    linkStyle 4 stroke:#ffd83d,stroke-width:1.5px
    linkStyle 5 stroke:#ffd83d,stroke-width:1.5px

🪝 Lifecycle hooks — full control over every event

Six hooks. Drop them in ~/.claude/hooks/. Edit a stub to activate. Delete to disable.

flowchart LR
    AD([autodetect]) --> PRE[pre-round] --> LOOP([round]) --> POST[post-round]
    LOOP -- plateau --> STAG[stagnation]
    LOOP -- pass --> APP[approved]
    LOOP -- fail --> FAIL[failed]

    style AD fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style PRE fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style LOOP fill:#ff2d95,stroke:#ff4fa8,color:#fff
    style POST fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style STAG fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style APP fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style FAIL fill:#2e0d0d,stroke:#f44336,color:#ff8a80

See docs/HOOKS.md for full reference.

📦 Install

One-liner (macOS / Linux / WSL / Git-Bash)

curl -fsSL https://cdn.jsdelivr.net/gh/RazvanGabrielNiculae/picasso-claude-design-claude-code-bridge-loop@main/scripts/install-oneliner.sh | bash

Wizard mode (prompts for gate, rounds, hook wiring):

... | bash -s -- --wizard

Manual clone

git clone https://github.com/RazvanGabrielNiculae/picasso-claude-design-claude-code-bridge-loop.git
cd picasso-claude-design-claude-code-bridge-loop
bash scripts/install.sh --wizard
bash scripts/verify.sh --smoke

Windows (PowerShell)

git clone https://github.com/RazvanGabrielNiculae/picasso-claude-design-claude-code-bridge-loop.git
cd picasso-claude-design-claude-code-bridge-loop
pwsh -File scripts\install.ps1
pwsh -File scripts\verify.ps1

The installer patches ~/.claude/settings.json automatically (timestamped backup). Use --no-hook to skip auto-wiring.

📁 Output structure

.pdl/
├── round-0/
│   ├── DESIGN.md        ← inferred tokens + ASSUMPTIONS block
│   └── prompt.md        ← Round-0 brief (~250 tok)
├── round-1/
│   ├── prompt.md        ← Round-N delta (~100 tok)
│   ├── design-output.png
│   ├── tokens.json
│   ├── impl-desktop.png
│   ├── impl-mobile.png  ← only if responsive < 8.0
│   ├── score.json
│   └── gaps.md
└── APPROVED.md          ← or FAILED.md

🚦 Exit codes

🖥️ No Pro+ account? Run the full loop locally with open-design

[nexu-io/open-design](https://github.com/nexu-io/open-design) (3.6k★ · MIT) is a local-first alternative to claude.ai/design. Run the complete PDL loop on your machine — no Pro+ account, no browser, no Chrome MCP required.

flowchart LR
    A{Pro+ account?} -- "yes" --> B[claude.ai/design]
    A -- "no" --> C{open-design\ndaemon running?}
    C -- "yes" --> D[open-design local]
    C -- "no" --> E[webdesign-mcp\nstandalone]
    B --> F([Full PDL loop])
    D --> F
    E --> G([Implement only\nno loop])

    style A fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style B fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style C fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style D fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style E fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style F fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style G fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0

/picasso auto-detects the active engine via GET /api/design-systems — no flag needed.

What open-design adds

Install open-design

# Clone once
git clone --depth 1 https://github.com/nexu-io/open-design.git ~/.claude/skill-library/open-design
cd ~/.claude/skill-library/open-design && npm install

# Start before each design session
npm run dev   # → http://localhost:3000

Then run /picasso --design-loop as usual — it probes :3000/api/design-systems automatically.

Use brand tokens as DESIGN.md seed

# 71 brand systems available instantly — no CSS extraction needed
/picasso --design-loop "hero for fintech, linear style"

# Explicit brand reference
/picasso --design-loop --ref linear "pricing page"

🔌 Companion tools

Picasso handles the loop. These tools extend it at the input, feedback, and scale layers.

See [docs/companion-tools.md](docs/companion-tools.md) for integration guides.

📋 Changelog

v0.3.0 — 2026-04 · Local-first engine + arsenal upgrade

• Adds: open-design local PDL engine — run the full loop without a Pro+ account. Auto-detected via GET /api/design-systems probe. No flag needed.
• Adds: 71 brand design systems (Stripe, Linear, Vercel, Apple, Tesla, Notion + 66 others) as DESIGN.md seed — replaces manual CSS extraction, saves 1–2 rounds to gate
• Adds: 5 visual directions (editorial, modern-minimal, tech-utility, brutalist, soft-warm) — structured style vocabulary for PDL prompts
• Adds: Auto Design-Extract from `--ref <url>` — color palette, typography, spacing, component patterns, motion hints auto-extracted into design-tokens-extracted.json
• Adds: DESIGN.md references — 68 real-world brand examples (awesome-design-md)
• Adds: Platform trade-offs table — Next.js vs Astro vs Remix vs Webflow vs Framer with budget brackets ($30K / $30-150K / $150K+)
• Adds: Arsenal tables — TIER 1/2/3 detailed with roles, star counts, notes
• Updates: Fallback matrix → "Fallback & recovery" — Pro+ absent now routes to open-design daemon before falling back to loop-less mode
• Docs: `docs/companion-tools.md` — open-design as first Input Layer entry with API reference

v0.2.0 — 2026-04 · Design sources + feedback

• Adds: --from-site (design-md-chrome pattern), --from-figma (Figma MCP source)
• Adds: --feedback drawbridge (browser annotation integration)
• Adds: --multi-page + SITE.md cross-page consistency (jezweb/design-loop pattern)
• Adds: visual scoring tiers (PASS / PASS WITH NOTES / ITERATE / FAIL)
• Adds: expanded fallback matrix for all new input modes
• Docs: docs/companion-tools.md integration guide

v0.1.0 — 2026-04 · First public release

• Unified public repo: v0.1 narrative + v0.2 operator additions
• Adds: context backpressure · 10 token-optimizations · Karpathy principles · 5 modes + 4 scope presets
• Adds: model routing · zero-context subagent · trajectory abort · idempotent writes
• Adds: 6 lifecycle hooks · wizard installer · economy.jsonl tracking
• Adds: reference mode · iterate mode · critique mode

v0.2 — operator-grade internals

• Conductor phases 1→4 · ASSUMPTIONS surfacing · DESIGN.md delta reads
• STAGNATED · EARLY_ABORT · PAUSED states · fingerprint deduplication
• Budget preflight · economy.jsonl · daily cap enforcement

v0.1 — initial bridge

• /picasso --design-loop command · pdl-conductor agent
• 6 round steps · gate scoring · pdl-autodetect hook
• One-liner installer (macOS / Linux / WSL / PowerShell)

📚 Docs

🗑️ Uninstall

bash scripts/uninstall.sh

Then remove the hook block from ~/.claude/settings.json manually.

<div align="center"> _{Not affiliated with Anthropic. "Claude", "Claude Code", and "Claude Design" are trademarks of Anthropic.<br/> This project only orchestrates user-owned sessions of those tools. · MIT License} </div>