agent-bridge-for-photoshop（Photoshop Agent 桥）

Agent Bridge for Photoshop Skill

Product summary

Agent Bridge for Photoshop is a local automation stack for Photoshop that provides a stable command surface, operation payload schema, and runtime bridge between CLI workflows and Photoshop UXP APIs. Agents use the psagent CLI to control Photoshop documents, layers, and operations through JSON operation envelopes. The bridge daemon runs on http://127.0.0.1:43120 and brokers calls between the CLI and a UXP plugin inside Photoshop. Key files: .psagent.json (project config), ~/.config/psagent/config.json (user config), operation envelope JSON payloads. Primary CLI: psagent with subcommands for sessions, documents, layers, operations, rendering, checkpoints, and diagnostics. MCP server available via psagent mcp-serve for agent tool integration.

When to use

Reach for this skill when:

• Automating Photoshop document and layer operations (create, rename, delete, style, export)
• Building reproducible creative workflows with deterministic operation sequences
• Managing document state with checkpoints and rollback capabilities
• Querying document structure (manifest, layers, properties)
• Exporting renders (PNG/JPG) from Photoshop programmatically
• Testing operation payloads before production use (dry-run mode)
• Integrating Photoshop automation into agent-driven workflows via MCP tools
• Debugging operation failures and validating bridge connectivity

Quick reference

Essential CLI commands

Discover operation contracts from CLI help

Use these before writing an ops payload:

• psagent op -h to see the full operation list/capability catalog.
• psagent op <command> -h to see required args, supported args, notes, aliases, and a copy/paste JSON example for that operation.

Working patterns (quality-first)

• Centered headline pattern: create or style text with position.x = 0, set maxWidth to the canvas/section width, and set alignment: "center" instead of hand-tuning x values.
• Baseline positioning pattern: createTextLayer.position.y is the text baseline (not visual top). For large text, set a lower baseline and iterate with quick renders.
• Readable text pattern: set explicit text color via textColor/color and add setLayerEffects drop shadow or stroke for contrast on busy photos.
• Shape polish pattern: use createShapeLayer with cornerRadius and fillType: "gradient" for modern buttons/badges.
• Photo frame pattern: place photo layer above a frame shape and apply createClippingMask to constrain photo bounds.
• Single-transaction pattern: keep all dependent operations for one document in the same op apply call to avoid active-document drift between CLI invocations.
• Iterative composition pattern: render after each logical group (background, photo, text, accents, CTA) and adjust before adding the next group.
• Pacing pattern for stability: when Photoshop is unstable under heavy automation, set safety.opDelayMs (or CLI --op-delay-ms) to add a short delay between ops (for example 80-200ms).

BatchPlay recipes (high-friction cases)

• Preserve text style while changing color: if using textStyleRange, include the full style payload (fontPostScriptName, fontName, fontStyleName, size with unitDouble/pointsUnit, and color) because Photoshop replaces style objects rather than merging.
• Prefer first-class text ops when possible: use createTextLayer/setTextStyle for normal font/size/color/alignment workflows. Reserve batchPlay for gaps not covered by first-class ops.
• Descriptor units are explicit: numeric descriptor values often require {"_obj": "unitDouble", "_unit": "pointsUnit", "_value": <number>} (or other unit enums) instead of raw numbers.

Global flags

Configuration precedence

Flags override environment variables, which override session config, which override project config (.psagent.json), which override user config (~/.config/psagent/config.json), which override defaults.

Environment variables

Operation envelope structure

{
  "transactionId": "tx-001",
  "doc": { "ref": "active" },
  "refs": {
    "hero": "layer_123"
  },
  "ops": [
    { "op": "createLayer", "name": "Draft", "ref": "draftLayer" },
    { "op": "renameLayer", "target": "$draftLayer", "name": "Draft v2" }
  ],
  "safety": {
    "dryRun": false,
    "checkpoint": false,
    "rollbackOnError": false,
    "onError": "abort"
  }
}

MCP tools (for agent use)

Decision guidance

When to use dry-run vs. checkpoint vs. rollback

When to use abort vs. continue error policy

When to use CLI vs. MCP server

Workflow

Typical task: Apply operations to a Photoshop document

1. Start the bridge stack (one-time setup):

- Terminal A: psagent bridge daemon (runs on 127.0.0.1:43120) - Terminal B: Reload UXP plugin in Photoshop (or use npm run bridge:reload) - Terminal C (optional): psagent mcp-serve if using agent tools

1. Verify connectivity:

- Run psagent bridge status — confirm "Connected" and queue is empty - Run psagent doctor — check health, exit code 0 = OK

1. Open a document:

- psagent doc open./path/to/file.psd - Verify with psagent layer list to see current structure

1. Create operation envelope:

- Write JSON file with ops array, safety settings, and refs for layer targeting - Use $refName syntax to reference layers created earlier in same transaction - Keep all dependent ops in one envelope for the same document

