Using Codex for Shopify Development

Shopify supports Codex officially. It reads the standard instruction file format, and with the right toolkit connected it validates its own output against real API schemas instead of guessing from training data.

It also invents Liquid filters that don’t exist, and it can execute bulk changes against a live store faster than you can read what it printed.

This guide covers setup, the configuration that makes its output correct, and how to contain what it can break.

1. What Codex gives you

It reads AGENTS.md natively. That’s the vendor-neutral instruction file most coding agents read, so your project rules stay portable rather than tied to one tool.

Shopify ships an official toolkit for it. The Shopify AI Toolkit provides a Codex plugin with around sixteen agent skills covering Admin GraphQL, Liquid themes, Hydrogen, Functions, Polaris extensions and store execution. It adds three capabilities:

• Documentation search against current shopify.dev rather than model memory
• Code validation — GraphQL queries, mutations, Liquid templates and extension code checked against bundled Shopify schemas before use
• Store operations — Admin GraphQL executed against a real store through Shopify CLI

Everything below assumes the toolkit is installed. Without it, Codex is a general-purpose coding agent that has read some Shopify documentation at some point.

2. Setup

Prerequisites: Codex CLI, Node 18+, Shopify CLI, and a store to connect to for store operations.

Install the plugin

In Codex CLI, run /plugins, search for Shopify, then select Add to Codex. This installs the plugin with all available agent skills.

Or install skills manually

npx skills add Shopify/shopify-ai-toolkit
npx skills add Shopify/shopify-ai-toolkit --skill shopify-admin

Manually installed skills don’t auto-update. The bundled schemas drift from the live platform, so re-install periodically or you’re validating against an older API version.

MCP config is TOML, not JSON

Codex CLI uses TOML for its general configuration, so MCP server config follows that convention. Most Shopify MCP examples online are written in JSON for Cursor or Gemini CLI and need translating. This is a common setup failure.

Opt out of telemetry before your first validation

Both validate.mjs and search_docs.mjs send usage payloads to Shopify by default. The skill files describe this as anonymised pass/fail results, but the validation payload includes the code being validated — your GraphQL, your Liquid, your client’s logic.

export OPT_OUT_INSTRUMENTATION=true

Set this before launching Codex on client or commercial work.

Verify it’s working

Ask Codex something Shopify-specific and version-sensitive:

What’s the correct GraphQL mutation to update a product’s title in the Shopify Admin API?

If the toolkit is connected, it will search current documentation and validate its answer. If it answers immediately from memory, it isn’t.

3. AGENTS.md

Write it by hand.

A 2026 study by Gloaguen et al. measured the effect of agent instruction files across 138 real-world repositories. Files written by the developers who worked on the codebase improved agent task success by around 4% and reduced agent-generated bugs by 35–55%. Instruction files generated by an LLM did the opposite: lower success rates, and inference cost up by over 20%.

The reading is that the value sits in the project-specific decisions a model can’t infer from the code — which conventions you’ve settled on, what a client has ruled out, which approach failed last time.

Keep it under about 150 lines. Beyond that the agent starts skimming.

Use AGENTS.md rather than a tool-specific file. If people on the team use different agents, per-tool instruction files drift apart and whoever is on the tool with the stale file works with degraded context.

Starting template

Adapt this rather than copying it. The project-specific decisions are what make it work.

# Storefront engineering instructions

## Scope
Applies to every Shopify theme, storefront, landing page and customer-facing
interface in this repository.

## Authority
1. The latest explicit request
2. Approved briefs and wireframes
3. The established project design system
4. Theme defaults

Wireframes are authoritative for information architecture, order, priority and
functionality, not for visual styling unless that has been approved.

Never invent prices, stock status, delivery times, reviews, guarantees,
certifications, opening hours or legal claims. If a fact isn't verifiable in the
repo or the brief, flag it rather than filling it in.

Prefer disagreeing with a request over implementing something that creates a
worse customer or maintenance outcome. State the tradeoff briefly.

