@op1/open-imagegen

Generate and edit images in OpenCode V2 with your existing ChatGPT sign-in.

Install

This plugin targets OpenCode 2.0.28. Use 0.2.2 with OpenCode 2.0.26 and earlier. Sign in to OpenAI through ChatGPT OAuth in OpenCode before generating an image.

Install the npm package:

opencode plugin add @op1/[email protected]

This adds the package to ~/.config/opencode/opencode.jsonc:

{
	"$schema": "https://opencode.ai/config.json",
	"plugins": ["@op1/[email protected]"]
}

The npm package includes the built plugin. Run opencode plugin list to check that imagegen is active.

Generate an image

Ask OpenCode to generate an image, for example:

Generate a square paper-cut illustration of an orange fox beside a laptop, on a midnight-blue background.

The agent calls imagegen with a prompt. Describe the composition, aspect ratio, text, style, and transparency in that prompt. The tool generates one PNG per call and returns its path plus a file attachment. Code Mode may show only the saved-path text; use read on the PNG to inspect it.

The plugin uses your active OpenAI ChatGPT OAuth connection, even if the agent uses a different model provider. Image generation consumes your ChatGPT image quota. It does not require an API key or a separate Codex installation.

Images are saved under $XDG_DATA_HOME/opencode/generated_images/, or ~/.local/share/opencode/generated_images/ when XDG_DATA_HOME is unset. Each call uses a unique directory. Files are private to their owner and existing files are never replaced.

Edit an image or use visual references

Give OpenCode the image's absolute path and describe the changes:

Edit /absolute/path/to/fox.png. Make the orange fur blue, but keep the white fur, pose, laptop and background.

For reference-guided generation, provide multiple image paths and describe each image's role:

Use /absolute/path/to/layout.png for composition and /absolute/path/to/style.jpg for the visual style. Create a new illustration of a fox.

The agent supplies referenced_image_paths to the same imagegen tool. Previously generated PNGs work as references using their saved paths. You can supply one to five PNG, JPEG or WebP files, up to 20 MiB each and 40 MiB combined. Paths must be absolute and must not contain symlinks. If a file changes while awaiting approval or being read, the call fails rather than uploading different contents.

Before reading image contents, the plugin checks native external_directory and read permissions. It then requests separate imagegen_upload approval, naming the paths and OpenAI destination. This approval applies to one call and does not save a blanket upload grant. Non-interactive clients that auto-approve permission requests can answer this prompt automatically; do not use auto-approval if you require human confirmation.

References require the managed OpenCode service. The plugin authenticates to that service through the supported client and verifies its PID matches the plugin's process. Standalone or unregistered servers fail safely instead of skipping permission checks. Plain generation does not need this local permission connection.

Develop and verify

From a source checkout, install dependencies with Bun and run the checks:

bun install --frozen-lockfile
bun run verify

To also inspect an existing generated artifact, pass its path:

bun run verify /absolute/path/to/image.png

Verification runs typechecking, the transport, file and permission tests, a bundle build, and an active-plugin check against the running OpenCode service. It does not generate another image or consume quota. On macOS, sips -g pixelWidth -g pixelHeight -g format /path/to/image.png provides an independent format check.

To exercise native permission creation against the running service, run bun run verify:permissions. It creates and removes temporary sessions, checks that an upload prompts and an explicit deny remains final, and rejects its own test prompt. It reads no reference file and sends no image request. It expects the standard build and title agent policies.

For a live edit test, provide a generated image's path and ask OpenCode to change one visible detail. Approve the upload, open the new PNG with read, and check that the original file is unchanged. This test consumes quota.

Control permission

The tool uses the imagegen permission action for general access. Plain generation respects existing rules without forcing a prompt. To ask before each generation call, add a rule to the ordered permissions array in ~/.config/opencode/opencode.jsonc:

{
	"action": "imagegen",
	"resource": "*",
	"effect": "ask"
}

Limits

• Every edit produces a new PNG. Originals are never edited in place.
• No conversation-history image scraping.
• No automatic retries or API-key fallback. A failed or cancelled request may already have consumed server-side quota.
• Prompts have a 32,000-character limit. Responses have a 48 MiB limit and decoded PNGs have a 32 MiB limit. Requests time out after ten minutes.
• This uses a ChatGPT backend endpoint, not a guaranteed public API. Server changes or account eligibility may break it.
• Dependencies target OpenCode 2.0.28. Re-run verification after an OpenCode upgrade.

Troubleshoot

For a missing account or HTTP 401 error, reconnect your OpenAI ChatGPT account in OpenCode. An API-key connection is not sufficient. HTTP 403 can indicate account or client eligibility. HTTP 429 indicates rate limiting or exhausted quota. The plugin does not print raw error responses, credentials, or base64 image data.

Reference uploads always escalate to an imagegen_upload request unless a configured deny already blocks them. To disable uploads, add an imagegen_upload deny rule. A general imagegen allow rule does not skip native file checks or the separate upload request.

Global plugin files are discovered automatically. After editing source, run bun run verify to rebuild the generated index.js entrypoint. OpenCode hot-reloads that bundle, including its local helpers. Do not edit index.js by hand. Restart the service only if rebuilding does not reload the plugin.

See DESIGN.md for the Codex protocol trace and design decisions.