pi-better-openai

A pi extension for OpenAI subscription workflows: fast mode, usage visibility, footer polish, custom Codex pets, and image generation through openai-codex auth.

Install

Requires Node.js 22.19.0 or newer.

Install from GitHub:

pi install git:github.com/mattleong/pi-better-openai

Or install from npm:

pi install npm:pi-better-openai

Authentication

Usage display and image generation require pi's openai-codex OAuth credentials.

1. In pi, run /login openai-codex.
2. Verify subscription usage with /openai-usage, or open /openai-settings and check Diagnostics.
3. The extension reads auth from pi's agent auth store, normally ~/.pi/agent/auth.json. Do not copy, paste, or commit values from this file.
4. If PI_CODING_AGENT_DIR is set, the auth store, global extension config, and global generated-image directory use that agent directory instead of ~/.pi/agent. A leading ~/ is expanded to your home directory.

Features

• Fast mode for supported OpenAI models, toggled with /fast or in /openai-settings.
• OpenAI subscription usage display via /openai-usage and the footer.
• Interactive settings picker via /openai-settings.
• Footer customization for model, thinking, fast mode, usage, and token/cost context.
• OpenAI image generation/editing through the openai_image tool and /openai-image command.
• Animated Codex custom pets rendered in the Better OpenAI footer.
• Commands:
  • /fast toggles fast mode.
  • /openai-image <prompt> generates an image directly.
  • /pets [help|list|wake [slug]|tuck|select <slug>] renders or manages custom pets from ${CODEX_HOME:-~/.codex}/pets.
  • /openai-usage shows current OpenAI subscription usage.
  • /openai-settings opens settings, diagnostics, and config details.

Configuration

The extension reads JSON config from two locations:

• Project config: .pi/extensions/pi-better-openai.json
• Global config: $PI_CODING_AGENT_DIR/extensions/pi-better-openai.json, defaulting to ~/.pi/agent/extensions/pi-better-openai.json

Project overrides global. Global values fill fields omitted by the project file. Invalid enum values are ignored, and numeric settings are clamped to safe ranges.

Default supported models:

[
  "openai/gpt-5.4",
  "openai/gpt-5.5",
  "openai-codex/gpt-5.6-sol",
  "openai-codex/gpt-5.6-terra",
  "openai-codex/gpt-5.6-luna",
  "openai-codex/gpt-5.4",
  "openai-codex/gpt-5.5"
]

Example config:

{
  "persistState": true,
  "desiredActive": false,
  "supportedModels": ["openai/gpt-5.5", "openai-codex/gpt-5.5"],
  "usage": {
    "enabled": true,
    "refreshIntervalMs": 60000,
    "showOnlyOnSubscriptionModels": true,
    "showResetTimes": true
  },
  "footer": {
    "mode": "status"
  },
  "image": {
    "enabled": true,
    "defaultModel": "gpt-5.5",
    "defaultSave": "project",
    "outputFormat": "png",
    "timeoutMs": 180000
  },
  "pets": {
    "enabled": false,
    "slug": "",
    "placement": "inline-right",
    "state": "idle",
    "thinkingState": "review",
    "toolState": "running",
    "failedToolState": "failed",
    "idleEmotes": true,
    "idleEmoteIntervalMs": 30000,
    "sizeCells": 10
  }
}

Image generation

Use the command for quick generation:

/openai-image draw an otter reading a terminal

Agents can call the openai_image tool directly. Supported parameters:

• prompt (required): pass the user's image wording verbatim.
• action: auto, generate, or edit.
• images: up to five distinct project-local reference/edit image paths. Paths must stay inside the current workspace and point to readable PNG, JPEG, WebP, or GIF files; each file is limited to 20 MB and the combined input to 50 MB.
• model: Codex image model override, for example openai-codex/gpt-5.5.
• outputFormat: png, jpeg, or webp.
• save: project, global, custom, or none.
• saveDir: required for save: "custom" unless PI_IMAGE_SAVE_DIR is set.

Save modes:

• project writes to .pi/generated-images/ in the current project.
• global writes to the agent generated-images directory, normally ~/.pi/agent/generated-images/ or $PI_CODING_AGENT_DIR/generated-images/.
• custom writes to saveDir or PI_IMAGE_SAVE_DIR; relative paths are resolved from the current project.
• none returns the image without saving it.

The repository ignores .pi/, so generated images and local config should not be committed.

Codex pets

Codex pets are an OpenAI Codex app feature, so the floating overlay and pet picker are still controlled by Codex (Settings → Appearance → Pets or /pet). This extension can also render compatible custom pet spritesheets directly in pi's Better OpenAI footer.

/pets wake          # render the selected pet, or pick one if none is selected
/pets wake <slug>   # render a specific ready pet
/pets select <slug> # select a ready pet without changing visibility
/pets tuck          # hide it
/pets list          # list local custom pets and readiness diagnostics

You can also enable Footer pet in /openai-settings, cycle installed pets with the Pet row, preview the selected pet in the footer, and tune placement (inline-right by default), idle, thinking/streaming, tool-execution, and any failed-tool animation states, plus random idle emotes and size.

To create a custom pet for the Codex app:

$skill-installer hatch-pet

Then reload Codex skills (Cmd/Ctrl+K → Force Reload Skills) and ask:

$hatch-pet create a new pet inspired by pi-better-openai

Custom pets should end up in ${CODEX_HOME:-~/.codex}/pets/<pet-name>/ with pet.json and spritesheet.webp. The spritesheet must be a 1536×1872 atlas arranged as 8 columns by 9 animation rows. Animated footer rendering also requires a terminal image protocol supported by pi. Refresh custom pets in Codex settings and toggle the overlay with /pet.

Screenshots