Stitch Design

Design, verify, art-direct, and deliver editable Google Stitch projects from your supported coding agent through 46 workflow-oriented Agent Skills and an evidence-driven Harness.

English | 简体中文 · Install · Quick start · Examples · Architecture · Troubleshooting

Codex host example

The screenshot above is from the v0.8.x plugin page and predates the v1.3.0 skill rename; the current inventory is 46 skills, and the names shown in it have since moved to the stitch-ui-* families.

In Codex, the installed plugin exposes three ready-to-run prompts, one bundled Stitch MCP server, 46 workflow Skills, and a secure local Token setup. ZCode and Kimi load the same public plugin identity through their host manifests.

Positioning

stitch-design turns product ideas and existing interfaces into editable Google Stitch screens, then carries those artifacts into production frontend workflows. It combines live Stitch generation and editing, design-system operations, code-to-design, local asset import/export, framework conversion, and an evidence-driven Delivery Harness.

46 workflow Skills	17 MCP tools	15+ frontend targets	3 verified viewports
Design, safety, conversion, delivery	15 Google Stitch + 2 local asset tools	React, Vue, mobile and more	Desktop, tablet, mobile

Installation

Prerequisites

• Python 3.11 or newer on PATH.
• A Google Stitch API key from https://stitch.withgoogle.com/settings.
• Optional, for the Harness comparison workflow: Pillow from requirements-harness.txt.

From the plugin marketplace

Recommended: track the repository's main branch explicitly.

codex plugin marketplace add full-stack-plugins/stitch-design-plugin --ref v0.9.0
codex plugin add stitch-design@partme-ai-stitch

Restart Codex or the ChatGPT desktop app, open a new task, and ask Stitch Design to list your projects.

Other supported Marketplace sources

GitHub shorthand pinned by the repository-local marketplace to v0.9.0:

codex plugin marketplace add full-stack-plugins/stitch-design-plugin
codex plugin add stitch-design@partme-ai-stitch

Full Git URL pinned to immutable v0.9.0:

codex plugin marketplace add https://github.com/full-stack-plugins/stitch-design-plugin.git --ref v0.9.0
codex plugin add stitch-design@partme-ai-stitch

Sparse Git checkout when only Marketplace metadata is needed:

codex plugin marketplace add https://github.com/full-stack-plugins/stitch-design-plugin.git \
  --ref v0.9.0 \
  --sparse .agents/plugins
codex plugin add stitch-design@partme-ai-stitch

Local checkout for development:

git clone https://github.com/full-stack-plugins/stitch-design-plugin.git
codex plugin marketplace add ./partme-stitch-plugin
codex plugin add stitch-design@partme-ai-stitch

Confirm or refresh the installation:

codex plugin marketplace list
codex plugin list
codex plugin marketplace upgrade partme-ai-stitch

The Marketplace name is partme-ai-stitch; the install selector is stitch-design@partme-ai-stitch.

China mirror (AtomGit)

If GitHub is slow or unreachable, install from the AtomGit mirror instead. The commands are identical apart from the marketplace URL — add the mirror first, then run the same codex plugin add stitch-design@partme-ai-stitch shown above:

codex plugin marketplace add https://atomgit.com/partme-ai/partme-stitch-plugin.git --ref main
codex plugin add stitch-design@partme-ai-stitch

To install the whole partme-ai plugin catalog from the mirror in one step, add the marketplace repository instead:

codex plugin marketplace add https://atomgit.com/partme-ai/plugins.git
codex plugin add stitch-design@partme-ai

Notes:

• The AtomGit source and the GitHub source share marketplace names, so adding one replaces the other. Switch back with codex plugin marketplace add https://github.com/partme-ai/plugins.git.
• For ZCode or Kimi, clone the mirror repository and register the local directory in the respective marketplace configuration.

Quick start

First run: one local Token screen

The plugin already bundles its MCP connection. The first Stitch request checks credentials and opens the local Token screen only when STITCH_API_KEY is missing.

flowchart LR
    A[Install plugin] --> B[Restart and open a new task]
    B --> C{Token available?}
    C -->|No| D[Open local Token screen]
    D --> E[Create key in Stitch Settings]
    E --> F[Save to restricted user config]
    C -->|Yes| G[Read-only project check]
    F --> G
    G --> H[Generate · edit · export]

