Agent Bridge for Photoshop

Control Photoshop with Codex, Claude Code, or your favorite desktop LLM tools

Formatted docs available at: https://agent-bridge-for-photoshop.jaredverdi.com

Agent-ready Photoshop automation scaffold with:

• psagent CLI command tree
• Desktop adapter contract (/rpc bridge)
• ops.json schema validation
• Minimal MCP-style stdio server
• Minimal UXP plugin scaffold (photoshop-uxp-bridge/)

Quick start

Users

Install the CLI from npm:

npm install -g @jverdi/agent-bridge-for-photoshop

Start daemon:

psagent bridge daemon

Install the Photoshop plugin from Creative Cloud Desktop:

1. Open Creative Cloud Desktop.
2. Go to Stock & Marketplace > Plugins.
3. Search for Agent Bridge for Photoshop and install it.
4. Open Photoshop and open the Agent Bridge panel.
5. Bridge auto-connects on launch; click Connect Bridge only if needed.

Contributing

git clone https://github.com/jverdi/agent-bridge-for-photoshop.git
cd ps-agent-bridge
npm install
npm run build

Run a local mock desktop bridge:

npm run dev -- bridge mock

Run the real bridge daemon (used by UXP plugin):

npm run dev -- bridge daemon

Automate UXP plugin reload + reconnect workflow (macOS):

npm run bridge:reload

Run optional dev hot-reload server for panel code changes (index.js, index.html, manifest.json):

npm run bridge:hotreload

Options:

• Uses UXP CLI plugin load flow (@adobe-fixed-uxp/uxp-devtools-cli) and auto-patches known parser bug locally
• Direct script usage supports flags like --no-wait, --timeout 40, --endpoint http://127.0.0.1:43120
• Script path: scripts/dev/reload-psagent-bridge.sh
• Hot-reload server path: scripts/dev/hot-reload-server.mjs (panel auto-reloads when watched files change)

In another shell, run commands:

npm run dev -- session start
npm run dev -- doc open ./sample.psd
npm run dev -- layer list
npm run dev -- op apply -f examples/ops.cleanup.sample.json --checkpoint
npm run dev -- render --format png --out ./out/mock.png
npm run dev -- doctor
npm run test:integration

Command surface

psagent [global flags] <subcommand>

subcommands:
  capabilities
  session start|status
  doc open|manifest
  layer list
  op apply
  render
  checkpoint list|restore
  events tail
  doctor
  bridge daemon|status|mock
  mcp-serve

Global flags:

• --json, --plain
• -q/--quiet, -v/--verbose
• --timeout <ms>
• --config <path>
• --profile <name>
• -n/--dry-run

Config precedence

flags > env > session > project config > user config > system defaults

• Project config: .psagent.json
• User config: ~/.config/psagent/config.json (or --config path)

Env vars:

• PSAGENT_PROFILE
• PSAGENT_TIMEOUT_MS
• PSAGENT_PLUGIN_ENDPOINT
• PSAGENT_DRY_RUN

npm publishing via GitHub Releases

This repo is configured to publish to npm from GitHub Actions when a release is published.

Workflow:

1. Bump package.json version.
2. Push commit + tag (for example v0.2.0).
3. Create/publish a GitHub Release from that tag.

What the workflow does:

• Runs npm ci, npm run check, npm run build
• Uses npm trusted publishing (GitHub OIDC; no long-lived npm token)
• Verifies release tag matches package.json version (scripts/release/verify-release-tag.mjs)
• Publishes to npm
  • normal release -> latest
  • prerelease -> next

Prerequisite:

• Configure npm trusted publisher for this repository/workflow in npm package settings.

Docs publishing automation (Mintlify)

• Docs source lives in docs/.
• Deployment is intended to run via Mintlify GitHub integration from main.
• Target domain: agent-bridge-for-photoshop.jaredverdi.com.
• CI guard: .github/workflows/docs-validate.yml runs docs validation and broken-link checks.

Local docs check:

npm run docs:validate

Setup details:

• internal/docs-publishing-and-domain.md

MCP server (scaffold)

Run:

npm run mcp

It exposes tools:

• photoshop_capabilities
• photoshop_open_document
• photoshop_get_manifest
• photoshop_query_layers
• photoshop_apply_ops
• photoshop_render
• photoshop_checkpoint_restore
• photoshop_events_tail

UXP plugin scaffold

photoshop-uxp-bridge/ includes a minimal panel plugin with:

• globalThis.psagentBridge.health()
• globalThis.psagentBridge.applyOps(payload)
• globalThis.psagentBridge.connectBridge()
• globalThis.psagentBridge.disconnectBridge()

Implemented ops in plugin scaffold:

• Full document/layer/selection/text/shape/smart-object operation surface (see photoshop-uxp-bridge/README.md)
• batchPlay passthrough for raw Action Manager descriptors
• Agent-oriented controls in applyOps:
  • op-local refs (ref + $ref resolution)
  • per-op onError (abort or continue)
  • safety.rollbackOnError best-effort rollback
  • structured per-op results (opResults, failures, refs, rolledBack)
  • operation contract validation (envelope + per-op preflight checks before mutation handlers)
  • unified modal wrapper with retry + normalized Photoshop state errors

Integration tests:

• npm run test:integration runs CLI -> adapter -> mock bridge tests across the full planned operation list and validates success/outcome assertions.

Desktop flow:

1. Start daemon: npm run dev -- bridge daemon
2. Load local plugin in Photoshop UXP Dev Tool
3. Open Agent Bridge panel and click Connect Bridge
4. Run CLI commands (session start, layer list, op apply, etc.)

CLI desktop adapter always targets daemon /rpc, and daemon forwards to connected UXP client via /bridge/*.