What the agent does
The agent reads the app's configuration first, because a theme app extension is a second deployable inside the same repository. In an app built from Shopify/shopify-app-template-react-router, package.json runs shopify app dev, shopify app generate and shopify app deploy as scripts, lists extensions/* as npm workspaces, and pins React Router 7.18.2 for the reasons its CHANGELOG.md records. shopify.app.toml has an empty client_id for the template, scopes = "write_products", webhook subscriptions for app/uninstalled and app/scopes_update on API version 2026-10, and an [events] subscription that fires only when a variant's price changes. extensions/ holds a .gitkeep and nothing else, and .graphqlrc.ts already loops over extensions/* looking for a schema.graphql, so a theme extension, which has none, is skipped cleanly. app/routes/app._index.tsx creates a product through productCreate as the template's demo, app/routes/app.tsx holds the s-app-nav menu, and .github/workflows/ci.yml runs tsc --noEmit, npm run lint, prisma validate and npm run build across Node 22 and 24 with npm, yarn and pnpm. The repository's AGENTS.md points every Shopify platform question at the Shopify Dev MCP server the template configures in .mcp.json.
The extension is generated with the CLI rather than written from scratch, so its layout matches what the platform expects: shopify app generate extension --template theme_app_extension --name product-badge creates extensions/product-badge/ with assets/, blocks/, snippets/, locales/, a package.json and a shopify.extension.toml whose type is theme. The generated example is a product-rating block reading a demo.avg_rating metafield; the agent replaces it with what the app sells. An app block in blocks/product-badge.liquid renders a badge next to the product title with a {% schema %} that sets a name under 25 characters, target: "content", settings for the badge text, a color and a toggle, enabled_on limited to product templates, and stylesheet and javascript entries naming files in assets/. An app embed block in blocks/announcement-bar.liquid with target: "body" injects a dismissible bar on every page once a merchant turns it on under Theme settings, App embeds, with its copy in locales/en.default.json so it can be translated.
The blocks stay inside the limits the platform enforces and the ones it suggests: 30 blocks, 10 MB in total, 100 KB of Liquid across the extension, 100 locale files of 15 KB each, and the suggested 10 KB of compressed JavaScript and 100 KB of CSS per block. The agent keeps the badge script to a few lines in assets/product-badge.js and the bar's dismiss state in localStorage, writes the two stylesheets with class names prefixed to the extension so they cannot collide with Dawn's, and adds a snippet in snippets/ for the badge markup so both the block and a future section can render it. The app code does not change: a theme app extension reads settings from its own schema and the metafields the app writes, so the write_products scope and the existing routes stay as they are.
The checks are the ones that run without a Partner login. The agent runs the CLI's Theme Check against the extension directory, which validates the Liquid, the schema JSON and the asset references, then npm run typecheck, npm run lint and npm run build to be sure the workspace addition broke nothing in the app, and reads the extension's shopify.extension.toml back to confirm the name, type and handle. shopify app dev and shopify app deploy need the reader's Partner account and a development store, so the pull request says which command to run to preview the blocks in the theme editor on Dawn and what to look for: the badge on a product page, the embed under App embeds, both settings panels, and that the bar does not cover the page.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a theme app extension to this Shopify app. Read package.json, shopify.app.toml, .graphqlrc.ts, AGENTS.md, app/shopify.server.ts, the routes under app/routes and .github/workflows/ci.yml first. Generate the extension with shopify app generate extension --template theme_app_extension --name product-badge, then replace the generated rating example with an app block that renders a configurable badge on product pages (text, color and toggle settings, enabled only on product templates, with its stylesheet and script in assets) and an app embed block with target body that shows a dismissible announcement bar with translatable copy in locales/en.default.json. Keep each block within Shopify's enforced and suggested size limits and prefix every class name. Run Theme Check on the extension, npm run typecheck, npm run lint and npm run build, and open a pull request that quotes the output and tells the reviewer how to preview the blocks with shopify app dev in the theme editor.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds extensions/product-badge/ with its shopify.extension.toml, two block files, one snippet, two stylesheets, one script and a locale file, and changes package-lock.json for the new workspace. Nothing under app/ changes. Its description quotes the Theme Check result and the three npm commands, lists each block's settings, and ends with the preview steps: shopify app dev, open the host theme in the editor, add the badge block to the product template and enable the announcement embed.
A reviewer reads the two schemas, since settings are what merchants will see, and the Liquid, which runs inside every storefront that installs the app. The CI matrix runs the same type check, lint and build on the pull request. The preview on a development store is the one step only the reviewer can take, and the description tells them exactly what to check there before shopify app deploy creates a version.
Run it on every Linear issue labelled theme
In the console, add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled, filtered to the theme label. When an issue such as "merchants want to show the badge on product pages without editing their theme" gets the label, the trigger puts the issue after the prompt, and the run reads which block, settings and templates the issue asks for before generating anything. Only label changes by a person in your Rush org fire it, and the automation starts at most max_runs_per_hour runs in an hour.
An automation's runs are read-only, so the run that pushes the branch starts from your own server: a handler receiving the automation's comment sends this body to POST /o/{org}/sessions with the issue URL in resources and a request_id that is a UUID v5 of the issue id, so a redelivered event returns the run already started.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A theme app extension has its own tooling, its own limits and its own review surface, and a mistake in it ships to every storefront that installs the app. The agent generates the extension with the CLI so the layout is the platform's, writes blocks against the schema fields and limits the documentation sets out, runs Theme Check and the app's own checks in its own sandbox, and keeps every command and its output in the run's record.
The agent also knows where its sandbox ends. Previewing in a theme editor needs the reader's Partner account, so instead of pretending, the pull request carries the exact steps to take there and what each should show, which is what a reviewer needs to finish the job in a few minutes.
Frequently asked questions
What is the difference between the two blocks?
An app block with target: "content" is placed by the merchant inside a section of an Online Store 2.0 theme and can be moved and configured in the editor. An app embed block with target: "body" has no placement: Shopify injects it before </body> on every page once the merchant enables it under App embeds, and it works in older themes too.
Does the app need new scopes?
No. A theme app extension renders from its own settings and from data the app already writes, such as product metafields under write_products. If a block later needs a metafield the app does not write yet, that is an app change with its own pull request.
Can the agent preview it in a store?
Not from the sandbox. shopify app dev signs in to a Partner account and pushes the extension to a development store, which only the reader can do. The agent runs Theme Check and the app's checks instead and writes the preview steps into the pull request.
How are the size limits handled?
The agent keeps the script and stylesheets small and reads their sizes before opening the pull request, against the 10 MB total, 100 KB of Liquid and 30 blocks the platform enforces and the 10 KB of JavaScript and 100 KB of CSS it suggests per block. The description lists each file's size.
Will merchants see the blocks right after deploy?
After shopify app deploy releases a version, app blocks appear in the theme editor's block picker and embeds under App embeds, switched off until the merchant turns them on. The pull request suggests a line for the app's onboarding page telling merchants where to find them.
More Shopify App jobs
More jobs like this: Turn a Linear label into a PR
- Add Throttling to a Django REST Framework API from a Linear Issue (Django REST Framework)
- Add TLS with cert-manager to a Kubernetes App (Kubernetes)
- Add Pagination to a Vapor API from a Linear Issue (Vapor)