1. Test with dry-run:

- psagent op apply -f ops.json --dry-run - Verify schema is valid and operation names are recognized - Check result for applied: 0 (no mutations)

1. Apply with checkpoint:

- psagent op apply -f ops.json --checkpoint - Inspect result for applied, failed, aborted counts - If errors, check failures[] array for details

1. Validate output iteratively:

- After each logical block, render and inspect: - psagent render --format png --out./preview-step-<n>.png - Confirm structure and refs: - psagent layer list - Inspect document properties as needed: - psagent doc manifest

1. Rollback if needed:

- psagent checkpoint list to see available snapshots - psagent checkpoint restore <id> to revert to checkpoint

Typical task: Use MCP tools from an agent

1. Start psagent mcp-serve in a terminal
2. Agent client connects via JSON-RPC over stdio
3. Call tools in order:

- photoshop_capabilities — confirm adapter is ready - photoshop_open_document — open target file - photoshop_get_manifest — inspect structure - photoshop_query_layers — find specific layers - photoshop_apply_ops — execute operation envelope - photoshop_render — export result - photoshop_checkpoint_restore — undo if needed

Common gotchas

• Daemon not running: psagent op apply will timeout if psagent bridge daemon is not running on 127.0.0.1:43120. Always start daemon first.
• UXP plugin disconnected: psagent bridge status shows "Disconnected" if Photoshop UXP panel is not loaded. Reload plugin with npm run bridge:reload or manually in Photoshop.
• Text style confusion: createTextLayer already supports styling/fitting args like font, fontName, fontSize, textColor, alignment, maxWidth, and overlap controls. Use setTextStyle for post-create edits or re-styling existing text layers.
• Text baseline mismatch: createTextLayer.position.y is baseline-aligned. If text appears clipped or too high, move the baseline down and re-render.
• BatchPlay textStyleRange resets styles: textStyleRange[*].textStyle replaces style values; it does not patch them. Include full style fields (font + size + color) in the descriptor.
• Active document drift across commands: Photoshop can switch active documents between separate CLI calls. Put dependent operations in one op apply payload and set doc.ref.
• saveDocumentAs key confusion: saveDocumentAs uses output for destination path. path is not a valid key.
• Layer references fail silently: Use $refName syntax to reference layers created in the same transaction. If reference is wrong, operation may target wrong layer or fail. Validate with --dry-run first.
• Rollback doesn't work as expected: rollbackOnError: true uses best-effort history snapshot strategy. Some Photoshop actions may not be fully reversible. Test rollback behavior in dry-run before relying on it.
• Checkpoint restore is slow: Restoring large documents from checkpoint can take seconds. Don't call checkpoint restore in tight loops.
• Schema validation errors are silent in JSON output: Check result.failures[] array for validation errors. Exit code will be non-zero if schema validation fails.
• Operation names are case-sensitive: Use exact canonical names like createLayer, not CreateLayer or create_layer. Alias forms (e.g., layer.rename) map to canonical names.
• Timeout on slow operations: Large document operations may exceed default timeout. Use --timeout <ms> to increase limit for batch operations.
• Dry-run still requires valid document: --dry-run validates schema but still needs an open document. Session must be active.

Verification checklist

Before submitting work with Agent Bridge for Photoshop:

• Bridge daemon is running on 127.0.0.1:43120 (verify with psagent bridge status)
• UXP plugin is connected (status shows "Connected", not "Disconnected")
• Document is open (psagent doc open succeeded, psagent layer list returns layers)
• Operation envelope JSON is valid (test with --dry-run first)
• All layer references use correct $refName syntax
• Text operations account for baseline positioning (position.y)
• If using batchPlay textStyleRange, descriptors include full style fields to preserve font/size/color
• Error policy is set correctly (onError: "abort" or "continue" as needed)
• Checkpoint is created before risky operations (--checkpoint flag)
• Result payload shows expected applied count (not failed or aborted)
• Cleanup operations (e.g., deleteLayer) are included to remove temporary layers
• Output is validated (render exported, manifest checked, layers verified)
• Exit code is 0 for success, non-zero for errors

Resources

• Comprehensive navigation: https://agent-bridge-for-photoshop.jaredverdi.com/llms.txt — full page-by-page documentation index
• CLI reference: https://agent-bridge-for-photoshop.jaredverdi.com/reference/cli-reference — all commands, flags, and exit codes
• Operation envelope: https://agent-bridge-for-photoshop.jaredverdi.com/reference/operation-envelope — payload schema, refs, safety controls, error handling
• Operation arguments and examples: https://agent-bridge-for-photoshop.jaredverdi.com/reference/operation-arguments-and-examples — operation parameters and real payload examples
• Real-world workflows: https://agent-bridge-for-photoshop.jaredverdi.com/guides/real-world-workflows — patterns for agent-driven creative automation

For additional documentation and navigation, see: https://agent-bridge-for-photoshop.jaredverdi.com/llms.txt