pi-codex-minimal-tools

Minimal Codex/OpenAI tools for Pi. Adds Codex-style tools without replacing Pi natives like read, grep, find, ls, bash, edit, or write. Pi 0.75 ships general image-generation APIs and OpenRouter image models; this package keeps the Codex-specific in-chat image_generation bridge, /image-gen Codex OAuth flow, view_image, and apply_patch.

Highlights

• image_generation — Codex-specific native image generation on supported openai-codex models, with saved local outputs.
• view_image — return a local image as model image content (off by default).
• apply_patch — local Codex-style patch application.
• /image-gen <prompt> [reference.png] — background image generation/editing via Codex OAuth, with a live status card.
• Generated images saved with timestamp filenames, latest.<ext> mirrors, metadata, and inline previews.
• Tools only activate on OpenAI/Codex-like models; hidden on Anthropic/Claude-bridge sessions.
• Optional direct OpenAI Images API fallback when OPENAI_API_KEY is set.
• Codex provider failures keep HTTP status prefixes such as HTTP 429: or HTTP 503: so Pi can classify retries and limits.
• Codex session parity matches Pi 0.82: cache/session IDs clamp to provider limits, cacheRetention: "none" disables session cache keys, sessionless WebSockets use UUIDv7, and missing cached continuations retry once with full context.
• Codex tool parity includes strict JSON-schema sampling, OpenAI grammar tools, and cache-friendly transcript-positioned loading for dynamically activated tools.

For web search, install pi-web-tools alongside this package.

Install

Via npm:

pi install npm:@vanillagreen/pi-codex-minimal-tools

Via vstack:

cargo install --git https://github.com/vanillagreencom/vstack.git vstack
vstack add vanillagreencom/vstack --pi-extension pi-codex-minimal-tools --harness pi -y

Restart Pi after installation.

Commands

Command	Action
/codex-minimal-tools	Open settings (or print status if extension-manager isn't installed).
/codex-minimal-tools:doctor	Run self-checks.
/image-gen <prompt> [reference.png]	Background image generation/editing via Codex OAuth.

/image-gen uses Codex/ChatGPT OAuth headers from Pi's model registry. It does not require OPENAI_API_KEY. Reference images may be @reference.png or bare local PNG/JPEG/WebP paths. The in-chat image_generation tool remains in-stream; use /image-gen when you want image work to continue while the agent does other things.

Settings

Open /extensions:settings; settings appear under the Codex Minimal Tools tab.

Project settings in .pi/settings.json apply only after Pi marks the workspace trusted; before trust, vstack Pi extensions read user/global settings only.

Glyph style: each package exposes glyphStyle (unicode default, ascii for terminal-safe chrome). @vanillagreen/pi-tool-renderer.globalGlyphStyleOverride=ascii forces ASCII chrome across vstack Pi extensions while leaving tool/model/user content unchanged.

General

Setting	What it does
Enable Codex minimal tools	Register image_generation, view_image, and apply_patch.
Auto-add tools to active set	Auto-activate this package's tools when a supported model is selected.

Provider

Setting	What it does
Native image_generation on Codex	Rewrite this package's image_generation function into OpenAI's Responses-API native tool on openai-codex. This is Codex-specific and coexists with Pi 0.75's general image APIs.

Images

Setting	What it does
Enable image_generation	Expose image_generation on supported models.
Image output directory	Where generated images are saved. Relative paths resolve against the workspace root.
Direct image API model	Model for direct OpenAI Images API fallback.
Direct Images API fallback	Allow direct OpenAI Images API generation when native Codex generation is unavailable.
Enable view_image	Expose view_image on image-capable models.
Restrict view_image to workspace	Reject view_image paths outside the workspace.

Patch

Setting	What it does
Enable apply_patch	Expose apply_patch.
Strict patch mode	Block edit/write so all edits go through apply_patch.
Allow absolute patch paths	Permit absolute paths in apply_patch.
Defer apply_patch rendering	Let pi-tool-renderer (preferred) handle display instead of registering an in-package renderer.