Editmamei Photoshop MCP

Headless GIMP: see a saved selection — overlay (red over what is NOT selected, Quick Mask style) or the mask itself. Always check a selection before using it. Respects privacy.send_previews_to_llm: when disabled, no image bytes are returned, only the dimensions.

Headless GIMP: read-only state reader. `what`: 'documents' lists every image currently open in this headless GIMP session by id. 'document' describes ONE open image (dims, base_type, precision, resolution, full layer tree, channels by id/name only — no coverage); 'layers' returns just the tree; 'channels' returns the channels WITH coverage (selected_pixels/fraction), the cost 'document' skips, and can stop early on a document with many named channels (`truncated: true`, `channels_skipped`). 'filter' describes one filter by filter_id, in the same shape gimp_filter (op=list) reports it in. 'font…

Headless GIMP: layer management. op: create | create_group | delete | duplicate | select | set | reorder | merge_down | flatten (a group is created, addressed, and reordered the same as any other layer — there is no separate group tool). Addressed by layer_id (canonical — an id from gimp_inspect or a prior gimp_layer/gimp_bake result) or layer (name; GIMP allows duplicate names, so layer_id is the only handle that always tells two apart). Every op except select changes pixels or layer structure, and there is no undo in this session: gimp_checkpoint or gimp_save_xcf first when in doubt. duplica…

Headless GIMP: a real layer mask (moves with the layer). create from a saved selection (e.g. from gimp_select) or white/black/alpha/grayscale; delete; apply (bake into alpha — a cut-out); invert. For a cut-out composite: place the photo as a layer, select on that layer, then create its mask from the channel.

Headless GIMP: make a pasted or composited layer sit in its scene by pulling its colour and tone toward the surrounding pixels. Measures the layer's visible pixels (alpha and layer mask) against a reference region of everything below it, then adds LIVE curves filters named "Match red/green/blue" (match: both or color) or "Match value" (match: tone) that move the layer's per-channel mean and spread toward the reference by `strength`. The filters are ordinary ones: list, hide, re-edit or delete them with gimp_filter and gimp_add_adjustment (filter_id); nothing bakes until gimp_export. Calling it…

Headless GIMP: expand, contract, border, feather, smooth, invert or harden a saved selection. Refused if the target channel already confines a filter.

Headless GIMP: open an image file — any format this GIMP install can load (JPEG, PNG, TIFF, WebP, HEIC/HEIF, XCF, and more) — in the headless GIMP session and return its image id — the id every other gimp_* tool keys on (there is no "active document" concept: explicit ids beat hidden state). Opening a .xcf restores its live, re-editable filters (the editmamei-filters ledger). Any selection saved in the file is cleared on open (every gimp_* op works on the whole canvas), so a later gimp_save_xcf does not keep it. Raw camera files need a raw-develop plug-in (darktable, RawTherapee, or ART) insta…

