Codex Photoshop PSD Automation

Turn AI-generated artwork into editable, validated layered PSDs.

A successful API call is not delivery evidence — the PSD is saved, closed, reopened, and validated.

AI image generators are excellent at producing final visuals. Commercial delivery often needs more: editable text, replaceable assets, independent objects, structured groups, and a PSD that can actually be opened and reviewed.

This project uses Codex and Photoshop MCP to assemble, validate, reopen, and verify Reconstructed Layered PSDs from AI-generated or isolated design assets.

AI Artwork / Isolated Assets
            ↓
          Codex
            ↓
      Photoshop MCP
            ↓
     Adobe Photoshop
            ↓
   Reconstructed Layered PSD
            ↓
 Save → Close → Reopen → Validate

The problem

Putting a flat PNG inside a PSD is not an editable source delivery.

Clients may need editable copy, Smart Objects, replaceable assets, visible groups, transparent elements, and a layered file that still works after it is saved and reopened. Manual reconstruction is slow and error-prone; trusting an in-memory automation result is not enough.

What this project does

Codex can orchestrate Photoshop to:

• create structured PSD documents and named groups;
• place isolated assets as independent Smart Objects;
• preserve transparent PNG and Alpha behavior;
• create editable TEXT layers with exact content, font, size, alignment, and RGB validation;
• validate transforms, opacity, effective visibility, required group content, and duplicate layer names;
• reserve non-overwriting output versions;
• save, close, reopen, and inspect the persisted PSD;
• independently decode the final preview and retain failure evidence on errors.

Why this is different

Why not just put a PNG inside a PSD?

Because that does not prove the source file is editable or deliverable.

This workflow verifies that required assets remain independent, text remains editable, Smart Objects survive reopening, Alpha survives reopening, transforms remain correct, required groups are effectively visible, and previews are decodable. The final artifact is validated from disk rather than trusted because an API returned success.

Reconstructed Layered PSD

This project does not claim to magically restore the unknown original layers of a flat image. Instead, it reconstructs an editable PSD from complete backgrounds, isolated major elements, editable text, and declared layout rules.

Final AI concept
      ↓
Generate or extract a complete background and isolated elements
      ↓
Reassemble in Photoshop with Smart Objects and editable text
      ↓
Validate the persisted layered PSD

Real Photoshop evidence

Validated on Adobe Photoshop 2026 / 27.8.0:

Gate	Result
PSD save → close → authoritative reopen	PASS
Editable TEXT content, alignment, RGB, exact font, and size	PASS
Smart Object transforms, opacity, and effective visibility	PASS
Required group visibility and recursive content	PASS
Transparent PNG / Alpha preservation	PASS
Case C multi-transparent-PNG composition	PASS
Independent preview decoding	PASS
Full-resolution preview pixel round-trip	PASS
Photoshop state restoration	PASS
Unit tests	221 / 221 PASS

Status: PRODUCTION READY FOR REVIEWED DELIVERY.

That means the technical delivery workflow is verified for commercial review. New customer artwork still requires human visual approval; this is not autonomous aesthetic approval.

Architecture

┌──────────────┐
│    Codex     │
└──────┬───────┘
       │ MCP
       ▼
┌────────────────────┐
│ Photoshop MCP      │
│ TypeScript / Node  │
└────────┬───────────┘
         │ COM / ExtendScript
         ▼
┌────────────────────┐
│ Adobe Photoshop    │
└────────┬───────────┘
         ▼
┌────────────────────┐
│ Editable PSD       │
│ + Preview + Report │
└────────────────────┘

Quick start

Windows with Adobe Photoshop is required for real Photoshop integration.

npm ci
npm run build
npm run test:unit

Then configure the MCP server for Codex or another MCP client. See Windows installation and Codex MCP setup.

Useful validation commands:

npm run test:delivery-mcp
npm run test:production-closure

test:production-closure is a real Photoshop test and creates local, gitignored disposable evidence.

Example delivery

background.png
main-subject.png
element-01.png
element-02.png
element-03.png
            ↓
01_Background
02_Main Subject
03_Elements
04_Text
05_Effects
06_Adjustments
            ↓
delivery-v01.psd
delivery-v01.png
delivery-v01-report.json

Who is this for?

• AI designers delivering editable source files
• automation engineers and creative-tooling developers
• freelancers who need reliable PSD handoff
• MCP and agent developers working with desktop creative software
• Photoshop automation enthusiasts

Use cases

• AI packaging artwork → editable PSD
• marketing artwork → structured source file
• AI illustration → separated production layers
• automated PSD QA and delivery validation
• creative delivery pipelines built around Codex and MCP

Limitations

• This is reconstructed layered delivery, not lossless recovery of an unknown original PSD.
• New customer artwork requires human visual review.
• Transactional editing of arbitrary existing customer PSDs (Case D) is not part of v1.0.
• Long-batch and large-file stress testing are outside the current verified matrix.
• Real Photoshop automation currently targets Windows.

Upstream attribution

Built on top of alisaitteke/photoshop-mcp, with additional production-oriented PSD delivery, extraction, validation, recovery, safety, and real-Photoshop verification workflows.

The upstream project provides the MCP server, Photoshop connection and execution foundation. This project adds the delivery-oriented workflow and evidence gates described above; it does not claim the entire Photoshop MCP was created from scratch.

See upstream audit, delivery specification, and production readiness.

License

MIT. See LICENSE. The upstream attribution is retained.

If you are building AI-assisted creative workflows, Photoshop automation, or MCP tooling, a ⭐ helps others discover the project.