## Required workflow
1. Inspect the existing implementation, target template, rendered document
   outline, design tokens, reusable components and mobile behaviour before
   editing.
2. Confirm the exact target theme, branch and environment. Work on a
   development or unpublished theme unless production is explicitly authorised.
3. Identify the page's primary audience, primary task, primary CTA and next
   destination.
4. Reuse or extend existing components and tokens. Do not create page-specific
   copies of shared patterns without a documented reason.
5. Build mobile-first (360-390px), then verify tablet, laptop and wide desktop.
6. Validate syntax, schemas, accessibility, responsive layout and critical
   flows.
7. Report what changed, what was verified, what was skipped and why, and any
   remaining blocker.

## Shopify conventions
- Prefer Online Store 2.0 JSON templates composed from reusable sections and
  blocks.
- Keep merchant content in theme settings, navigation, metafields, metaobjects,
  collections or products, not hardcoded in Liquid.
- Keep section schemas focused. Expose meaningful choices, not arbitrary pixel
  controls that let a merchant break the design system.
- Snippets for reusable markup, sections for merchant-arrangeable modules,
  blocks for repeatable items, locales for all interface strings.
- Use LiquidDoc in snippets and blocks. Do not use it in sections; it isn't
  supported there, and sections are documented via schema.
- Use Shopify image filters with responsive widths, intrinsic dimensions,
  meaningful alt text and correct loading priority.
- One H1 per page. Reusable sections must not emit their own canonical, robots,
  hreflang or page-level structured data.
- Guard every object access: {% if collection.products.size > 0 %}.
  Liquid cannot read query parameters directly; use built-in objects and
  filters.

## Critical flows
Test these whenever they are touched: search, variant selection, add to cart,
cart drawer, discounts, price and tax labels, stock messaging, filters,
pagination, account links, forms, checkout handoff.

## Quality gates
A change is not complete until:
- Shopify Theme Check passes
- Desktop and mobile rendered review, where a preview is available
- Keyboard navigation works with visible focus states
- No horizontal overflow, clipping, overlap or obscured text
- WCAG 2.2 AA contrast passes on every rendered surface and state, including
  overlays and merchant-selectable colour schemes
- Console shows no new errors
- Affected critical flows tested

## Honesty rule
Do not report a page as finished when rendered QA was unavailable. State the
exact verification limit instead.

The honesty rule is worth keeping. Agents overstate completion, and making it an explicit checkable requirement changes what they report back.

4. Context engineering

The most common failure on Shopify projects is confident invention.

Liquid is particularly prone to it. It contains non-obvious patterns, community workarounds and language limitations that don’t appear in basic documentation, and there is a large volume of outdated Liquid on the web for a model to have absorbed. Ask for something slightly unusual and you get an object or filter that reads correctly and doesn’t exist. GraphQL has the same problem with deprecated fields and REST-era patterns.

Three fixes, in order of impact.

Give it real schemas

This is what the AI Toolkit does. With it connected, Codex validates GraphQL against the bundled schema and Liquid against Shopify’s theme rules before handing anything over. Without it, every line needs manual cross-checking against the reference.

When the generic path returns something close but wrong, use specific tool calls rather than re-prompting: introspect the GraphQL schema to check field availability, validate the code block directly, or fetch the full documentation page instead of a search chunk.

Break the theme into small files

Large files reduce output quality. A 1,200-line section template means the agent reasons about hero layout, variant logic and cart behaviour in the same block of context, and its suggestions get vaguer.

Splitting a theme into well-named snippets and focused sections improves what the agent produces, because each unit of context is coherent. The same refactor that makes the theme maintainable makes it legible to the agent.

Keep a decisions file

Maintain a Markdown file documenting significant logic changes and complex workflows. The agent reads your intent rather than reverse-engineering it from code.

5. Blast radius: code changes

Code is recoverable. This is hygiene, and it costs nothing.

