Optimize images and alt text with Codex
Optimizing Shopify images with Codex means asking OpenAI's coding agent, from your terminal or editor, to read your image statuses through StoreSEO and then compress them and write alt text and file names one image per call, with a restore for any change you reject.
Last updated: October 2026
Set up Codex for StoreSEO
Skip this if Codex is already connected. The full guide, with the alternatives, is on the Codex page.
- 1
Add StoreSEO to Codex
Run this in any terminal. It writes a [mcp_servers.storeseo] table to ~/.codex/config.toml, which the Codex CLI, the IDE extension and the ChatGPT desktop app all read.
Terminalcodex mcp add storeseo --url https://mcp.storeseo.com/mcp
- 2
Sign in to your store
Run the login command. Your browser opens: pick your Shopify store and approve access. Then run codex mcp list, or type /mcp inside Codex, to confirm storeseo is there.
Terminalcodex mcp login storeseo codex mcp list
How does this work in Codex?
You start Codex in the theme repository and ask it to list the product images that have no alt text and the heaviest ones that are not compressed. Codex calls storeseo_start and storeseo_list_images, which are reads, and under a writes approval mode they run without a prompt because they are marked read-only. The listing gives each image's compression, alt text and file name status, and Codex can turn it into a worklist file in the repository or search the theme for the file names before you rename anything.
The server's approval setting in config.toml decides what happens next. With default_tools_approval_mode set to writes or prompt, Codex stops before storeseo_optimize_image and storeseo_restore_image, which is the hard stop, while StoreSEO also tells the agent to name the Image Optimizer quota or AI credit it will spend and wait for your yes. Each call handles one image with the axes you picked and returns a report for compression, file name and alt text separately, so Codex can tell you which part applied and which was refused. Codex shares config.toml between the CLI, the IDE extension and the ChatGPT desktop app, so the same approval settings apply wherever you run the job.
Timing matters in this job. A file name change on a collection or article image re-uploads it, and Codex waits 60 seconds for a tool by default, so those calls can run out of time before StoreSEO finishes. If that happens, re-list the image to see its state rather than repeating the call, because a retry regenerates and spends again.
-
You: List the product images with no alt text and the heaviest unoptimized ones.
- storeseo_start read-only
- storeseo_list_images read-only
-
Codex: There are 31 images with no alt text, and the five heaviest are on Canvas Tote and Ceramic Mug. Alt text spends AI credit and each call covers one image. Shall I write alt text for the Canvas Tote images first?
-
You: Yes, Canvas Tote only.
- storeseo_optimize_image needs approval
-
Codex: First Canvas Tote image has alt text. Codex is waiting on the approval for the second call.
What to ask Codex
List my images with no alt text via StoreSEO, group them by product and write the result to images-todo.md. Make no changes.
Compress the ten heaviest unoptimized product images, one call per image, and stop for my yes before the first call.
Rename and add alt text to the images on my Collection Summer banner, and tell me about the URL change before you start.
- Find my ten heaviest unoptimized product images and compress them. Tell me the quota it will use first.
- Which product images have no alt text at all? Write alt text for the ones on my best seller.
- Optimize every image on the product Canvas Tote: compression, alt text and file name.
- Restore the original alt text on the last image you changed.
- Give my collection images descriptive file names, and warn me which URLs will change.
What StoreSEO does: image seo and alt text
StoreSEO tracks three things per image: file-size compression, alt text and file name. The agent finds the heaviest or unlabelled images, optimizes them one call per image, and can restore any of the three if you do not like the result.
Requires: Compression needs the Image Optimizer add-on and counts against its monthly quota; alt text and file names spend AI Content Optimizer credit.
- 1
Find the images
The agent lists product, collection or article images, heaviest unoptimized first by default. It can filter to images with no alt text, or scope the list to one product by title.
- 2
Check what it found
A title search can also match image file names from other resources, so the agent checks each row belongs to the product you meant.
- 3
Agree the scope and cost
Compression uses image quota and alt text and file names use AI credit, so the agent confirms before working through many images.
- 4
Optimize one image per call
Each call takes the axes you want: compression, alt text, file name or all three. The axes always run compression, then file name, then alt text, and the response reports each one separately.
- 5
Report or restore
The agent reports what applied, what was already done and what was refused. If a result is wrong, the restore tool brings back the original file, alt text or name.
Image SEO and alt text reference
| Axes per image | Compression, alt text, file name |
|---|---|
| Image sources | Products, collections and articles (pages have no images) |
| Batching | One image per call; never two calls on the same image at once |
| Compression | Image Optimizer add-on and its monthly quota; an already compressed image is reported as already applied |
| Alt text and file name | AI Content Optimizer credit; both together are billed as one generation |
| File name change | Renames the file on Shopify and changes the image's storefront URL |
| Collection and article renames | Re-upload the image, so the call can take a couple of minutes |
| Restore | Reverts compression, alt text or file name per axis |
| Score impact | Alt text and file names count on products, collections and articles; compression counts on products |
Rules Codex follows
- The agent confirms the number of images and the kind of spend before a bulk run.
- One image per call, all wanted axes together; never parallel calls on the same image.
- A renamed image has a new URL, so the agent tells you, because anything that hard-coded the old URL keeps serving the old file.
- If a response is lost, the agent re-lists the image instead of retrying, because a retry regenerates and spends again.
- A refused axis, for example compression without the add-on, is reported as such while the other axes still apply.
In Codex
Codex waits 60 seconds for a tool call by default, and a file name change on a collection or article image re-uploads it, which StoreSEO says can take up to a couple of minutes. Raise tool_timeout_sec for the storeseo server before renaming those images. If a call times out, re-list the image with storeseo_list_images to see what applied rather than retrying, because a retry regenerates and spends again. Do not set the server's approval mode to approve, since that removes the prompt in front of every image write.
What runs without asking. Reads such as SEO scores, store listings, settings and Google reports run straight away. Generating a preview spends AI credit but writes nothing, and StoreSEO tells the agent to say what a generation will cost before it runs one. Applying content, optimizing images, changing settings, publishing llms.txt or agents.md, writing a product description and deleting anything wait for your yes in the conversation. That yes is an instruction the agent follows, not a lock on the server, so your client's own tool-approval setting is the hard stop.
Questions
Why did my Codex image rename time out?
Renaming a collection or article image re-uploads it, which can take up to a couple of minutes, and Codex waits 60 seconds by default. Raise tool_timeout_sec for the storeseo server in config.toml, and re-list the image before retrying so you do not spend credit twice.
Which Codex approval mode suits image optimization?
Use writes or prompt for the storeseo server. Reads such as listing images then run freely while storeseo_optimize_image and storeseo_restore_image stop for approval, and that setting is the hard stop in addition to the yes StoreSEO tells the agent to wait for.
Can the agent compress images without the Image Optimizer add-on?
No. Compression needs the Image Optimizer add-on and counts against its monthly quota. Alt text and file names work without it and spend AI Content Optimizer credit instead.
Can I undo an image optimization?
Yes. The restore tool reverts compression, alt text or file name for one image, per axis. Restoring compression brings back the original file.
Why did my image URL change?
Giving an image a new file name renames the file on Shopify and re-points its storefront URL. Pages that use the image through Shopify keep working, but anything that hard-coded the old URL keeps the old file.
Can I write my own file name or alt text through the agent?
No. StoreSEO writes the alt text and file name from the resource's own context. You can steer the language, and you can always edit alt text yourself in Shopify admin.
Keep going
Image SEO and alt text with other agents
More Codex guides