pi-codex-image-gen

Image generation for Pi using the ChatGPT Images 2.0 model.

Package details

← Back

extensionskill

Install pi-codex-image-gen from npm and Pi will load the resources declared by the package manifest.

npm report

$ pi install npm:pi-codex-image-gen

Package: pi-codex-image-gen
Version: 0.1.2
Published: Apr 26, 2026
Downloads: 387/mo · 387/wk
Author: mocito
License: Apache-2.0
Types: extension, skill
Size: 163.9 KB
Dependencies: 0 dependencies · 3 peers

Pi manifest JSON

{
  "extensions": [
    "./index.ts"
  ],
  "skills": [
    "./skills"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-codex-image-gen

Image generation for Pi using the ChatGPT Images 2.0 model via the OpenAI Codex Responses backend.

Install

pi install npm:pi-codex-image-gen

To uninstall:

pi remove npm:pi-codex-image-gen

Quick usage

In a Pi session:

> Generate a pixel-art sword icon, 32×32, with a blue blade and gold hilt

The agent will invoke codex_generate_image with your prompt, stream the response from the Codex backend, and save the resulting image to disk. The model parameter controls the Codex routing model; image generation is always performed by gpt-image-2 on the backend.

Authentication

Uses your existing openai-codex login — no OPENAI_API_KEY required. If you haven't logged in yet:

> /login

Select ChatGPT Plus/Pro (Codex) and complete the OAuth flow.

Configuration

Create a JSON config file at one (or both) of these locations:

Scope	Path
Global	`~/.pi/agent/extensions/codex-image-gen.json`
Project	`<project-root>/.pi/extensions/codex-image-gen.json`

Project config overrides global config. Example:

{
  "save": "global",
  "saveDir": "~/Pictures/generated",
  "model": "gpt-5.5"
}

Config keys

Key	Type	Default	Description
`save`	string	`"global"`	Default save mode (see below).
`saveDir`	string	—	Directory used when `save=custom`.
`model`	string	`"gpt-5.5"`	Codex routing model. Image generation is always handled by gpt-image-2.

Environment variables

Variable	Description
`PI_CODEX_IMAGE_SAVE_MODE`	Overrides the `save` config key.
`PI_CODEX_IMAGE_SAVE_DIR`	Overrides the `saveDir` config key (custom mode).

Save modes

Mode	Behavior
`none`	Image is returned inline but not written to disk.
`project`	Saves to `<project>/.pi/generated-images/<session-id>/`.
`global`	Saves to `~/.pi/agent/generated-images/<session-id>/`.
`custom`	Saves to a user-specified directory (requires `saveDir` or env).

Tool parameters

Parameter	Type	Required	Description
`prompt`	string	✅	The image generation prompt.
`model`	string	—	Override the Codex model. Defaults to config or `gpt-5.5`.
`outputFormat`	string	—	`png` (default), `jpeg`, or `webp`.
`save`	string	—	Override save mode for this call.
`saveDir`	string	—	Directory when `save=custom`. Relative paths resolve under CWD.

How it works

Resolves auth via Pi's openai-codex provider (ChatGPT session token).
Sends a Codex Responses API request to the routing model (default gpt-5.5) with the image_generation tool enabled.
The backend invokes gpt-image-2 to generate the image.
Parses the SSE stream for response.output_item.done events containing the base64 image.
Saves the image to disk according to the active save mode.
Returns the image data inline plus metadata (model, format, path, revised prompt, usage).

Troubleshooting

Symptom	Cause	Fix
"Missing openai-codex credentials"	Not logged in	Run `/login` and select ChatGPT Plus/Pro (Codex)
401 / 403 response	Token expired	Re-run `/login` for openai-codex
429 response	Rate limited	Wait and retry; the extension retries automatically with backoff
"Codex did not return an image"	Backend refused the prompt	Rephrase the prompt and try again
"save=custom requires saveDir"	Missing config	Set `saveDir` in config or `PI_CODEX_IMAGE_SAVE_DIR` env var

License

Apache-2.0