Loading

On the first MCP request without a credential, or after a refreshed credential is still rejected with HTTP 401, the plugin automatically opens this local Token screen. A 10-minute cooldown prevents repeated windows while setup is in progress.

1. Create your key in Stitch Settings.
2. Paste it into the masked local field. Never paste it into chat.
3. Return to Codex; start with a read-only request such as “List my Stitch projects.”

Manual fallback if the browser does not open:

# macOS / Linux
python /path/to/installed/plugin/scripts/stitch_setup.py ui

# Windows
python C:\path\to\installed\plugin\scripts\stitch_setup.py ui

The setup page listens only on 127.0.0.1, loads bundled assets, validates Origin and CSRF, never logs the key, and clears the field after every response. The cooldown marker stores only a launch timestamp. The python command on PATH must resolve to Python 3.11 or newer.

What you can build

Workflow	Built-in path	Verifiable output
Create and iterate	Generate, inspect, edit, variants	Bound project and screen identities
Govern visual systems	Create, update, list, apply design systems	Design-system identity and version evidence
Bring existing UI into Stitch	Upload reviewed HTML/images	Same-project screen resources
Export for production	Download HTML, screenshots and referenced assets	Atomic files and SHA-256 manifest
Generate frontend code	React, React Native, shadcn/ui, Vue, Vant, Element Plus, Bootstrap, Layui, uView	Editable component source
Deliver with gates	Stitch → explicit art decision → optional ImageGen loop or Stitch-only validation → approval	Receipt chain and explicit human decisions

The plugin does not host Stitch or bundle a shared key. Ambiguous writes are reconciled with read operations before any retry.

Slash commands

Every command is a thin entry point that routes to the narrowest skill for the job. Start with /stitch when you are not sure which one applies.

Command	What it does
/stitch	Total entry point; routes by capability
/stitch-ui-execute	Create, import, edit or variant a Stitch screen
/stitch-design-spec	Turn a PRD or feature into per-page specs and prompts
/stitch-ui-style	A DESIGN.md proposal with a distinct visual direction
/stitch-site-md	Site identity, navigation and page priorities
/stitch-ui-loop	Relay iteration from SITE.md / DESIGN.md / next-prompt.md
/stitch-design-harness	Carry one screen to a verified high-fidelity delivery
/stitch-remotion	Compose screens into a Remotion walkthrough video
/stitch-design-md	Export or extract a structured DESIGN.md
/stitch-extract-static-html	Static HTML with inlined assets
/stitch-code-to-design	Import an existing frontend into Stitch
/stitch-manage-design-system	Tokens, components, consistency
/stitch-upload	Upload approved local assets to a project
/stitch-local-setup	One-time local MCP proxy, credentials and self-check

Framework specialists (stitch-ui-contract-*, stitch-ui-*-components), the MCP primitives and the compatibility aliases are reached through /stitch or the skill that needs them, rather than as separate commands.

Package self-check against OpenAI guidance

Official requirement	Current repository	Result
Stable plugin identity and metadata	.codex-plugin/plugin.json, stitch-design, publisher and URLs	Pass
Skills at the plugin root	skills/ with 46 validated Skills	Pass
Bundled MCP configuration	.mcp.json compatibility mapping to the local stdio proxy	Pass for Codex compatibility
Visual install metadata	Logo, composer icon, default prompts and README screenshot	Pass
Marketplace policy metadata	Installation, ON_USE authentication and Creativity category	Pass
Portable Agent Plugins root manifest	Root plugin.json and portable mcp.json	Not yet migrated
Universal public Plugins Directory	Requires separate OpenAI submission and remote HTTPS MCP review	Not published

This repository intentionally remains a Codex compatibility package while the portable/public migration gate is open. See Portable migration gate.

Status and version

Property	Value
Plugin ID	stitch-design
Current candidate	0.9.0
Current release	v0.9.0
Previous release	v0.8.6
Marketplace	partme-ai-stitch
Authentication	User-owned STITCH_API_KEY, requested on first use
License	Apache-2.0

Example requests

