pi-image-gen

Pi extension that registers image_gen and delegates image generation to a local CLI provider: codex or agy.

codex uses codex exec with a JSON output schema and validates images under ~/.codex/generated_images/<session-id>/.

agy uses agy --print with prompt-constrained JSON output, --dangerously-skip-permissions, and validates the returned image path.

Installation

pi install npm:@smoose/pi-image-gen

Requirements

• For codex: codex must be on PATH, logged in, and able to use its built-in image generation capability.
• For agy: agy must be on PATH and logged in.

Tool parameters

• prompt: image prompt.
• images: optional local image paths.
• provider: optional auto, codex, or agy. Defaults to PI_IMAGE_GEN_PROVIDER or codex.
• model: optional provider-specific model. For agy, this overrides PI_AGY_IMAGE_GEN_MODEL.

Configuration

The default provider is resolved with this precedence (first match wins):

1. The provider argument passed to an individual image_gen call.
2. ~/.pi/agent/image-gen.json (written by /image-provider), e.g. {"provider":"codex"}.
3. The PI_IMAGE_GEN_PROVIDER environment variable.
4. The built-in default codex.

PI_IMAGE_GEN_PROVIDER=codex|agy|auto
PI_CODEX_IMAGE_GEN_TIMEOUT_MS=900000
PI_AGY_IMAGE_GEN_TIMEOUT_MS=900000
PI_IMAGE_GEN_MAX_CONCURRENCY=5
PI_AGY_IMAGE_GEN_MODEL="Gemini 3.5 Flash (High)"

If PI_AGY_IMAGE_GEN_MODEL is not set and no model parameter is passed, image_gen does not pass --model to agy.

auto selects an installed provider before execution, preferring codex over agy; it does not fallback after a provider failure.

Multiple image_gen tool calls can run in parallel. PI_IMAGE_GEN_MAX_CONCURRENCY limits concurrent provider processes and defaults to 5.

Commands

Use /image-provider to switch the default provider. The choice is persisted to ~/.pi/agent/image-gen.json, so it applies to every Pi session on this machine. The footer status shows the active selection.

/image-provider codex
/image-provider agy
/image-provider auto

Without an argument, Pi opens a provider picker.

Timeout

Both providers default to 15 minutes. For agy, the timeout is applied both to Pi's outer process guard and to agy --print-timeout.

Failure behavior

When image generation fails, the tool returns the failure reason and terminates the turn. It does not ask Pi to try Python, SVG, Image API scripts, or another provider unless the user explicitly asks for a fallback.

Returned image paths are validated for existence, readability, non-empty content, supported image type, fresh mtime, and not being one of the input images. Codex results are additionally restricted to the current Codex session directory.