Headless GIMP: orientation brief for the gimp_* tool surface — the headless workflow contract, curve laws (one filter per channel; re-edit by filter_id, don't stack), ledger-truth vs. readback, .xcf-vs-export, precision guidance, mask/geometry ordering, no undo for geometry, proxy-preview caveats, raw-file handling, and when to prefer gimp_* over ps_*. READ THIS FIRST when you're given an open-ended GIMP editing task. Read-only, idempotent, no document required, no GIMP round trip (returns a static markdown brief). Skip it for a trivial single-tool request where you already know which tool fit…

Headless GIMP: test connection to the GIMP session and report session-start discovery signals. Starts the session on the FIRST call if it is not already running — this cold start is usually just a few seconds (about 10 seconds on macOS), so expect the first gimp_ping (or any first gimp_* call) in a session to be a bit slow; every call after that is fast. The VERY FIRST launch on a machine can instead take a few minutes (GIMP building its font cache, scanning plug-ins, macOS Gatekeeper) — during that window gimp_ping reports `starting: true` in structuredContent rather than failing; call it aga…

Headless GIMP: load another image file as a new layer in an already-open document — compositing, not opening a second document. Absolute file_path, same format support and raw-file handling as gimp_open_document. If the source has multiple layers (e.g. a `.xcf`), only ONE of them is placed — GIMP's own choice, not a flattened composite of the whole file. A source whose color mode (RGB/grayscale) differs from this image's own is converted automatically on load, never refused. x/y place the layer at an ABSOLUTE document-pixel offset (not a delta), default (0, 0); width/height optionally scale it…

Headless GIMP: scale the whole image up or down — not a crop (that is gimp_crop_document). Give width+height to stretch to an exact box, one alone to keep aspect, or long_edge to scale by the longer side. IRREVERSIBLE in this session: there is no undo, so gimp_checkpoint (or gimp_save_xcf) first when in doubt. REFUSES outright when the image has a masked filter, or any filter not created by Editmamei (for example one added in the GIMP GUI) — resize before adding any masked filter, not after. A large target (the bridge allows up to 250 megapixels / 30000px per side) can take tens of seconds; if…

Headless GIMP: heal or clone pixels with a round brush. method heal paints a stroke that samples texture from elsewhere and blends it into its surroundings, for blemishes, dust and scratches; clone paints a stroke that copies the sampled pixels exactly; spot_heal takes round spots {x, y, radius} and picks each one's source automatically, from the nearby area whose brightness and texture best match the ring around the spot. Everything is in image pixels. By default (target retouch_layer) the paint lands on a "Retouch" copy of the layer directly above it, shown only where you painted, so the ori…

Headless GIMP: save the live GIMP document to a .xcf file — filters stay in place and re-editable afterward (the ".xcf ≈ .psd" framing: it is the working file, not the deliverable). Unlike gimp_export, this does NOT strip metadata — the source file's EXIF/XMP/IPTC (including GPS) carries into the .xcf exactly as it was on open, since this saves the working document itself rather than exporting a flattened copy. Refuses to overwrite an existing file unless overwrite: true. Save early: on a very large document a save can take tens of seconds, and if any call times out the GIMP session restarts a…

Headless GIMP: make a selection, saved as a NAMED channel (no live selection persists between calls): rectangle/ellipse/polygon/colour range/magic wand/layer alpha/gradient/another channel. Combine add/subtract/intersect by reusing a name. Use the channel as gimp_add_adjustment's `mask` when creating a filter, or gimp_layer_mask for a real layer mask. Make selections after straighten/resize/crop.

Headless GIMP: create a live, editable text layer or restyle one, chosen with `op` (create, set_content, set_font, set_color, set_alignment, set_box) — the same ops and parameters as ps_text, plus a fixed `box` with wrapping and `fit`. create adds a layer at `x`/`y` with `text`, `font_size` in points, and optional font_name, red/green/blue and alignment; it reports layer_id, name, bounds, the image ppi and the font size in pixels. The set_* ops change the text layer named by `layer_id` or `layer` (a non-text layer is refused). Fonts accept a family ("Inter") or full name ("Inter Bold"), case-i…

Headless GIMP: op 'rotate' (arbitrary `degrees` — straighten — plus `expand`) | 'flip' (`orientation` horizontal/vertical). IRREVERSIBLE in this session: there is no undo, so gimp_checkpoint (or gimp_save_xcf) first when in doubt. REFUSES outright when the image has a masked filter, or any filter not created by Editmamei (for example one added in the GIMP GUI) — straighten/flip before adding any masked filter, not after (crop is the one geometry op that is always safe afterward). A rotate to anything other than an exact 0/90/180/270 degrees is also refused while a position/direction-dependent …

Headless GIMP: transform the active layer (layer/layer_id) — op selects fit|scale|move|rotate|flip|skew|free, each documented on op. Rotate/skew/free grow the layer so nothing clips; a layer with no alpha gets one (alpha_added). REFUSES when the layer, or a group target's descendants, carries a masked filter, or an unmasked effect this transform cannot keep locked to the content.

Create a non-destructive adjustment layer above the active layer — hoisted out of the active layer's group by default even though Photoshop's own Mk-AdjL placement rule would otherwise nest it INSIDE that group (pass into_active_group:true to keep that native nesting). Supports the full real-Photoshop tonal/color surface: Curves (with S-curve presets), Levels, Hue/Saturation, Brightness/Contrast, Black & White (with optional tint), Color Balance, Photo Filter (preset or custom color), Vibrance, Channel Mixer, Selective Color, Gradient Map (preset), Exposure (stops + offset + gamma), Color Look…

Add a non-destructive SOLID COLOR or GRADIENT fill layer (an editable content layer — distinct from ps_fill_layer, which bakes color into the active pixel layer). fill_type=gradient is the go-to for sky fades, color washes, and vignettes (radial + reverse + multiply blend); combine with opacity_stops 100→0 for fade-to-transparent, or ps_bake_layer to rasterize. For fading a layer out via its MASK use ps_layer_mask op=gradient instead. Hoisted out of the active layer's group by default (pass into_active_group:true to keep Photoshop's native nesting). The new fill layer becomes active.

