stitch-local-setup

Stitch Design local first-time setup

Quick start

Typical triggers:

"First time using Stitch Design."
"Stitch says STITCH_API_KEY is missing."
"Help me configure the Stitch key, but do not write it into the shell profile."

For local Codex users on Windows, macOS, and Linux. The plugin has a built-in local stdio MCP proxy; this Skill only handles missing user credentials and restricted user-level configuration.

The python in PATH on all supported hosts must resolve to Python 3.11 or later; the plugin MCP and this setup flow use the same command.

Capability boundaries

✅ Good at handling

Check whether STITCH_API_KEY is already set in the current process or user configuration, without outputting its value.
Guide the user to enter their own Stitch API key via hidden input and save it to a cross-platform restricted configuration file for the current user.
Start the Codex CLI with the saved credentials, or inject environment variables into a user-specified local command.

⚠️ Requires the user to complete

Log in to Stitch Settings to create or rotate their own key.
Enter the key only in the local configurator's hidden prompt.
Restart Codex so the new process picks up STITCH_API_KEY。

❌ Inapplicable scenarios and handoff

ChatGPT web plugin authorization: should be handled by the official connector/OAuth, and users should not be asked to paste a key.
A team sharing one author key: each user should use independent credentials, or build a tenant-isolated authentication gateway.
Writing the Key into Codex configuration, shell profile, project files, or files without restricted permissions.

First-time use workflow

First use the configurator to perform a read-only check; it verifies both whether the credentials are readable and whether the plugin root .mcp.json exists, outputting only status lines and not printing the key or paths:
```
python /absolute/plugin/root/scripts/stitch_setup.py check
```
After the check passes, continue the original Stitch task.
If the check fails, pause remote calls and distinguish the two branches based on the last output line; do not conflate them:
- STITCH_API_KEY is not configured: Credentials missing. The MCP proxy will automatically open the local Token page; tell the user to create a key from Stitch Settings, and do not let the user paste the key into chat. The proxy also opens the same page when it still receives a 401 after one refresh, for replacing an invalid Key.
- Stitch MCP configuration is missing: Credentials are readable but the plugin root is missing .mcp.json, which means the installation is incomplete. In this case, creating a new key is ineffective; repair or reinstall the plugin and rerun check。
Normally, wait for the local page to open automatically. The proxy uses a 10-minute cooldown marker to avoid repeated pop-ups for the same missing credentials; the marker only records the startup time and does not contain the key. Only when the browser is blocked by system policy or the page does not appear should you locate the plugin root directory from the current SKILL.md by going up two levels and open it manually:
- Windows：
```
python C:\absolute\plugin\root\scripts\stitch_setup.py ui
```
- macOS / Linux：
```
python /absolute/plugin/root/scripts/stitch_setup.py ui
```
The user pastes and saves the Token in a single card; the acquisition link, three instructions, and advanced commands remain lightweight, and the separate three-step wizard is no longer displayed.
Credentials come only from the current process or a restricted user configuration file; there is no other storage migration entry point.
After setting, return to the conversation and re-initiate the original request. If the current host has not re-established the MCP process, use the configurator to start Codex:
```
python /absolute/plugin/root/scripts/stitch_setup.py cli
```
Windows uses the same python ... cli command. For a custom start command, use run -- <command>。
For a new task, first make a read-only call to list_projects. Either a project list or an explicit empty list counts as successful authentication; if unknown or timed out, do not perform write operations.

Security and degradation

Do not search for keys in browsers, other client configurations, shell profiles, history, or logs.
Do not execute echo "$STITCH_API_KEY"、printenv STITCH_API_KEY or a full env。
Keys do not enter the plugin directory, Git, or Codex configuration; user configuration directories and files use 0700/0600on Unix, and Windows inherits the current user Profile ACL. The configurator does not modify .zshrc, PowerShell Profile, or system environment.
PATH python is missing or lower than 3.11, first block plugin calls and provide repair instructions; session-level environment variables cannot fix interpreter prerequisites.

FAQ

Q1: Where do I get the key? Create it in Stitch Settings .

Q2: Why is a key still needed after installation? Installation has completed the MCP configuration; the key is used for Stitch user authentication.

