How to Reference Multiple Images in Codex Desktop

Codex Desktop can inspect pasted screenshots, but a long prompt that says "the first image" or "attachment three" becomes fragile as soon as you add more files or continue the conversation. Save each image under a descriptive local filename, give Codex the exact path and role, and make it verify the mapping before it edits anything.

This is a workflow, not a hidden attachment-name feature. An open Codex Desktop request from August 7, 2026 asks for addressable names such as @attachment1; the report says that syntax is not currently available and recommends saving screenshots to the filesystem as a workaround. Use stable paths until Codex documents or ships a different attachment contract.

The Reliable Workflow

1. Save every screenshot as a real file.

2. Give each file a short, ordered name based on its role.

3. Keep the files in one workspace-readable folder.

4. Provide the absolute path and role for every image.

5. Ask Codex to open all files and verify the mapping before analysis.

6. Separate visual diagnosis from code changes.

For a three-image comparison, use names like these:

01-current.png
02-expected.png
03-reference.png

The number preserves order. The word preserves meaning. If the conversation is compacted, resumed, or handed to another Codex surface, the mapping remains recoverable from the prompt and the filesystem.

Put the Images in a Workspace-Readable Folder

Choose an existing project-local scratch folder that your repository ignores. If the project has no convention, create a temporary review folder and confirm that it will not be committed:

review_dir="$PWD/tmp/codex-image-review"
mkdir -p "$review_dir"
git check-ignore "$review_dir" || git status --short -- "$review_dir"

Save or copy the screenshots into that folder, then inspect the exact inventory:

find "$review_dir" -maxdepth 1 -type f -print

Do not put private customer data, access tokens, internal dashboards, or unredacted personal information in screenshots. If the images must not enter the repository, confirm the folder is ignored before continuing and remove the local copies after the review is complete.

Use One Explicit Image Manifest

Do not rely on visual order alone. Paste one manifest that assigns a role to every absolute path:

Compare exactly these three images:

CURRENT: /absolute/path/to/tmp/codex-image-review/01-current.png
EXPECTED: /absolute/path/to/tmp/codex-image-review/02-expected.png
REFERENCE: /absolute/path/to/tmp/codex-image-review/03-reference.png

First open all three files. Before suggesting a change, return a table with:
- role
- filename
- pixel dimensions
- one visible detail that confirms the mapping

If any file cannot be opened or the mapping is ambiguous, stop and tell me which path failed. Do not edit files yet

Pixel dimensions and one visible detail make a useful canary. A response that merely repeats your filenames does not prove that Codex opened the correct files. If the canary fails, fix the path or permission boundary before asking for implementation.

Separate Diagnosis From Implementation

Once Codex confirms the manifest, ask for a bounded comparison:

Treat CURRENT as the implementation under review, EXPECTED as the required outcome, and REFERENCE as style guidance only.

List the five most important visual differences. For each difference, identify:
1. the affected region;
2. the observed state in CURRENT;
3. the required state in EXPECTED;
4. whether REFERENCE changes the interpretation;
5. the smallest likely code change.

Do not edit yet. Mark anything that cannot be inferred from the images

Review that diagnosis before authorizing changes. This prevents Codex from treating a style reference as the expected pixel-perfect target or modifying code based on an incorrectly ordered attachment.

Then give a separate implementation prompt:

Implement only the approved differences numbered 1, 2, and 4. Preserve responsive behavior and existing design-system components. After the change, run the targeted tests, capture a new screenshot as 04-result.png, and compare 04-result.png against 02-expected.png. Report remaining differences without making a second round of edits

The new result gets a new filename. Never overwrite 01-current.png; preserving the original makes the comparison auditable.

If the visual change is part of a broader release gate, pair this comparison with the Aident guide to verifying AI coding-agent tests so the screenshot result and executable checks stay separate.

Why Pasted Attachments and Local Paths Differ

An image attachment gives the model visual context. A local path gives tools a durable object they can reopen, measure, copy, rename, or pass to another command. Those are related capabilities, but they are not interchangeable.

OpenAI's Codex prompting guidance recommends saving a screenshot locally for CLI workflows and attaching images when visual context matters. The Codex app-server contract also distinguishes remote image URLs from localImage inputs that carry a path. Upstream work merged in June 2026 to expose local image paths to models, yet the newer Desktop request shows that users still cannot assign convenient symbolic names to a group of freshly pasted attachments.

That is why the manifest workflow is conservative: it depends on ordinary files and explicit paths, not on guessing whether attachment1, "the image above," or message order will remain meaningful later.

When You Only Have Pasted Images

If the screenshots exist only as chat attachments, use one of these paths:

• For one or two images, describe each by a unique visible feature and ask Codex to confirm the order before analysis.

• For several images, save each screenshot to the workspace-readable review folder and restart the comparison with the manifest.

• If the image must be copied, renamed, uploaded, or committed, save it as a file first. A visually inspectable attachment may still lack a tool-usable path.

Do not ask Codex to infer a local filename from pixels. Do not paste sensitive screenshots again merely to repair an ambiguous order. Do not let an attachment comparison silently become authorization to modify the repository.

Verify the Review Did Not Pollute the Repository

After the comparison, check the working tree:

git status --short

Expected result: only the intended implementation files and approved evidence are present. Scratch screenshots should remain ignored or be removed from the local review folder. If an image is meant to become a real product asset, move it into the repository's documented asset location and review that addition like any other source file.

Monitor Native Attachment References

Aident Loadout can monitor the upstream feature request through a governed, read-only GitHub Action without giving Codex permission to alter the issue.

Give Codex the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then use this prompt:

Check my Aident Loadout account authentication and Vault status. Search the staging capability catalog for a connected read-only GitHub issue-search Action, inspect its current schema, and preflight it. If the estimate is free, return only the state, updated time, title, labels, reaction count, and URL for openai/codex issue 37412. Do not comment, edit, close, label, publish, install, change files, start OAuth, or request a GitHub token.

Success is measurable: the current issue record is returned, the receipt shows a read-only search, and no GitHub write occurs. Set up Aident Loadout and monitor Codex attachment references.

Sources

• OpenAI Codex issue 37412: allow referencing pasted images in chat

• Official Codex prompting guidance for image inputs

• Official Codex CLI reference

• Official Codex app-server image input contract

• OpenAI Codex PR 25944: expose local image paths to models

• OpenAI Codex issue 25983: attachments without tool-usable local files

• OpenAI Codex issue 9283: pasted image paths converted into attachments

Refresh this guide when issue 37412 changes state, Codex documents symbolic attachment references, or Desktop exposes a durable path or identifier for every pasted image.