• Theme in Git, one focused branch per change.
• Development or unpublished themes only. Development themes are temporary and hidden but use real store data, so you preview against reality without touching what customers see.
• shopify theme push --unpublished on every push. The toolkit supports it but doesn’t enforce it.
• Read the diff before publishing.
• Never use the live theme as scratch space.

With all of the above in place, the worst realistic outcome is a broken preview on a branch, fixed with git checkout.

6. Blast radius: store operations

What it can do

Bulk metafield population. Catalogue clean-up. Retagging several thousand products against a new taxonomy. Restructuring collections. Inventory audits. Work that previously meant a CSV export, a spreadsheet and a re-import.

shopify store auth --store yourstore.myshopify.com --scopes read_products
shopify store execute --allow-mutations

Why it’s riskier than code

Four properties combine badly:

1. Immediate execution. The mutation runs on the live store as soon as the agent runs it. There is no draft state.
2. No preview. You can’t see the change before it happens.
3. No undo and no audit trail. Nothing at the toolkit level records what changed or reverses it.
4. Broad scopes. OAuth permissions apply to whole resource types. write_products grants every product write operation, not the single mutation you were discussing.

The failure mode: you ask for a change to one product, the agent generalises the instruction, and it has applied that change to every matching record before you’ve read its output.

On a development store

Pre-handover, on a dev store with no real orders, customer records or revenue, use it freely. You can reset the store or reload seed data.

Build and prove out the operation here. Get the mutation working, record which resources it touched and what it wrote, and you have a known-good change.

On a client’s live store

Kahunam doesn’t run agent-executed mutations against live client stores.

The tooling works. The control surface doesn’t exist. You can’t preview the change, stage it, roll it back, or produce an audit trail for the client afterwards. Codex writes the operation; a human executes it, against a controlled path, with a backup in hand.

If you do it anyway

Some jobs genuinely need a bulk change on a live store, and the alternative is a week of manual admin work. It can be done responsibly with mitigation at each step.

Before

• Export a full backup of every field you’re about to touch, via bulk operation query or CSV export, stored outside the store. This is your only rollback.
• Provision a dedicated credential. Create a custom app with the narrowest scopes for this specific job and revoke it when the job is done. Don’t reuse a long-lived token with broad write access.
• Read-only first. Connect with read scopes and have Codex explore and audit. Add write scopes as a separate step.

Planning

• Supply the record set yourself. Don’t let the agent decide which records match. Give it an explicit list of IDs or handles you generated and reviewed.
• Require a deterministic dry run. Have Codex produce a file listing every resource it will touch with field-level before and after values. Read it. This is the preview the toolkit doesn’t provide.
• Separate generation from execution. The agent writes the mutation script; you run it. This removes the failure class where the agent decides to proceed.

Executing

• Canary batch first. Run against five to ten records and verify them in the admin. Then proceed.
• One resource type at a time, and one field where possible.
• Query before you mutate. Read current state before writing so you don’t overwrite a value you didn’t know was there.
• Be specific. “Optimise my products for SEO” is not an instruction. “Set the meta description for product handle classic-tee to X” is.
• Use Codex approval modes so no command executes without confirmation. Don’t run this work in a full-auto configuration.
• Log everything. Have the script write each mutation and response to a file. That’s your audit trail.
• Run outside trading hours on a store taking real orders.

After

• Re-export and diff against your backup. Confirm the change matched the dry run.
• Inspect user errors in the mutation responses. GraphQL returns partial success quietly.
• Revoke the credential.

7. The verification loop

Three layers.

Automated

Put these in the agent’s loop so it runs them and reacts to the output:

shopify theme dev --store your-store   # hot-reloading preview
shopify theme check                    # Liquid and JSON linter

An agent that runs its own linter and fixes its own errors produces different results from one that hands you code and stops.

For performance work, add the Theme Inspector MCP:

codex mcp add shopify-theme-inspector -- npx -y shopify-theme-inspector-mcp@latest

Manual