Read-only: List my Stitch projects and do not create anything.
Generate: Create a responsive product screen in Stitch.
Edit: Preserve the design system and only update the current screen.
Convert: Turn this Stitch screen into production React components.

Remote writes require the target project and intended scope. If a write times out, do not immediately repeat it; inspect the project/screen state first.

MCP tools

The bundled stdio proxy exposes 17 tools: 15 from the Google Stitch MCP server and 2 local asset tools added by this plugin.

Google Stitch tools (15)

Tool	Purpose
create_project	Create a Stitch project
list_projects	List accessible projects
get_project	Read one project
delete_project	Delete a project
generate_screen_from_text	Generate a screen from a text prompt
list_screens	List screens in a project
get_screen	Read one screen
edit_screens	Edit an existing screen
generate_variants	Generate design variants
create_design_system	Create a design system
create_design_system_from_design_md	Create a design system from a design document
update_design_system	Update a design system
list_design_systems	List design systems
apply_design_system	Apply a design system to a screen
upload_design_md	Upload a design document

Local tools added here (2)

Tool	Purpose
stitch_local_upload_asset	Upload a reviewed local image or HTML file into the current project
stitch_local_download_assets	Download screen HTML, screenshots, and referenced assets with an atomic write and SHA-256 manifest; referencedAssetPolicy defaults to best_effort and may be set to strict

Error contract

Signal	Meaning	Next action
ProxyError	Sanitized proxy failure	Read the message; no automatic retry
UnknownWriteResult	A write may have reached Stitch without a definitive response	Reconcile with read tools before retrying
ApprovalRequired	A gate needs an explicit human decision	Approve or reject in the Harness
InvalidTransition	A state change bypassed an approved gate	Re-run from the previous state
ContractError	A page specification is unsafe or incomplete	Fix the specification
SecretStoreError	The credential could not be read or written safely	Re-run the local setup

Failures are returned as JSON-RPC errors with code -32000 for a sanitized proxy failure and -32001 for an unknown write result.

Configuration

.mcp.json starts the bundled proxy from the installed plugin root:

{
  "type": "stdio",
  "command": "python",
  "args": ["scripts/stitch_mcp_proxy.py"],
  "cwd": "."
}

Credential precedence:

1. STITCH_API_KEY in the current process.
2. The current-user Stitch Design credential file.
3. First-use setup.

Default locations are $XDG_CONFIG_HOME/stitch-design/credentials.json (or ~/.config/...) on Unix and %APPDATA%\stitch-design\credentials.json on Windows.

Run a secret-free check:

python scripts/stitch_setup.py check

Architecture and security

Codex owns plugin loading and approvals. Google Stitch owns remote design data and tool execution. Stitch Design owns workflow instructions, package validation, local credential bootstrap, and error recovery. The authors do not receive MCP traffic.

• Architecture
• Technical solution
• Portable migration gate
• Privacy
• Terms

Component responsibilities

Component	Owns	Does not own
scripts/stitch_mcp_proxy.py	The stdio entry point that starts the proxy	Credential storage
stitch_harness/mcp_proxy.py	HTTP session handling, tool-list repair, and the write-result rules	Business approval
stitch_harness/secrets.py	Credential lookup order and the restricted user config	Remote calls
stitch_harness/assets.py	The two local asset tools	Upstream Stitch behaviour
stitch_harness/orchestrator.py	The evidence-driven Harness state machine	Remote execution
stitch_harness/storage.py	Atomic run files and receipt chaining	Rendering
scripts/stitch_setup.py	The loopback Token screen and the status check	Design work
skills/ (46)	Routing, design, conversion, and delivery instructions	Runtime enforcement

Development and verification

python -m pip install -r requirements-test.txt
python -m unittest discover -s tests -v
python scripts/validate_distribution.py .
python scripts/validate_skills.py skills
python scripts/validate_markdown_links.py .
python scripts/scan_secrets.py .
find scripts skills -type f -name '*.sh' -exec shellcheck {} +
python -m compileall -q scripts stitch_harness skills
git diff --check

