This manual is for the person who has never written a line of Liquid but wants to ship a real Shopify store with Claude Code or Codex. We break down the full agentic dev workflow, the MCP ecosystem, and all the gotchas that Reddit and agency post-mortems learned the hard way. By the end you'll have a CLAUDE.md you can paste into any repo, a repeatable install script, and the safety rails that keep an agent from torching production.
Most people still think "AI on Shopify" means pasting a snippet into ChatGPT. Shopify quietly skipped four levels ahead between December 2025 and April 2026.
December 2025 — Winter '26 Edition. Shopify ships the official Dev MCP Server inside the platform. For the first time, coding agents get structured access to GraphQL Admin / Storefront schemas and Liquid docs. The release carries 150+ AI features — Shopify internally calls it "The Renaissance."
March 24, 2026 — Agentic Storefronts go live by default. Eligible US merchants — 5.6 million stores — instantly become discoverable inside ChatGPT, Microsoft Copilot, Google AI Mode, and the Gemini app. McKinsey projects $5 trillion in global agentic commerce volume by 2030. Morgan Stanley estimates 10–20% of US e-commerce will be AI-agent-driven that same year.
April 9, 2026 — Shopify AI Toolkit open-sourced (MIT). One install gives Claude Code, Codex, Cursor, Gemini CLI, and VS Code access to the Dev MCP plus 16 agent skills covering Admin GraphQL, Liquid validation, Hydrogen, and the full UI extensions stack.
What this means for you: you no longer have to remember GraphQL field names — the agent validates before writing. You no longer have to switch windows — the agent can edit themes, run mutations, and push to production from a single terminal. And as Shopify's VP of Engineering Farhan Thawar put it: "If you don't figure out how to harness the agents in 2026, you'll be behind."
"Claude Code or Codex?" is the wrong question. The real question is: which slice of the work are you handing off? You'll use all four pieces below — they're not substitutes, they're a division of labor.
Anthropic's terminal-native agent CLI. Reads whole repos, runs shell, performs git ops. Its 1M-token context holds an entire Dawn theme without chunking — ideal for Liquid refactors, Hydrogen builds, and large-scale rewrites.
OpenAI's counterpart. Reads AGENTS.md instead of CLAUDE.md, configured via TOML (~/.codex/config.toml). Ships with subagents, hooks, skills — and can run itself as an MCP server for other agents to call.
Runs locally, no auth needed. Provides doc search, real-time validation against GraphQL Admin/Storefront schemas, and Liquid template checks. Plug this into every coding agent. Non-negotiable.
Every Shopify store now exposes a /api/mcp endpoint. This is what ChatGPT, Claude.ai, and Perplexity's shopping agents call to search your products, build carts, and check out. You don't call it — you get called.
Since Shopify CLI 3.93.0, shopify store auth + shopify store execute let the agent read and write products, orders, metafields. --allow-mutations is off by default — opt in per command.
Open-source Admin MCPs maintained by the community (GeLi2001's is the most prominent). More direct than the official path, but no SLA — graduate to it once you know what guardrails you need.
Prerequisites: Node.js 18+, a terminal (Terminal / iTerm2 / Warp), and a Shopify Partner account. If you don't have one, register free at partners.shopify.com and spin up a development store. Never do your first practice run on a live store.
# 1. Install Claude Code globally $ npm install -g @anthropic-ai/claude-code # 2. Start it from any directory · OAuth opens in your browser $ claude ✓ Signed in as you@example.com (Max subscription) # 3. Install the Shopify AI Toolkit (the easy path) claude> /plugin marketplace add Shopify/shopify-ai-toolkit claude> /plugin install shopify-plugin@shopify-ai-toolkit ✓ 7 tools available · auto-update enabled # 4. Just want the Dev MCP without the full toolkit? $ claude mcp add --transport stdio shopify-dev-mcp \ -- npx -y @shopify/dev-mcp@latest # 5. Verify claude> /mcp ✓ shopify-dev-mcp · connected
# 1. Install Codex CLI $ npm install -g @openai/codex # 2. Authenticate (ChatGPT OAuth or API key) $ codex login # 3. Use the built-in plugins menu $ codex codex> /plugins # search "Shopify" → Add to Codex # 4. Or wire the MCP in manually $ cat >> ~/.codex/config.toml << 'EOF' [mcp_servers.shopify-dev] command = "npx" args = ["-y", "@shopify/dev-mcp@latest"] EOF $ codex mcp list shopify-dev · stdio · ready
# Shopify CLI 3.x · powers theme dev, app dev, store auth/execute $ npm install -g @shopify/cli@latest # Read-only auth · this is the safe starting point $ shopify store auth --store your-store.myshopify.com \ --scopes read_products,read_orders,read_customers,read_inventory # Run a read-only query to confirm everything is wired $ shopify store execute \ --store your-store.myshopify.com \ --query 'query { shop { name email currencyCode } }' { "shop": { "name": "Your Store", ... } } # Write ops require an explicit flag · never alias this away $ shopify store execute --allow-mutations \ --query 'mutation { productCreate(input: { title: "Test" }) { product { id } } }'
Do not connect to a live store on your first session. The first ten sessions — install, prompt practice, subagent design — should all run against a dev store. Agents interpret ambiguous instructions in ways you'll find surprising, and Shopify scopes grant access to entire resource categories, not individual records. write_products doesn't mean "edit these three products" — it means "edit any product in the store."
CLAUDE.md (read by Claude Code) and AGENTS.md (the cross-tool standard adopted by Codex, Cursor, Gemini CLI, and others) live in your project root.
Think of it as the agent's project briefing, house style, and rulebook. Skip it and you'll watch the agent invent nonexistent Liquid filters, write metafields from client-side JS, or commit settings_data.json and overwrite a live merchant's customizations.
# Project · {store-name} ## Stack - Shopify Online Store 2.0 theme (Dawn-based) - Shopify CLI 3.x · Node 20 - Theme check enforced · zero errors required ## Rules — non-negotiable 1. Never push to a live theme. Use development themes. 2. Never commit config/settings_data.json. 3. Before marking ANY task complete, run shopify theme check and confirm 0 errors. 4. Prefer {% render %} over {% include %}. 5. Themes only READ metafields — never write. 6. Always check existence: {% if product.metafields.custom.x != blank %} ## Conventions - Branch names: feature/, fix/, chore/ prefixes - One logical change per commit · imperative mood - Translation keys via locales/ · no hard-coded strings ## When in doubt - ASK clarifying questions BEFORE editing. - Validate every GraphQL query through shopify-dev-mcp first. - If a 16KB metafield value is truncated, FLAG it — don't silently cut. ## House style - Brand voice: warm, expert, no hype. - Currency: USD primary · EUR secondary.
A solid open-source starter exists — Karim Tarek's Shopify Theme CLAUDE.md covers the full frontend best-practice surface. Drop it in your project root and customize from there.
This is not an engineering Gantt chart. It's a conversation script for someone who's never built an e-commerce store before. Open the terminal each day and paste the brief.
Install Node, Claude Code or Codex, and Shopify CLI. Register a Partner account, spin up a development store. Drop a starter CLAUDE.md in the project root. Your first prompt should not be code — ask the agent to read the entire repo and write back its understanding of the project. Anything it misses, add to CLAUDE.md.
"Initialize a theme from Dawn via Shopify CLI. Walk me through the directory structure. Then do three things: (1) replace the logo and favicon placeholders; (2) set brand color CSS variables; (3) rewrite the hero section copy to match this brand voice {paste briefing}. Before each step, tell me which files you'll touch."
Prepare a CSV (columns: title, description, price, sku, vendor, tags, variant_options, image_urls). Brief: "Use Admin GraphQL productCreate to import this CSV into the dev store. Write SEO-optimized descriptions. Product titles must be natural-language (optimized for AI shopping agents) — no brand-collection names. After import, query back and report which records failed."
Define product.specifications (JSON metafield), product.care_instructions (rich text), product.materials (list). Ask the agent to create the definitions, populate them across the catalog, and surface them on the product page section. This step is what makes your products findable by AI shopping agents.
Every section is a Liquid file plus a schema block. "Refactor the hero into a reusable section that accepts image_picker, richtext, and url settings. Register it in templates/index.json so I can drag it in the theme editor. After the refactor, run shopify theme check and resolve every error and warning."
Most of this is admin UI configuration — the agent runs the checklist. "Use shopify store execute to verify the following are configured, and list any that aren't: payment gateway, shipping zones, tax registration, refund policy, privacy policy, cookie banner, abandoned cart email. For each missing item, tell me exactly where in the admin to set it."
Create a theme-performance-auditor subagent in .claude/agents/. Give it permission to run Lighthouse, read the output, propose specific Liquid changes, and re-run to verify improvement. Pair with shopify theme check --performance.
Edit robots.txt — confirm GPTBot, ClaudeBot, PerplexityBot are allowed. Submit your catalog to Shopify Catalog. Register sitemaps in Google Search Console and Bing Webmaster Tools. Every store automatically exposes /api/mcp — verify it responds correctly.
Preview with shopify theme push --unpublished. Wire GA4, GTM, and Klaviyo (the agent can script all three). Publish. Every week thereafter, run a 30-minute health check: low-stock SKUs, products missing alt text, unanswered reviews, abandoned-cart sequence trigger rate.
Three principles: (1) plan before execute; (2) give it a way to verify, not just a goal; (3) define a stopping condition. Four copy-paste templates below, one per workflow phase.
[ROLE] You are a senior Shopify theme engineer fluent in Online Store 2.0, Liquid, theme app extensions, and Shopify CLI 3.x. [CONTEXT] I run a dev store selling {specialty pour-over coffee gear} at {store.myshopify.com}. Expecting {40} SKUs, AOV {$45–$120}. Markets: {US + Canada}. Locales: {en primary, fr-CA secondary}. [TASK] Initialize a theme from Dawn and complete: 1. Set brand color tokens (CSS vars) to {#1A1A1A, #C77B3E, #F4F1EA} 2. Set typography (display: {Fraunces}, body: {Inter}) 3. Custom hero section supporting image / video / no-media modes 4. Custom product card: price, rating stars, metafields {custom.origin} and {custom.brewing_method} 5. Add en + fr-CA locale files · move every hard-coded string into translation keys [CONSTRAINTS] - Before editing any file, state which files you're about to touch and why - Validate every Liquid construct through shopify-dev-mcp first - Use {% render %} · forbidden: {% include %} - Before marking done: shopify theme check with 0 errors [STOP CONDITION] - All builds pass · theme check 0 errors · previewable on the dev store - Output a README describing every custom section's settings [BEGIN] Plan first, then execute. Wait for me to say "go" before touching files.
[ROLE] You are a Shopify product data engineer. [CONTEXT] CSV at {./data/products-2026Q3.csv}. Columns: {sku, title_en, title_fr, price, vendor, tags, weight_g, variant_color, image_urls}. {40} rows. [TASK] 1. Use shopify-dev-mcp to validate the current schema for productCreate / productVariantsBulkCreate 2. For each row, generate: - Natural-language product title (optimized for AI shopping agents — no collection-style names) - 80–120 word SEO description (1 primary keyword + 2 long-tail) - 4 metafields: custom.origin / custom.brewing_method / custom.material / custom.gift_ready (boolean) 3. Write everything via an Admin GraphQL bulk operation 4. Output failures to {./logs/failed-{timestamp}.json} [GUARDRAILS] - GraphQL rate cost cap is 1000/min · self-throttle - Read CLAUDE.md "brand voice" section before generating copy - On duplicate SKU: print a diff and ask skip vs update · never silently overwrite [VERIFICATION] - After completion, query back and confirm the count matches - Print 3 randomly-sampled products in full for me to review [BEGIN] Plan first · list every mutation you'll run and estimated cost. Wait for "go".
[GOAL] I want to build a "{coffee bean subscription}" feature, but I'm not sure whether to implement it with metafields, a theme app extension, a checkout extension, or a Shopify subscription app. [TASK] Use the AskUserQuestion tool to interview me. Dig into: - Technical implementation preferences (complexity I can tolerate) - UX / UI (what the shopper sees when subscribing) - Edge cases (swap, pause, skip a delivery) - Tradeoffs I haven't thought about Don't ask obvious questions · go after the hard parts. When the interview is done, write a complete spec to {./SPEC-subscription.md}. [ENDING] Once the spec is complete · DO NOT implement. Tell me: "Open a fresh session and use SPEC as input to execute."
[ROLE] You are a careful operator running Shopify Admin mutations. [TASK] For every product tagged {summer-2026}, identify variants priced ≥ $50 and reprice them to 85% of current price. [NON-NEGOTIABLE] 1. Dry-run first: list affected products and variants 2. Compute old_price → new_price for each · output as CSV for me to review 3. Wait for me to type "EXECUTE" before running the actual mutation 4. Use productVariantsBulkUpdate (not per-variant) · batch the calls 5. After the run, report: success count · failure count · failure reasons 6. For failures, generate rollback commands (list with original prices) 7. Run with --allow-mutations · ask me to manually disable it after [STOP IF] - Dry-run shows affected variants > {500} - Any computed new_price falls below {$5} (likely a data bug)
What follows isn't in the Shopify docs. It comes from r/ClaudeAI, r/Shopify, r/ChatGPTCoding, and the post-mortems published by agencies like Talk Shop, Charle, Flagship, and Claudefast.
write_products, the agent can touch every product in the store. Talk Shop's stat: ~1 in 10 sessions has the agent misread the scope of your instructions.--dangerously-bypass-approvals-and-sandbox (yolo mode) on a production store.git reset --hard is your only way out. Make a habit of git commit -m "before the agent run" before each session./init command scans the whole project and drafts a CLAUDE.md. Even if you already have one, re-running before a big refactor surfaces context you missed.Control + V (not Cmd + V) to paste an image. "Analyze this UI and suggest improvements" beats any text description ten to one./clear, dump the current state to status.md, start fresh.list.product_reference and list.single_line_text_field.Each subagent is a Markdown file in .claude/agents/{name}.md with a YAML frontmatter block declaring scope, tools, personality. Commit them to the repo so the whole team benefits.
codex mcp serve lets Claude Code call Codex. When you need cross-validation on a tricky change, having two different model families peer-review the same diff cuts error rates dramatically.features.multi_agent = true to unlock spawn_agent, send_input, resume_agent. It's on by default in stable, but verify before relying on it.project_root_markers = [".git", "pnpm-workspace.yaml"] so Codex knows where to read AGENTS.md from.PreToolUse to intercept dangerous bash commands · PostToolUse to auto-run theme check. Anthropic's best-practices docs have full examples.Pushing settings_data.json to git. This file holds merchant customizations made in the theme editor (colors, images, copy). Push it once and you overwrite production content. Always .gitignore it unless you've deliberately designed a sync strategy.
Letting the agent push directly to the live theme. Always use shopify theme push --unpublished to land changes on a preview theme, then publish from admin after a visual check. Make this rule #1 in your CLAUDE.md.
Writing metafields from client-side JS. Themes can only read metafields. Agents occasionally try to fetch the Admin API from JS to write them — that leaks your admin token and violates Shopify policy. Always write via the Admin API server-side.
Building metafield keys dynamically. It looks clever: product.metafields["custom"][key]. Liquid doesn't permit runtime key construction — it silently fails. Always use dot notation: product.metafields.custom.tagline.
Hitting GraphQL rate limits. Standard plan caps Admin API at 1000 cost points / minute. The agent will happily fire 200+ mutations in parallel and get throttled. Add to CLAUDE.md: "Batch mutations must throttle, batch, and retry on 429."
Prompting a general-purpose LLM for Liquid. Liquid is underrepresented in public training data, so models without Dev MCP frequently invent filters that don't exist (product.featured_variant is a classic hallucination). Always attach shopify-dev-mcp so the agent validates against the live schema before writing.
Aliasing --allow-mutations on by default. The flag is a safety net specifically for agentic workflows. Aliasing it to always-on removes the guardrail. Enable per session when you intend writes, disable after.
Operating production without an audit log. The Shopify AI Toolkit doesn't log operations at the toolkit level. When something breaks, retracing what the agent did is painful. Wrap your own layer: write every mutation to ./logs/{date}/ops.jsonl so you can answer "what, when, by whom."
Once you're live, three natural directions to push — depending on whether you're chasing scale, differentiation, or productization.
When a Liquid theme can't hold the interactive depth you want, switch to Hydrogen (Shopify's Remix-based framework) on Oxygen. Claude Code's Hydrogen subagent writes routes, queries, and components directly. And from 2026.1.4, Storefront MCP is built into Hydrogen — your headless storefront automatically becomes an agent endpoint.
For dynamic pricing, custom discount logic, or checkout customization, go custom app + Shopify Functions (Wasm). Claude Code uses shopify app create to scaffold, writes Polaris React UI, runs Prisma migrations — all from the terminal. TinyTwo's ReviewMate case (a full review app built end-to-end with Claude Code) is the best public reference.
Running 5+ stores? Plug Composio's Tool Router or a community admin MCP into Claude Code. One natural-language command orchestrates across stores: "Set inventory to zero and unpublish every product tagged holiday-2026 across all stores."
"You don't need to learn Liquid first.
You need to learn how to hand the right question to the right agent."