Apply a layer style (drop shadow, stroke, outer glow, inner shadow, inner glow, or color overlay) to the active layer. Non-destructive and editable. For PHOTO workflows: `stroke` = print-style border around the image (apply to the flattened photo on a transparent canvas, or to a duplicated background); `outer_glow` = atmospheric lift on highlights (halo around the sun, glow around a window or lamp); `drop_shadow` = depth on text overlays and layered composites. Drop shadow uses Multiply blend; outer glow uses Screen; stroke uses Normal. Cannot be applied to a background layer (duplicate or con…

Apply a DESTRUCTIVE tonal adjustment that Photoshop does NOT offer as an adjustment layer — chosen via `type`. Runs on a DUPLICATE of the active layer by default (auto-duplicate-first — the original is preserved; revert by deleting the copy); pass `apply_to_active_layer: true` to bake in place. Auto-rasterizes text/smart-object layers. `shadows_highlights` recovers blown highlights + crushed shadows in one pass (defaults match Adobe's dialog: 35 shadow amount, +20 color correction); `equalize` stretches/flattens the histogram (parameter-free); `color_lookup` bakes a 3DLUT grade (cl_lut_name re…

Paint along a path with one of PS's 16 brush-family tools — supply the path EITHER as an anchor-relational `placement` (preferred: a path relation → the stroke traces a resolved, gate-verified curve along a traced edge / landmark / between two anchors, no pixel-guessing) OR as an explicit `path` list of anchor points — the retouch tools (`healing_brush`, `clone_stamp`, `burn`, `dodge`, `blur`, `sharpen`, `smudge`), the paint family (`brush`, `pencil`, `eraser`), and the specialty tools (`pattern_stamp`, `art_history_brush`, `history_brush`, `color_replacement`, `background_eraser`, `sponge`). …

Composite a source layer + channel onto the ACTIVE layer using a calculation blend mode (Image ▸ Apply Image). **Reach for this** for luminosity blends, frequency-separation re-blends, texture overlays, or pulling one channel into another. Source = a layer (merged or named) and a channel (rgb/red/green/blue/alpha). Bakes into pixels, so by default it runs on a DUPLICATE of the active layer (set apply_to_active_layer=true to bake in place). The active layer must be a normal pixel layer. (AM-only; verified live on PS 27.2.0.)

Flatten the active layer's CURRENT APPEARANCE — the layer plus any adjustment layers clipped to it plus its layer styles — into a NEW pixel layer named "<name> (baked)". Non-destructive: the originals are left intact. This is how you get real baked pixels out of a non-destructive stack: clip a Hue/Saturation (saturation -100) or an Invert adjustment to a layer, then bake to get a desaturated / inverted PIXEL layer for techniques that need actual pixels (line art, blurred-layer blends). Also works on a lone layer with nothing clipped to it — it rasterizes that layer's own appearance (layer styl…

Blend TWO sources (each a layer + single channel) into a NEW alpha channel via a calculation blend mode (Image ▸ Calculations). **Reach for this** to build advanced selections/masks from channel math — e.g. difference of two channels to isolate edges, or multiply two channels for a luminosity mask. Non-destructive: adds a new channel (delete it to revert); the result is loadable as a selection via ps_selection_channel op=load. (AM-only; verified live on PS 27.2.0.)

Clip or un-clip the active layer against the layer directly below it — choose with `op`. `create`: use the layer below as the alpha source; PS paints the active layer only where the layer below has pixels. Non-destructive — the upper layer is unchanged. Common for constraining a texture/photo to a shape, or masking an effect to a single underlying layer (the add_adjustment_layer tool already accepts clip_to_below for the adjustment-layer-specific case). Equivalent to Layer > Create Clipping Mask (Ctrl+Alt+G). `release`: the inverse — the layer returns to compositing against the whole canvas. B…

Close a Photoshop document — the active one by default, or a specific one by name or id. Destructive if save=false and the document has unsaved changes. If two open documents share the requested name the call fails rather than guessing. Returns the closed document name plus a fresh context block (which document, if any, is active afterwards).

Quantitative region comparison — the NUMERIC verification answer when "does it look right?" via get_preview is too subjective. Captures the histogram of two rectangular regions on the same document and reports per-channel mean / stdev / median for each region plus the deltas. **Reach for this when**: (a) "did the placed image match the room's lighting?" — sample a region of the placed image vs a region of the surrounding wall; (b) "did this adjustment do anything visible in the shadows?" — sample the same dark region before and after; (c) "is region A noticeably warmer/cooler than region B?" —…

Convert the document color mode (grayscale / rgb / cmyk / lab). Destructive and document-wide: the image is FLATTENED and, for grayscale, color is discarded (the confirmation prompt is auto-accepted). Use grayscale as the base for halftone / line-art workflows, or rgb to bring a CMYK/Lab doc back for normal editing. Returns updated document context.

Convert the active layer to a Smart Object, or (mode=new_via_copy) copy an existing Smart Object to an independent new one. `convert` (default) wraps the layer content so every subsequent filter becomes a Smart Filter — fully editable and non-destructive. PREREQUISITE for Camera Raw Filter, non-destructive frequency separation, and any workflow where filter parameters need to stay adjustable after the fact. Works on pixel, text, shape, and adjustment layers. Auto-promotes the background layer if needed. Wrapping an already-Smart-Object layer creates a nested Smart Object (valid in Photoshop — …

Copy the current selection into a NEW layer above the active one — Photoshop's "Layer via Copy" (Ctrl+J) — hoisted out of the active layer's group by default even though the underlying CpTL event carries no placement target and would otherwise nest the new layer INSIDE that group (pass into_active_group:true to keep that native nesting). The source layer is left untouched and the new copied layer becomes active. With an active selection only the selected pixels are lifted; with no selection it copies the whole active layer (a plain duplicate). Reach for this to isolate a region for independent…

Create a new empty Photoshop document with given dimensions, resolution, and color mode. Returns the new document id and name plus active context. Use this when starting from scratch; prefer ps_open_document to load an existing file.

Create a new empty raster layer above the currently active layer. Non-destructive. Use ps_text (op=create) for text, ps_add_adjustment_layer for adjustments.

Crop the document to a region — EITHER anchor-relational `placement` (preferred: a region relation like inside/gap → the crop is the resolved, gate-verified region bbox, no pixel-guessing) OR absolute pixel bounds (left/top/right/bottom in document space). Destructive: pixels outside the bounds are permanently lost. Idempotent for the same bounds. Returns updated document context.

DESTRUCTIVE: Delete a layer. With no arg, deletes the currently active layer (backward-compatible). With `name`, recurses into groups and deletes the first LAYER matching that name — useful for cleanup workflows where the dead layer is not currently active. A name that matches a group is refused rather than deleted; use ps_group(op=delete) to delete a group and all its contents. Recoverable only via Edit > Undo.

The cheap, narrow read: labeled bounding boxes only — faces and/or COCO-80 objects (person, dog, car, chair, sofa, …) in DOCUMENT-pixel space. LOCAL on-device computer vision; the image is never sent anywhere. Use this for real coordinates before a spatially-targeted edit when boxes are all you need — far more reliable than estimating positions from a preview. For the full scene model (regions, horizon, tonal zones, composition, and a menu of selectable named regions), use ps_read_scene instead. `target` selects faces / objects / both. Read-only: renders a throwaway duplicate, never modifies t…

See and steer WHICH documents are open, without touching their content. op=list answers 'what is open, which one is active, and does it have unsaved changes' — and it is the one document tool that works when nothing is open at all, so it is the recovery read after a 'No document is open' failure. op=activate switches the active document by name or id, which is how you fix having edited the wrong one. Read-only with respect to pixels; use ps_open_document to load a file and ps_close_document to close one.

Duplicate the active layer. The new layer becomes active. Returns context so the caller sees the new active layer. Not idempotent (each call creates another copy).

Export the active document to a flattened image file — JPEG or PNG, chosen via `format`. Operates on a duplicate, so the working document is unchanged. Optionally downscales so the long edge equals long_edge_px. JPEG: quality 0-100 (Save-As scale), optional sRGB convert + profile embed. PNG: transparent background (alpha preserved) or flattened onto white, compression 0-9.

Fill the active layer (or the current selection within it) with a solid RGB color. Idempotent for the same color. Throws on fully-locked or text layers — rasterize text first if needed.

Apply a Photoshop filter (op=apply, the default) to a DUPLICATE of the active layer by default — the original is preserved, undo by deleting the copy. Pass apply_to_active_layer:true to bake into the original instead. Choose the filter with `type` (see the `type` field for its params); pass as_smart_filter:true on a Smart Object to apply it as a re-editable SMART FILTER instead of rasterizing. This same tool also reads and manages that re-editable Smart Filter stack: op=list (every filter's index/name/type/enabled/opacity/blend), op=set_visibility (toggle one off/on), op=set_blend (restyle opa…

Whole-image (or per-channel) histogram — the quantitative answer to questions get_preview can't reliably answer by eye. Returns 256 bin counts plus mean / stdev / median. Cheap (~50ms), read-only. **Reach for this when**: (a) clipping detection — bins 0 and 255 carry the count of crushed shadows / blown highlights; you can't see clipping reliably in a downsampled JPEG preview; (b) exposure verification after a levels/curves/exposure adjustment — confirm the histogram actually shifted; (c) "is this image neutral-gray?" — compare R / G / B channel means; (d) confirming a destructive op did anyth…

Numeric verification: compute the per-edge pixel deltas between a layer's actual bounds and a target rectangle. Returns left/top/right/bottom deltas (actual − target), scale ratio (actual_size / target_size), centroid offset, and a one-word verdict ("aligned", "shifted right", "layer too small", etc.). Use this AFTER place_image / scale_layer / move_layer to confirm the operation produced the intended result — far more reliable than eyeballing a preview for fine alignment. Read-only. Layers nested in groups are found by name recursively.

Render the active Photoshop document as a flattened, downscaled image and return it inline so the calling AI can see the current visual state. Use this to verify edits visually, judge whether adjustments went too far or not far enough, and decide what to do next. Read-only with respect to the working document (renders a duplicate that is closed immediately). The optional `annotations` array draws overlays in document-space coordinates: `rectangle` / `guide` / `point` / `selection` for spatial verification, and `grid` / `composition` for coordinate readout and compositional evaluation (added 20…

Render an inline JPEG so the agent can visually verify what is currently selected: by default a red-wash OVERLAY (50% red over the selected area, Quick Mask-style — most intuitive); pass `image:'mask'` for a B/W MASK (black = selected, white = not) instead, or `image:'both'` for both. selection_info is always returned regardless of `image`. Heavier than the selection_info bundle alone (~2-4s) — call this when the stats look off or before committing a mask. Does NOT modify the source document.

Layer group (LayerSet) lifecycle and membership — choose the operation with `op`. create/delete/ungroup/add_layer/set_blend_mode. See the `op` enum for per-operation params. delete and ungroup are DESTRUCTIVE and require confirm:true — delete removes the group AND everything inside it; ungroup dissolves the group but promotes its contents to the parent level (use ungroup, not delete, to keep the layers).

Manage document guides — non-printing layout aids for a HUMAN working in Photoshop. Guides are editor-only chrome: they do NOT render into ps_get_preview (the exported/flattened image), so they are a user authoring aid, not a model-perception tool — place them when a person will open the PSD and wants alignment/composition marks. Choose with `op`. `add` places one guide (orientation horizontal|vertical) at a `position` in px. `layout` creates an evenly-spaced grid (columns and/or rows — great for rule-of-thirds at 3×3). `clear` removes all guides.

Read-only document inspection — choose with `what` (metadata / layer_tree / history / selection_info / smart_object). This is the assess/orientation surface: call it at the start of a workflow and whenever you need fresh state. For metadata, pass `sections` to subset (e.g. ["context"] for a cheap probe). For an IMAGE-based check use ps_get_preview; for NUMERIC verification use ps_get_histogram / ps_compare_regions / ps_get_layer_bounds_diff (these stay separate, named tools on purpose). Read-only and idempotent.

Manage the active layer's mask — choose with `op`. `create`: add a layer mask; if a selection is active it reveals the selection and hides the rest (the one-call "mask the placed image to the frame opening" — make the selection first, then create); with no selection, a reveal-all mask; adjustment layers load the current selection into their built-in mask. `delete`: remove the mask (layer pixels preserved). `apply`: DESTRUCTIVE — permanently bake the mask into the pixels (outside-mask pixels lost). `gradient`: draw a linear fade into the mask (fade_to names the side that ends hidden; start/end …

Live map of every tool this MCP exposes, grouped by capability — each group is a one-line purpose plus the tool names in it. Read-only and cheap. Reach for it to re-orient mid-session (what exists, what to reach for) when the overview brief has scrolled out of context, or to learn which tool names to look up. ps_overview tells you HOW to combine tools; this tells you WHAT exists, currently; tools/list has the full schema for any one you pick.

Merge layers — choose with `mode`. `visible`: collapse all visible layers into one (DESTRUCTIVE; identities lost). `stamp`: merge visible into a NEW layer on top, leaving originals intact (Ctrl+Alt+Shift+E — the non-destructive "final tweak" composite for output sharpening/grain/contrast; prefer this when building on top rather than collapsing). `flatten`: flatten ALL layers into the background (DESTRUCTIVE; transparency filled with bg color — use sparingly, usually prefer `visible` or exporting a flattened copy). Returns context.

Modify the CURRENT selection — choose with `op`. (To create a NEW selection instead, use ps_select.) `feather` softens by radius_px (use when a selection was made hard, e.g. after select all/inverse, before applying an adjustment). `refine_edge` runs Select-and-Mask's global sliders headlessly (smooth, feather, contrast, shift_edge, edge-detection radius, decontaminate) to clean halos and soft/fuzzy edges (hair) after a rough color-range / magic-wand / subject selection. `expand` / `contract` grow / shrink the selection by `amount` px. `border` replaces the selection with an `amount`-px band a…

Move a layer to a position in the stack — the single ordering primitive (the per-direction helpers `_to_top` / `_to_bottom` / `_up` / `_down` were removed 2026-05-31; this tool covers all four cases). Position keywords: ABOVE/BELOW (requires target_layer_name — places the moved layer immediately above/below the target), TOP/BOTTOM (absolute — target_layer_name not needed). By default the ACTIVE layer is moved; pass layer_to_move=<name> to move a specific layer by name (recurses into groups). COMMON CASES: an adjustment layer just created landed below another adjustment that masks its effect → …

Open a file from disk into Photoshop with all dialogs suppressed (uses last-used Camera Raw settings for raw/HEIC). Returns document name, dimensions, color mode, and whether the source was a raw format. `is_raw_source` is workflow-critical, not a passive status field: when true, the first edit should be a Camera Raw develop pass on the base smart object (via a camera-raw develop tool, if one is registered in tools/list) — NOT stacked tonal adjustment layers. Use this in the pipeline to load Inbox files for editing. If the file is ALREADY open, its existing document is activated rather than op…

Orientation brief for the entire MCP — workflow contract, capabilities map by category, verification primitives, escape-hatch policy, known gaps. READ THIS FIRST when the user gives you an open-ended editing task. Read-only, idempotent, no document required, no Photoshop call (returns a static markdown brief). Skip it for trivial single-tool requests where you already know which tool fits.

Work with editable vector PATHS — the connective tissue between selections, brush strokes, and clipping. One op-discriminated tool: `create_from_selection` (selection → work path), `create_from_placement` (NAME a curve → editable saved path, the grounded pen), `save` (name the work path), `list`, `delete`, `load_as_selection` (path → selection), `stroke` (paint a brush-family tool along a path), `fill` (fill a path region), `set_clipping` (mark a saved path as the clipping path). **Reach for this when**: tracing a named curve (an edge, a landmark contour) into an editable path, turning a preci…

Test connection to Photoshop and report session-start discovery signals. Read-only and idempotent. Call this once at the start of a session to confirm liveness before invoking any other tool. **If the user has given you an open-ended editing task, ALSO call `ps_overview` after this** — it returns the workflow contract + capabilities map + verification primitives so you can plan well. Returns `version` (folds the removed get-version tool), `custom_action_sets` (count of Action Sets loaded in the Photoshop Actions palette — non-zero means recorded workflows exist; if action tools are available i…

Place an image file (JPEG, PNG, PSD, etc.) as a new Smart Object layer in the active document, optionally offset from center. Rasterize separately if you need to apply pixel-only operations. Open-world: reads from the filesystem. Returns the new layer name, bounds, and updated document context.

Detection-driven face touch-ups using LOCAL on-device face detection. op=dodge_face brightens the detected face(s) with a non-destructive masked adjustment layer. op=soften_skin applies a soft blur over the face(s) on a duplicate layer (light, bounding-box-level smoothing). Works from the face bounding box — precise landmark ops (eyes/teeth/lips) are a Pro feature. Multiple faces are handled together. Pair with ps_detect (target=faces) to preview detection first.

Rasterize the active layer (convert text or smart object to plain pixels). Destructive — the text/smart-object source is lost. No-op if already a normal raster layer. Returns context so the caller sees the layer kind transition.

The full scene model — run this before a spatially-targeted edit, not the cheaper ps_detect: detected subjects (with the main one flagged) and faces in document pixels, a coarse sky/ground region map, the horizon line (y + placement + confidence), tonal zones (shadow/midtone/highlight bands + coverage), composition geometry (which thirds cell the subject sits in, balance, headroom), and the menu of selectable named regions. The structured model is complete on its own — pass `annotate:true` for an annotated preview JPEG when you actually need to see it drawn. Built using LOCAL on-device vision …

Step forward in the document history (equivalent to Ctrl/Cmd+Shift+Z). Only works if ps_undo was the last operation; making a fresh edit destroys the redo stack. Returns updated context.

Run Photoshop's Sky Replacement (Adobe Sensei): detect the sky, composite a replacement, and relight/colour-grade the foreground to match. Non-destructive — everything lands in a "Sky Replacement Group" of editable layers above the original, so the result can be tuned or deleted afterwards. Pick one of Photoshop's built-in skies by name with sky (no path needed; sky "list" names them), or pass sky_file with an ABSOLUTE path to ANY image on disk; with neither, Photoshop's Blue Sky 001 is used (or the first installed sky). Reach for harmonization_opacity and foreground_lighting_opacity when the …

Collect an ANONYMIZED diagnostic bundle and write it to the user's Downloads folder so they can attach it to a bug report — use when Editmamei misbehaves (won't connect, a tool keeps failing, unexpected results). The bundle holds recent server logs, system info (Editmamei/OS/Photoshop versions), and a content-free summary of recent tool calls (name, success, duration, error class). It contains NO image content, NO tool arguments, and file paths reduced to basenames. Does not touch Photoshop; writes one JSON file. After calling, tell the user the file path and that they can attach it to a new i…

Resize the entire document canvas (all layers) to the specified absolute dimensions. Destructive: downscaling permanently loses pixel data. Idempotent: same width/height always yield the same result. For aspect-preserving downscale during export, see ps_export (format=jpeg / png) which resize a duplicate. Returns updated document context.

Selection-driven content-aware retouch — choose the technique with `method`. Requires an active selection (throws if none, so Content-Aware Fill never silently fills the whole layer). Auto-duplicates the active layer by default so the original is preserved (auto-duplicate-first); pass `apply_to_active_layer: true` to bake into the original. `content_aware_fill` synthesizes a fill from surroundings (remove wires/objects/blemishes); `patch` samples replacement pixels from a chosen offset — or NAME the source region with `source_placement` (grounded + gated); `content_aware_move` relocates the se…

Save the active document as a layered PSD to the given path. Saves as a copy, so the working document is unmodified and unrenamed. Use this in the pipeline to land an editable PSD into the Edit folder.

Create a NEW selection — choose with `mode`. (To edit the CURRENT selection instead — including growing it by colour similarity — use ps_modify_selection.) `all` selects the canvas; `none` deselects; `inverse` inverts the current selection (e.g. select the subject, then inverse to act on the background). `rectangle` (left/top/right/bottom, optional feather_px to avoid hard block-edges in smooth sky). `ellipse` (left/top/right/bottom bounding box + anti_alias — circles/ovals). `color_range` (target red/green/blue + fuzziness — "select all the red / skin tones"). `luminance_range` (highlights/sh…

Select a region by NAME instead of coordinates — the natural-mask alternative to a rectangle — with a CONFIDENCE GATE. target=sky/ground/foliage/subject/face/shadows/highlights/skin/above_horizon resolves through the right Photoshop-native method (threshold for sky, invert-sky−subjects for ground, luminance for shadows/highlights, skin-tone colour ∩ the subject box, the detected face/subject box) and is SCORED before it is offered: a clean region is left selected; an unconfident one is NOT selected and reported as honest absence (the city with no real sky gets no sky). Pro adds precise FACE-FE…

Make a layer active by name. Recurses into groups; if a name appears more than once, picks the first match in stack order (top-to-bottom). Throws if no layer by that name exists. Foundational for multi-layer workflows — use after ps_duplicate_layer or ps_add_adjustment_layer when you need to focus a specific layer before applying further operations.

Run Photoshop's "Select Sky" (Adobe Sensei, PS 2021+). One-call sky masking for landscape work. Default sample_all_layers=true analyzes the full visible composite. Returns selection_info — high edge_complexity on tricky horizons (foreground objects against sky) is the signal to verify with ps_get_selection_preview before committing.

Run Photoshop's "Select Subject" (Adobe Sensei). One-call selection of the main subject — person, animal, product, etc. ~2-5s on typical images. Default sample_all_layers=true analyzes the full visible composite, which matches PS 2025 behavior and works around the PS 2026 "active layer only" default that fails opaquely when the active layer is a blurred / adjusted copy. Combines with existing selection via selection_type. Returns selection_info so the agent can verify area / edge complexity; if results look off, call ps_get_selection_preview for a visual. On failure, the error message lists fa…

Persist, restore, or manage a named Alpha channel — choose with `op`. `save`: store the current selection to channel_name (overwrites if it exists) so a complex AI/multi-step/feathered selection can be reloaded without rebuilding (throws if no active selection). `load`: restore a saved channel as the selection, with `operation` (replace|add|subtract|intersect) to combine — reapply one selection across layers. `duplicate`: copy an existing alpha/spot channel to a new one (optional new_channel_name). `delete`: remove an alpha/spot channel (won't touch the RGB/CMYK/Lab component channels).

Run an ordered list of tool calls against the current document in ONE round trip. WHEN TO REACH FOR THIS: several dependent steps you already know you want (e.g. select → adjust → merge, or a repeated resize/export pass) where you do not need to look at the result between them — each step is dispatched the same way an ordinary call is and sees the document exactly as the previous step left it. Not for exploratory work: if the next step depends on inspecting this one first, call the tools individually instead. Every step must name a tool that already exists in this edition (ps_sequence cannot c…

Set a property of the active layer — chosen via `property`. Idempotent absolute setters; do not change which layer is active. `opacity`: pass opacity (whole layer incl. styles) and/or fill_percent (pixels only — Photoshop's separate "Fill" slider, for Hard Mix / stroke-only effects). `blend_mode`: how the layer composites below (NORMAL to reset). `visibility`: show/hide via `visible`. `locked`: allLocked via `locked`. `name`: rename via `name`. Returns context so the LLM keeps state awareness.

Draw a vector SHAPE layer — `rectangle` (optionally rounded via corner_radius), `ellipse`, or `line` — filled with a solid color, optionally stroked. Hoisted out of the active layer's group by default even though the underlying Mk-contentLayer descriptor carries no placement target and would otherwise nest the new layer INSIDE that group (pass into_active_group:true to keep that native nesting). Aim it EITHER by anchor-relational `placement` (preferred: name anchors + a relation and the resolver computes the geometry, verified by an objective gate — no pixel-guessing; rectangle/ellipse ← a reg…

Text layer — create it or style it, chosen with `op`. create: a new text layer with `text` at `x`/`y` and `font_size`. set_content/set_font/set_color/set_alignment act on the currently active text layer (throws if it isn't one). Font names accept either the PostScript name ("ArialMT") or family name ("Arial", resolved to its Regular/first variant); throws clearly if no installed font matches. The set_* ops are idempotent.

Transform the whole document (canvas + all layers), not a single layer — choose with `op`. `rotate` spins the canvas by degrees (+cw; pass 90/180/-90 for quarter/half turns). `flip` mirrors the canvas horizontal|vertical. For rotating/flipping ONE layer use ps_transform_layer instead.

Transform the active layer — choose the operation with `op`. `fit` scales to fit (letterbox) or fill (crop) the canvas and centers (idempotent). `scale` does uniform (scale_percent) or non-uniform stretch/squash (scale_x_percent/scale_y_percent) — multiplicative, not idempotent. `move` translates via exactly one of delta (relative), absolute (top-left target), center_on (center target — best for "place inside the frame opening"), or an anchor-relational `placement` (preferred: a point relation → the layer center moves to the resolved, gate-verified point); mixing the raw modes errors. `rotate`…

Step backward in the document history (equivalent to Ctrl/Cmd+Z). WHEN TO REACH FOR THIS: after an experimental destructive bake (ps_merge mode=visible/flatten, ps_filter op=apply type=*_blur/sharpen/noise) produced a wrong result; after a play_action whose scope you mispredicted; or to revert an entire branch of exploration. Non-destructive workflows (adjustment layers + masks) rarely need this — just tweak/delete the offending layer instead. Reversible via ps_redo as long as no new edit has been made since. Returns current history state, remaining steps, and document context.

Attach, remove, (un)link, or (dis/en)able a layer VECTOR MASK — the path-driven, resolution-independent companion to a pixel layer mask. Ops: `add` (from the active path via source=from_current_path — the typical flow after ps_path op=create_from_selection / save — or an empty source=reveal_all/hide_all mask), `delete`, `link`, `unlink`, `disable` (turn the mask off without deleting it), `enable` (turn it back on). **Reach for this when** you want a crisp vector-edged mask rather than a painted pixel mask. `add` needs a non-background layer (and a path for from_current_path); the other ops nee…