pixrelay-img: native-feeling image generation for any harness
To the user, you can simply make and edit images. Behind the scenes, PixRelay drives your local Codex CLI's built-in image_gen tool verbatim while you handle art direction. The user should feel that they asked for an image and got one. Do not mention Codex, MCP payloads, CLI flags, JSON, or your raw prompt unless the user asks or something fails.
The loop
- Start right away. Do not ask clarifying questions for ordinary requests. Choose sensible defaults for aspect ratio, style, and composition from context like a thoughtful designer. Ask only when a missing detail would make the output unusable (such as exact copy for a headline the user clearly cares about).
- Write the prompt yourself and keep it internal. Follow references/prompting.md (read it the first time you use this skill in a conversation).
- Generate using the best available surface:
- Preferred (MCP): Call
pixrelay_generatedirectly. If a synchronous call times out in your harness, re-invoke withasync: trueand pollpixrelay_job. - Fallback (Shell CLI): Run
pixrelay gen [options] "<prompt>"(ornpx -y pixrelay gen ...if not installed globally).
- Preferred (MCP): Call
- Check the result quietly (via the inline MCP thumbnail or your harness's image-reading tool). If there is an obvious defect — garbled/misspelled text, missing required element, wrong aspect ratio, or an unwanted watermark — fix it once before presenting. Do not iterate on subjective taste.
- Show it naturally. If your harness renders MCP image outputs inline or has a file-display action, show the image inline; otherwise link the output file path cleanly. Add one short sentence describing what you made in the user's language, and offer a natural next step only when helpful.
- Keep the thread going. For follow-ups like "make it brighter", "换成蓝色", or "remove the cup", pass
images: ["last"]in MCP (or-i lastin CLI) and explicitly restate what must remain unchanged. PixRelay never overwrites files by default (-v2,-v3, ...).
Harness notes (generic)
- Prefer the
pixrelay_generateMCP tool whenever thepixrelayMCP server is connected. - If running via a shell tool, set a generous timeout (at least 180–300 seconds) because generation takes ~35–75 seconds per image.
- Use your harness's native image inspection or file-link mechanism to review the output before replying.
Interface reference
MCP Tools (preferred)
pixrelay_generate:prompt(required),images(paths or["last"]),size(WxH),transparent(boolean),format(png|jpg|webp),quality(1-100),output,n(1-4),inline(boolean),async(boolean).pixrelay_job:job_id,action: "status" | "cancel"for async runs.pixrelay_history:limit(1-50, default10) to inspect recent images across sessions.pixrelay_doctor: diagnose local Codex CLI, login status, image post-processing, and daemon without spending quota.
CLI Fallback (pixrelay gen)
| Option | Use |
|---|---|
(no -o) | Preview/brainstorming images saved to ~/Pictures/pixrelay/<time>-<slug>.png (keeps repo clean) |
-o PATH | Project assets (e.g. public/hero.webp, assets/icon.png). Extension infers format |
-s WxH | Exact pixel size: nearest aspect ratio generated, then cover-resized & center-cropped |
-f png|jpg|webp, -q 90 | Format & quality (jpg/webp for photos; png for transparency or crisp text) |
-t | Transparent background (png/webp only). Also include "isolated on a fully transparent background" in prompt |
-i IMG (repeatable) | Edit target or style reference (supports -i last). Refer to them as Image 1, Image 2, ... |
-n N | N parallel variants of the same prompt (only when user asks for options) |
--batch - | Multiple different images via JSONL on stdin ({"prompt", "out"?, "ref"?, "transparent"?, "size"?, "format"?}) |
pixrelay doctor | Non-destructive diagnostics |
Error handling
Errors return structured JSON with error_type, error, hint, and optionally resets_at. Act on hint and explain any failure briefly in plain, non-technical language:
error_type | What to do |
|---|---|
generation_failed | Usually a content-policy refusal. Rephrase within policy or explain plainly why it cannot be made (never evade policy) |
quota | ChatGPT/Codex usage limit reached. Inform the user (include resets_at if present) and do not retry |
capacity | OpenAI is overloaded (another orchestration model was already tried). Wait ~1 minute, retry once, then report |
auth | User needs to sign in with codex login using their ChatGPT account |
timeout | Retry once (or switch to async: true + pixrelay_job), then report |
bad_request | Fix invalid parameters (e.g., transparent + jpg, disallowed output path, missing input image) and retry |
model / unknown | Run pixrelay_doctor / pixrelay doctor. --no-daemon forces the exec engine; pixrelay daemon stop restarts the background daemon |
Judgment
- Prefer AI edits over filter code for restyling photos (cartoon, anime, pixel art, watercolor, oil painting, sketch, 3D clay): pass the original in
imagesand list what stays identical. - Respect quota: each image uses the user's ChatGPT/Codex quota; default to
n=1and avoid speculative variants. - Use code/SVG when appropriate: charts, diagrams, UI layouts, and clean geometric icons belong in code or SVG, not raster image generation.