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
Markdown
[](/listings/gnipbao--pixrelay)HTML
<a href="/listings/gnipbao--pixrelay"><img src="/api/listings/gnipbao--pixrelay/badge.svg" alt="findsafeskills safety rating" /></a>Install
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
- # PixRelay 「借笔」
- > 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.**
- [中文文档 (README.zh-CN.md)](./README.zh-CN.md) · [Compatibility Matrix](./docs/compat-matrix.md) · [Harness Guides](./docs/harnesses/)
- ---
- ## Live Output Example (Generate → `-i last` Edit)
- | Step 1: Generate (`512x512`) | Step 2: Follow-up edit (`images: ["last"]` / `-i last`) |
- | :---: | :---: |
- | <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" /> |
- | *"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`) |
- ---
- ## Why PixRelay?
- [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:
- - **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).
- - **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.
- - **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.
- - **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.
- - **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.
- - **Native Inline Previews:** Returns resized inline thumbnails (`≤ 1024px`, `≤ 1 MB`), JSON metadata, `file://` `resource_link`, and `structuredContent` in every MCP tool result.
- ## Architecture
- ```mermaid
- flowchart LR
- subgraph H["Agent Harnesses"]
- CC["Claude Code"]
- AG["Antigravity"]
- CU["Cursor / Windsurf / VS Code"]
- GE["Gemini CLI / OpenCode / Cline"]
- end
- subgraph P["PixRelay"]
- MCP["pixrelay mcp<br/>stdio (one per harness)"]
- CLI["pixrelay CLI<br/>gen / doctor / install / daemon"]
- SK["Skill & Rules<br/>pixrelay-img"]
- D["pixrelay daemon<br/>Unix socket / pipe + token<br/>queue + concurrency cap + history"]
- EX["exec engine<br/>codex exec --ephemeral"]
- PP["Post-processing<br/>aspect / crop / format / thumbnail"]
- end
- CC -->|MCP or Skill+CLI| MCP
- AG -->|MCP + Skill| MCP
- CU -->|MCP + Rules| MCP
- GE -->|MCP + Skill| MCP
- SK -.shell fallback.-> CLI
- MCP -->|socket + token| D
- CLI -->|socket + token| D
- D -->|JSON-RPC stdio| AS["codex app-server<br/>warm shared process"]
- D -.automatic fallback.-> EX
- AS --> PP
- EX --> PP
- PP --> OUT[("Output Dir<br/>+ history.jsonl")]
- ```
- ## Prerequisites
- 1. **Node.js ≥ 18**
- 2. **Codex CLI** signed in with your ChatGPT account:
- - Bundled automatically with the ChatGPT desktop app on macOS, or install via `npm i -g @openai/codex`
- - Sign in once: `codex login`
- ## Quick Start
- ### 1. Check your environment (no quota spent)
- ```bash
- npx -y pixrelay doctor
- ```
- ### 2. Install into your harness(es)
- Preview changes first with `--dry-run`:
- ```bash
- npx -y pixrelay install --harness auto --scope user --dry-run
- ```
- Apply (safely merges existing JSON configs and creates `.bak` backups):
- ```bash
- # 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) |
- ## MCP Surface (`pixrelay mcp`)
- ### Tools
- | Tool | Purpose | Key Parameters |
- | --- | --- | --- |
- | `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` |
- | `pixrelay_job` | Poll or cancel an async job | `job_id`, `action` (`"status" \| "cancel"`) |
- | `pixrelay_history` | List recent generated images | `limit` (`1–50`, default `10`) |
- | `pixrelay_doctor` | Non-destructive diagnostics | *(none)* |
- ### Prompts
- - `pixrelay_art_direction`: Full structured prompting recipes, aspect-ratio defaults, and edit continuity guidelines.
- ## CLI Surface (`pixrelay`)
- ```bash
- # Generate a preview image (saved to ~/Pictures/pixrelay/)
- pixrelay gen "Minimal flat editorial illustration of a ginger cat holding a fountain pen, warm cream backdrop, no text"
- # Exact pixel asset (OG card 1200x630 WebP)
- pixrelay gen -o public/og.webp -s 1200x630 -q 85 "Clean geometric developer tool banner..."
- # Transparent sticker
- pixrelay gen -t -o assets/mascot.png "Cute ceramic cat sticker, thick white die-cut border, isolated on a fully transparent background"
- # Edit the most recently generated image
- pixrelay gen -i last -o assets/mascot-warm.png "Edit Image 1: shift lighting to warm golden hour; keep pose, outline, and expression identical."
- # Parallel JSONL batch from stdin
- printf '{"prompt":"Warm coffee mug icon","out":"a.png"}\n{"prompt":"Cool tea cup icon","out":"b.png"}\n' | pixrelay gen --batch -
- # Daemon & protocol diagnostics
- pixrelay daemon status
- pixrelay daemon stop
- pixrelay history --limit 10
- pixrelay schema-check
- ```
- ## Security & Safe Defaults
- - **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.
- - **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.
- - **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`.
- - **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`.
- ## Development & Testing
- 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:
- ```bash
- npm install
- npm run typecheck
- npm run build
- npm test
- ```
- ## Disclaimer & Attribution
- - **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.
- - **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).
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.