Q3: Will shell configuration be modified? No. The configurator uses a separate user credential file.

Q3.1: Why didn't the page open automatically? Automatic opening is triggered by the local MCP proxy when credentials are first missing, and has a 10-minute anti-repeat cooldown. If browser policy blocks opening, use the above ui command; there is no need to send the key to the chat.

Q4: Where is it saved? Unix uses $XDG_CONFIG_HOME/stitch-design/credentials.json or ~/.config/..., Windows uses %APPDATA%\stitch-design\credentials.json. To remove it, first revoke the key in Stitch Settings, then delete the credential file; after deletion, do not continue using the old key.

Q5: How do I verify? Run stitch_setup.py check, and after restart make a read-only call to list_projects。

Q6: Can I send the key to the agent? No, only enter it in the local hidden prompt.

Reference as needed

For status and platform branches, see Workflow。
For insecure solutions, see Anti-patterns。
For storage, rotation, and connector boundaries, see In-depth FAQ。
For behavior verification, see Local verification example。

When to use

Load this skill when the user needs to configure or diagnose local authentication and runtime prerequisites . First extract the goal, input, constraints, delivery format, and acceptance criteria from the request; the description summary is: When using Stitch Design locally for the first time, when STITCH_API_KEY is missing, or when authentication fails, guide Windows, macOS, and Linux users to obtain a key from Stitch Settings and complete one-time setup through the plugin configurator; web ChatGPT connections do not use this process..

Rules

Read before write: first confirm the current state and real capabilities, then perform actions that change external state.
Least privilege: use only the files, tools, accounts, and network scope required to complete the current step.
Evidence first: when run results, resource IDs, versions, hashes, or test output are missing, explicitly mark them as NOT_VERIFIED。
Idempotency first: retain request identifiers and stage status; when results are unclear, query first and do not blindly retry.
Privacy and security: logs, examples, receipts, and error messages must not contain tokens, cookies, keys, or personally sensitive data.

Workflow

Step 1: Clarify intent

Confirm whether this skill matches the goal; if it is only an adjacent need, hand it off to a more precise skill.

Step 2: Perform preflight checks

Check local tools, configuration locations, permissions, and current authentication status; when any key condition is unknown, stop at the read-only stage.

Step 3: Form a plan

List the tools to be called, the objects that will change, the success criteria, and the safe exit path after failure.

Step 4: Execute actions

Complete the minimal configuration through supported interaction entry points, and immediately clean up sensitive input; keep a correlatable status or receipt for every external call.

Step 5: Verify delivery

Report only availability, identity scope, and redacted errors, do not output credential contents, and state facts, inferences, and unverified items separately.

Validation checklist

The skill trigger conditions are consistent with user intent, and no adjacent task was misrouted to this skill.
Inputs, target objects, versions, and output locations are all clear, and no guessed values were used in place of required values.
All write, paid, publish, or irreversible actions are within the scope of user authorization.
The result has been verified with independent checks; "command succeeded" or "file exists" alone does not count as complete acceptance.
The output includes actual evidence, failed/skipped items, remaining risks, and executable next steps.

Gotchas

Mistaking the plan for the result: a document or prompt is not the same as actual execution; the actual execution level must be stated.
Retrying on error: a timeout or lost response may already have produced remote state; query first before deciding whether to retry.
Implicitly expanding scope: batch, full-scale, publish, overwrite, and paid operations are not a natural extension of ordinary reads and writes.
Version drift: when referencing external resources, record the version, tag, or commit; do not treat a mutable branch as release evidence.
Stale evidence: caches, old screenshots, and historical tests cannot prove the current environment; refresh key evidence before delivery.

Non-applicability and boundaries

Do not echo, log, or commit keys; do not create accounts, purchase credits, or accept terms on behalf of the user. If a request requires another skill, do not copy its body text; hand off by skill name while preserving the current task context.

Progressive disclosure

When you need to determine inputs/outputs, state, and authorization points, read references/workflow-contract.md。
When you need a pre-delivery self-check, read references/validation-checklist.md。
When encountering timeouts, partial success, or recovery scenarios, read references/error-recovery.md。
For first runs, refusal of overreach, and failure recovery, refer respectively to examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。