Cursor Image Gen

Launch a headless Cursor Agent and save bitmaps to a user-chosen directory. Do not call $imagegen, image_gen, or the OpenAI Images API.

Skill path

export ZCODE_HOME="${ZCODE_HOME:-$HOME/.zcode}"
export CURSOR_IMG="$ZCODE_HOME/skills/cursor-image-gen/scripts/generate_with_cursor.mjs"

The wrapper needs network and write access to --output-dir. In a sandboxed ZCode task, request permission before running it.

Do not invoke PATH agent; that binary may be Grok. The wrapper resolves cursor-agent.

Routing

Intent	How to call
New image, no file	--prompt only (text2img)
Guide from one image	--reference FILE (img2img)
Several refs (style, face, layout)	repeat --reference; optional matching --reference-role
Edit an existing image	--mode edit and/or --keep / --change; edit target is the first --reference
Same prompt, several variants	--n N
Many different assets	--jobs jobs.json
Independent multi-image set	Launch one wrapper invocation per image concurrently; reuse verified references when applicable

Scheduling: sequential vs parallel

Decide automatically from the dependency graph instead of always using one mode:

• Generate one image at a time when there is only one requested asset, when each image depends on the previous result, or when the next prompt must be chosen after inspecting the previous output. This is the normal serial workflow.
• If a reference, identity, style, or layout image must be created first, generate and verify that reference serially. After it exists, launch independent downstream image jobs concurrently when they share the reference but do not depend on one another. Reusing the same local reference file across concurrent jobs is supported.
• For true parallel generation, use one generate_with_cursor.mjs invocation per output with a unique filename and start those invocations concurrently through the available execution tools. Do not put all independent jobs into one sequential loop.
• --jobs runs several assets through one Cursor Agent invocation, and --n makes several GenerateImage calls for one prompt. Both are batch mechanisms; neither should be described as guaranteed process-level parallelism. Use separate concurrent wrapper invocations when the user asks for simultaneous multi-image generation.
• Keep dependent edits, reference creation, inspection, and any retry that needs a prior result serial. After a parallel batch finishes, verify every returned file independently and report partial failures clearly.

Need exact pixels, a mask, true transparent PNG, seed, or ControlNet? Read references/limits.md, tell the user Cursor cannot do it, and stop. Do not silently switch to $imagegen.

Mode details and inner-prompt rules: references/modes.md.

Commands

Text to image:

node "$CURSOR_IMG" \
  --prompt "a paper-cut red panda, warm studio lighting" \
  --output-dir "/absolute/path/to/output" \
  --filename "red-panda.png" \
  --aspect-ratio 1:1

Image to image / edit:

node "$CURSOR_IMG" \
  --prompt "keep the subject, replace the background with a misty forest" \
  --output-dir "/absolute/path/to/output" \
  --filename "forest-edit.png" \
  --reference "/absolute/path/to/source.png" \
  --mode edit \
  --keep "subject, clothing, face" \
  --change "background only"

Multi-reference:

node "$CURSOR_IMG" \
  --prompt "same person as identity ref, composition matching the layout ref, white background turnaround" \
  --output-dir "/absolute/path/to/output" \
  --filename "character-turnaround.png" \
  --aspect-ratio 16:9 \
  --reference "/absolute/path/to/face.png" \
  --reference-role identity \
  --reference "/absolute/path/to/layout.png" \
  --reference-role composition

Batch:

node "$CURSOR_IMG" \
  --jobs "/absolute/path/to/jobs.json" \
  --output-dir "/absolute/path/to/output"

--aspect-ratio must be 1:1, 4:3, 3:4, 16:9, or 9:16. Optional: --transparent, --avoid "...", --n N, --overwrite (only with explicit user approval). The default Cursor model is cursor-grok-4.6-high; pass --model only when intentionally overriding it.

Verify

Treat exit code 0 and JSON ok: true as success. Return every absolute path in outputs. Inspect the files before telling the user they look right.

Setup only:

node "$CURSOR_IMG" --doctor
node "$CURSOR_IMG" --help

If --doctor reports logged_in: false, ask the user to run cursor-agent login (or set CURSOR_API_KEY). Do not fall back to $imagegen.