Version 0.7.8 keeps Stitch's primary HTML, screenshot, and DESIGN.md downloads on the Google/Stitch allowlist, while HTML-referenced dependencies may come from any safe public HTTPS host such as cdn.tailwindcss.com. Referenced dependencies now default to best_effort: a safe dependency that is temporarily unavailable or has an unsupported response is skipped with a host-only warning while primary artifacts are still published. Set referencedAssetPolicy: "strict" to retain all-or-nothing export. Unsafe URLs, HTTP, credential-bearing URLs, localhost, local/internal names, IP literals, redirects, primary-artifact failures, path escapes, byte/file limits, and the independent 500-URL reference discovery budget remain blocked.

Unknown-write reconciliation may bind target.project_id and target.expected_title. When a complete list_screens read succeeds, its evidence binds the project ID, completeness flag and normalized title-hash inventory. Only when the Harness derives that the expected-title hash is absent may get_screen be recorded as skipped with reason no_candidate_id; an applied or discovered candidate still requires a successful get_screen. Attempt limits, timestamps, hashes, and duplicate-write protection remain enforced.

Repository preparation for the provider + asset live smoke is complete: the manual-only workflow uses the STITCH_API_KEY repository secret, private runner state, sanitized output, and a final always() cleanup with read-back absence proof. It has not been run remotely and is not Harness acceptance. The full Harness remains an interactive local controller path. See the live-smoke acceptance register, which records the v0.7.1 provider + asset smoke and release gates.

Data and state

Data	Location	Lifecycle	Secrets
Credential	$XDG_CONFIG_HOME/stitch-design/credentials.json, or %APPDATA%\stitch-design\credentials.json on Windows	Until you rotate or delete it	Yes: the STITCH_API_KEY value
Harness run files	.stitch/ inside your project	Until you archive or delete them	No
Receipt chain	Alongside each run	Tamper-evident; grows with each accepted gate	No
Downloaded assets	Your chosen output directory	Until you delete them	No

Run state machine: DRAFT, PREFLIGHT_PASSED, STITCH_GENERATED, SOURCE_ACCEPTED, AWAITING_ART_DECISION, ART_ENHANCEMENT_APPROVED, STITCH_ONLY_SELECTED, ART_GENERATED, ART_ACCEPTED, SEMANTIC_NORMALIZED, ROUNDTRIPPED, EDITABILITY_VERIFIED, COMPARISON_ACCEPTED, AWAITING_USER_APPROVAL, APPROVED, ARCHIVED, CANCELLED, RECONCILING, BLOCKED.

Accepting a Stitch source never authorizes ImageGen. The Harness pauses and asks the user to reply with exactly enhance, keep_stitch, or cancel; only the exact enhance response can enter the ImageGen path. Ambiguous confirmations are not mapped, and the CLI exposes no self-asserted --source user override.

Specs may select strict provider_generated provenance or imported_editable_html. Imported HTML still requires an exact-canvas render artifact and full DOM/copy gates. Reported OCR drift fails closed, and enhanced delivery records a deterministic semantic-normalization receipt before Stitch upload/readback.

Visual comparison uses coarse, canvas-relative edge geometry for layout scoring, while illustration texture, shadows, color, and component finish remain in the separate five-dimension quality review.

Troubleshooting

Symptom	Action
Stitch tools are missing	Confirm plugin status, restart Codex, open a new task
Credentials are missing	Open stitch_setup.py ui
Authentication fails	Replace the key, restart, run read-only list_projects
A write times out	Read project/screen state; do not blindly resubmit
ChatGPT web stalls	Treat the path as experimental; use local Codex

Upgrade

codex plugin marketplace upgrade partme-ai-stitch
codex plugin add stitch-design@partme-ai-stitch

Contributing and support

Open functional issues at https://github.com/full-stack-plugins/stitch-design-plugin/issues. Before proposing a change, state the Stitch API surface you verified against, whether it alters the tool catalogue or the write-result rules, and include the affected validators.

Source and license

All 44 Skill bodies are vendored verbatim from full-stack-skills/stitch-skills, the single source of truth, and pinned by skills.lock.json (source repo, ref, commit, and per-skill digests). Refresh them with python3 scripts/vendor/skill_vendor.py update; never edit skills/ directly. Official adapted material traces to google-labs-code/stitch-skills commit 0337446dadde6f8c94210444e2aa9d546126480f.

See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.