VS Code with the Shopify Liquid extension, Shopify CLI, Chrome DevTools, Git. For app conflicts, disable apps one at a time and confirm in the console rather than asking the agent to rewrite something. Read the logs.

Require the agent to explain the root cause, not just supply a patch. If it can’t say why the bug happens, the fix is a guess.

Human

A working store has to hold up across customer experience, catalogue data, app interactions, payments, fulfilment, analytics, accessibility, SEO and real order behaviour.

Codex can confirm your Liquid is valid. It can’t tell you the variant picker is confusing, that the shipping rules contradict the returns policy, or that the discount stacks wrong on a bundle. Treat it as a fast junior that proposes while you approve.

8. Benchmark-driven optimisation

The case

In March 2026, Shopify CEO Tobi Lütke published the results of a performance project on Liquid — the open-source Ruby engine that renders every Liquid storefront. The work was done with a coding agent, and the pull request is public: Shopify/liquid #2056.

It records 93 commits and roughly 120 autonomous experiments, producing 53% faster parse and render and 61% fewer allocations.

The number matters less than where it came from. Liquid has been worked on by hundreds of contributors and hand-optimised for years. Finding gains of that size in a codebase that mature is the part worth paying attention to.

Why it worked

The agent wasn’t asked to make Liquid faster. It was given a measurable target and a safety net, then allowed to run a large number of attempts against it. Three conditions were already in place:

1. A strong test suite, so a wrong answer failed loudly
2. A clear benchmark, so every attempt could be scored
3. A codebase where gains were still available

Agents are effective at searching a solution space. They’re poor at deciding what to search for. The three conditions above are what convert one into the other.

Applying it to a theme

Don’t ask Codex to make the site faster. Give it a number to move and a test that fails when it breaks something.

Worked example — a slow collection page:

1. Establish a baseline. Use Shopify’s Theme Inspector to profile server-side Liquid render on the collection template against a fixed test collection. Say it comes back at 480ms on a 48-product collection. Record the collection handle; every subsequent measurement has to use the same one or the numbers are meaningless.

2. Find the actual bottleneck. The profile shows most of the time inside the product-card snippet, called 48 times, each call doing a metafield lookup and a nested loop over variants to build a price range.

3. Write the brief with the metric in it.

Reduce Liquid render time for templates/collection.json against the test-48 collection. Baseline is 480ms. Rendered output must be identical — badge, swatches and price range all still present. shopify theme check must pass. Re-profile after each change and report the number.

4. Let it run attempts. Typical wins here: hoisting repeated lookups out of the loop with assign, replacing nested variant iteration with a single pass, dropping metafield calls whose output isn’t rendered, deferring non-critical markup.

5. Verify each attempt against the same profile and the same collection. Reject anything that changes rendered output, regardless of what it did to the number.

This is the work that normally gets deprioritised — measurable, repetitive, and slow to do by hand. It’s also where an agent given a benchmark outperforms one given an instruction.

Setup checklist

1. Theme in Git, one focused branch per change.
2. Shopify AI Toolkit installed in Codex via /plugins, or npx skills add re-run periodically.
3. export OPT_OUT_INSTRUMENTATION=true for client or proprietary work.
4. MCP configured in TOML. Theme Inspector MCP added for performance work.
5. A hand-written AGENTS.md under about 150 lines: workflow, environment rule, Shopify conventions, critical flows, quality gates, honesty rule.
6. Theme split into small, well-named sections and snippets, plus a decisions .md file.
7. shopify theme dev and shopify theme check inside the agent’s loop.
8. Development or unpublished themes only. --unpublished on every push.
9. Store mutations on development stores. On live stores: human-executed, with backup, dry run, canary batch and audit log.
10. A human reviewing the diff and the rendered result before anything ships.

Further reading

• Shopify AI Toolkit — github.com/Shopify/Shopify-AI-Toolkit
• Official toolkit documentation — shopify.dev/docs/apps/build/ai-toolkit
• Shopify Dev MCP — shopify.dev/docs/apps/build/devmcp