Skip to content
Back to search

PixRelay

PixRelay (借笔): Let any AI agent harness generate and edit images via your local Codex CLI (ChatGPT account) — no OPENAI_API_KEY required. MCP + CLI + Agent Skills.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gnipbao--pixrelay/badge.svg)](/listings/gnipbao--pixrelay)

HTML

<a href="/listings/gnipbao--pixrelay"><img src="/api/listings/gnipbao--pixrelay/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Check your environment (no quota spent)

npx -y pixrelay doctor

2. Install into your harness(es)

Preview changes first with `--dry-run`:

npx -y pixrelay install --harness auto --scope user --dry-run

Apply (safely merges existing JSON configs and creates `.bak` backups):

# Auto-detect installed harnesses
npx -y pixrelay install --harness auto --scope user

# Or target a specific harness
npx -y pixrelay install --harness antigravity --scope user
npx -y pixrelay install --harness claude-code --scope user
npx -y pixrelay install --harness cursor --scope project

3. Supported Harnesses

| Harness | Primary Surface | Guide | | --- | --- | --- | | **Claude Code** | MCP + Skill / Plugin | [docs/harnesses/claude-code.md](./docs/harnesses/claude-code.md) | | **Google Antigravity** | MCP + Skill | [docs/harnesses/antigravity.md](./docs/harnesses/antigravity.md) | | **Cursor** | MCP + `.cursor/rules/` | [docs/harnesses/cursor.md](./docs/harnesses/cursor.md) | | **Gemini CLI** | MCP (600s timeout) + Skill | [docs/harnesses/gemini-cli.md](./docs/harnesses/gemini-cli.md) | | **OpenCode** | MCP + Skill | [docs/harnesses/opencode.md](./docs/harnesses/opencode.md) | | **Windsurf** | MCP + Rules | [docs/harnesses/windsurf.md](./docs/harnesses/windsurf.md) | | **VS Code (Copilot Agent)** | MCP (`.vscode/mcp.json`) | [docs/harnesses/vscode.md](./docs/harnesses/vscode.md) | | **Cline / Roo Code** | MCP (300s timeout) + Rules | [docs/harnesses/cline.md](./docs/harnesses/cline.md) |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 176 lines
  1. # PixRelay 「借笔」
  2. > Let **any** AI agent harness — Google Antigravity, Claude Code, Cursor, Gemini CLI, OpenCode, Windsurf, VS Code Copilot Agent, Cline/Roo — generate and edit images via your local signed-in **Codex CLI** (ChatGPT subscription). **No `OPENAI_API_KEY` required.**
  3. [中文文档 (README.zh-CN.md)](./README.zh-CN.md) · [Compatibility Matrix](./docs/compat-matrix.md) · [Harness Guides](./docs/harnesses/)
  4. ---
  5. ## Live Output Example (Generate → `-i last` Edit)
  6. | Step 1: Generate (`512x512`) | Step 2: Follow-up edit (`images: ["last"]` / `-i last`) |
  7. | :---: | :---: |
  8. | <img src="./docs/images/demo-before.webp" width="280" alt="Generated orange cat holding a fountain pen" /> | <img src="./docs/images/demo-after.webp" width="280" alt="Edited night sky and warm desk lamp version" /> |
  9. | *"Minimal flat studio illustration of an orange tabby cat holding a fountain pen"* (24.6 s via warm daemon) | *"Change the background to a twilight indigo night sky with golden stars and warm desk lamp glow"* (27.7 s via `-i last`) |
  10. ---
  11. ## Why PixRelay?
  12. [c2c_img](https://github.com/actionow-ai/c2c_img) proved that a local signed-in Codex CLI can act as a fast, headless `image_gen` backend using your existing ChatGPT login. **PixRelay** ("借笔" — *borrowing the brush*) rebuilds that engine in TypeScript and opens it up to **every** harness:
  13. - **One Engine, Three Surfaces:** **MCP Server** (universal, zero shell-approval friction), **CLI** (JSON contract compatible with shell workflows), and **Agent Skills / Rules** (art direction & interaction conventions).
  14. - **One Shared Warm Daemon:** Multiple harnesses and MCP servers share a single background `codex app-server` over a `0600` Unix domain socket / Windows named pipe with random-token auth, a concurrency queue (default `3`), idle auto-exit (`15m`), and automatic binary-upgrade replacement.
  15. - **Dual-Engine Resilience:** Falls back automatically to lean `codex exec --ephemeral` (with 17 non-image tools disabled and PNG `IEND` early-stop) whenever the daemon cannot serve a request.
  16. - **Cross-Session Edit Continuity:** Records `history.jsonl` so any harness can pass `images: ["last"]` (or `-i last`) for follow-up edits ("make it brighter", "swap the background") without tracking paths manually.
  17. - **Timeout-Proof MCP:** Emits `notifications/progress` heartbeats during synchronous renders, supports `async: true` + `pixrelay_job` polling/cancellation, and writes extended timeouts where harnesses support them.
  18. - **Native Inline Previews:** Returns resized inline thumbnails (`≤ 1024px`, `≤ 1 MB`), JSON metadata, `file://` `resource_link`, and `structuredContent` in every MCP tool result.
  19. ## Architecture
  20. ```mermaid
  21. flowchart LR
  22. subgraph H["Agent Harnesses"]
  23. CC["Claude Code"]
  24. AG["Antigravity"]
  25. CU["Cursor / Windsurf / VS Code"]
  26. GE["Gemini CLI / OpenCode / Cline"]
  27. end
  28. subgraph P["PixRelay"]
  29. MCP["pixrelay mcp<br/>stdio (one per harness)"]
  30. CLI["pixrelay CLI<br/>gen / doctor / install / daemon"]
  31. SK["Skill & Rules<br/>pixrelay-img"]
  32. D["pixrelay daemon<br/>Unix socket / pipe + token<br/>queue + concurrency cap + history"]
  33. EX["exec engine<br/>codex exec --ephemeral"]
  34. PP["Post-processing<br/>aspect / crop / format / thumbnail"]
  35. end
  36. CC -->|MCP or Skill+CLI| MCP
  37. AG -->|MCP + Skill| MCP
  38. CU -->|MCP + Rules| MCP
  39. GE -->|MCP + Skill| MCP
  40. SK -.shell fallback.-> CLI
  41. MCP -->|socket + token| D
  42. CLI -->|socket + token| D
  43. D -->|JSON-RPC stdio| AS["codex app-server<br/>warm shared process"]
  44. D -.automatic fallback.-> EX
  45. AS --> PP
  46. EX --> PP
  47. PP --> OUT[("Output Dir<br/>+ history.jsonl")]
  48. ```
  49. ## Prerequisites
  50. 1. **Node.js ≥ 18**
  51. 2. **Codex CLI** signed in with your ChatGPT account:
  52. - Bundled automatically with the ChatGPT desktop app on macOS, or install via `npm i -g @openai/codex`
  53. - Sign in once: `codex login`
  54. ## Quick Start
  55. ### 1. Check your environment (no quota spent)
  56. ```bash
  57. npx -y pixrelay doctor
  58. ```
  59. ### 2. Install into your harness(es)
  60. Preview changes first with `--dry-run`:
  61. ```bash
  62. npx -y pixrelay install --harness auto --scope user --dry-run
  63. ```
  64. Apply (safely merges existing JSON configs and creates `.bak` backups):
  65. ```bash
  66. # Auto-detect installed harnesses
  67. npx -y pixrelay install --harness auto --scope user
  68. # Or target a specific harness
  69. npx -y pixrelay install --harness antigravity --scope user
  70. npx -y pixrelay install --harness claude-code --scope user
  71. npx -y pixrelay install --harness cursor --scope project
  72. ```
  73. ### 3. Supported Harnesses
  74. | Harness | Primary Surface | Guide |
  75. | --- | --- | --- |
  76. | **Claude Code** | MCP + Skill / Plugin | [docs/harnesses/claude-code.md](./docs/harnesses/claude-code.md) |
  77. | **Google Antigravity** | MCP + Skill | [docs/harnesses/antigravity.md](./docs/harnesses/antigravity.md) |
  78. | **Cursor** | MCP + `.cursor/rules/` | [docs/harnesses/cursor.md](./docs/harnesses/cursor.md) |
  79. | **Gemini CLI** | MCP (600s timeout) + Skill | [docs/harnesses/gemini-cli.md](./docs/harnesses/gemini-cli.md) |
  80. | **OpenCode** | MCP + Skill | [docs/harnesses/opencode.md](./docs/harnesses/opencode.md) |
  81. | **Windsurf** | MCP + Rules | [docs/harnesses/windsurf.md](./docs/harnesses/windsurf.md) |
  82. | **VS Code (Copilot Agent)** | MCP (`.vscode/mcp.json`) | [docs/harnesses/vscode.md](./docs/harnesses/vscode.md) |
  83. | **Cline / Roo Code** | MCP (300s timeout) + Rules | [docs/harnesses/cline.md](./docs/harnesses/cline.md) |
  84. ## MCP Surface (`pixrelay mcp`)
  85. ### Tools
  86. | Tool | Purpose | Key Parameters |
  87. | --- | --- | --- |
  88. | `pixrelay_generate` | Text-to-image, image-to-image, editing | `prompt`, `images` (supports `"last"`), `size` (`WxH`), `transparent`, `format` (`png\|jpg\|webp`), `quality`, `output`, `n` (`1–4`), `inline`, `async` |
  89. | `pixrelay_job` | Poll or cancel an async job | `job_id`, `action` (`"status" \| "cancel"`) |
  90. | `pixrelay_history` | List recent generated images | `limit` (`1–50`, default `10`) |
  91. | `pixrelay_doctor` | Non-destructive diagnostics | *(none)* |
  92. ### Prompts
  93. - `pixrelay_art_direction`: Full structured prompting recipes, aspect-ratio defaults, and edit continuity guidelines.
  94. ## CLI Surface (`pixrelay`)
  95. ```bash
  96. # Generate a preview image (saved to ~/Pictures/pixrelay/)
  97. pixrelay gen "Minimal flat editorial illustration of a ginger cat holding a fountain pen, warm cream backdrop, no text"
  98. # Exact pixel asset (OG card 1200x630 WebP)
  99. pixrelay gen -o public/og.webp -s 1200x630 -q 85 "Clean geometric developer tool banner..."
  100. # Transparent sticker
  101. pixrelay gen -t -o assets/mascot.png "Cute ceramic cat sticker, thick white die-cut border, isolated on a fully transparent background"
  102. # Edit the most recently generated image
  103. pixrelay gen -i last -o assets/mascot-warm.png "Edit Image 1: shift lighting to warm golden hour; keep pose, outline, and expression identical."
  104. # Parallel JSONL batch from stdin
  105. printf '{"prompt":"Warm coffee mug icon","out":"a.png"}\n{"prompt":"Cool tea cup icon","out":"b.png"}\n' | pixrelay gen --batch -
  106. # Daemon & protocol diagnostics
  107. pixrelay daemon status
  108. pixrelay daemon stop
  109. pixrelay history --limit 10
  110. pixrelay schema-check
  111. ```
  112. ## Security & Safe Defaults
  113. - **Local, single-user only:** The daemon listens exclusively on a `0600` Unix domain socket (macOS/Linux) or local Windows named pipe with constant-time random token authentication. There is no network/remote listener.
  114. - **Sandboxed Codex runs:** Every generation runs inside an empty temporary working directory with `sandbox: read-only`, `approvalPolicy: never`, and `shell_tool` / browser / plugin tools disabled.
  115. - **MCP output path allowlist:** In MCP mode, output files are restricted to your active workspace and `~/Pictures/pixrelay` by default (preventing path-traversal writes). Add extra directories via `PIXRELAY_ALLOWED_DIRS` or `~/.config/pixrelay/config.json`.
  116. - **Input image header verification:** Reference images are checked for both allowed extensions and valid magic bytes (PNG/JPEG/WebP/GIF) so non-image files cannot be exfiltrated via `localImage`.
  117. ## Development & Testing
  118. All unit, end-to-end engine/daemon, and MCP contract tests run offline against `tests/fake-codex/fake-codex.mjs` without needing a Codex login or spending quota:
  119. ```bash
  120. npm install
  121. npm run typecheck
  122. npm run build
  123. npm test
  124. ```
  125. ## Disclaimer & Attribution
  126. - **Not affiliated with OpenAI:** PixRelay is an independent open-source project powered by your locally installed Codex CLI. You are responsible for complying with OpenAI's Terms of Use; do not use PixRelay to expose a shared service or share accounts.
  127. - **Built on the shoulders of [c2c_img](https://github.com/actionow-ai/c2c_img):** PixRelay's Codex driver prompt, dual-engine architecture, error classification taxonomy, early-stop strategy, and prompting guidelines are adapted from `actionow-ai/c2c_img` (MIT License, Copyright © 2026 actionow). See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
  128. ## License
  129. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.