pi-better-openai

A pi extension for OpenAI subscription workflows: fast mode, usage visibility, realtime voice, 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/monotykamary/pi-better-openai

Or install from npm:

pi install npm:@monotykamary/pi-better-openai

Authentication

Usage display, image generation, and live voice 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.
• Live web search through the openai_websearch tool and /openai-websearch command, backed by the ChatGPT Codex search backend.
• Codex-backed realtime voice through /live, with an animated microphone waveform and coding-task delegation into the active pi session.
• Animated Codex custom pets rendered in the Better OpenAI footer.
• Commands:
  • /fast toggles fast mode.
  • /openai-image <prompt> generates an image directly.
  • /openai-websearch <query> searches the web and inserts the cited answer into the session.
  • /live starts or stops realtime voice mode. Ctrl+Shift+L is the keyboard toggle.
  • /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-image-2",
    "defaultSave": "project",
    "outputFormat": "png",
    "timeoutMs": 180000
  },
  "live": {
    "enabled": true,
    "voice": "sol"
  },
  "pets": {
    "enabled": false,
    "slug": "",
    "placement": "inline-right",
    "state": "idle",
    "thinkingState": "review",
    "toolState": "running",
    "failedToolState": "failed",
    "idleEmotes": true,
    "idleEmoteIntervalMs": 30000,
    "sizeCells": 10
  }
}

Live voice

Run /live or press Ctrl+Shift+L to open the realtime voice panel. Ctrl+L remains pi's model selector, so the extension deliberately uses the shifted chord. While live mode has focus:

• Space toggles microphone mute.
• Escape, Ctrl+C, or Ctrl+Shift+L ends the call.
• The waveform reacts to microphone RMS level and the panel footer shows connecting, listening, working, speaking, muted, or error state.
• Streaming speech transcripts stay in the live panel. Coding and repository requests are delegated into the current pi agent session; normal tool and assistant output continues in the transcript, and the final result is spoken back through the live session.

Choose the spoken voice under Live voice in /openai-settings. Supported values are arbor, breeze, cove, ember, juniper, maple, sol, spruce, and vale.

Live mode requires interactive TUI mode, microphone/speaker access, openai-codex OAuth, and one of these native targets: macOS arm64/x64, Linux arm64/x64, or Windows x64. Standard HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY settings are honored for signaling and sideband traffic. Audio/WebRTC uses the MIT-licensed native platform packages from can1357/oh-my-pi. The adapted implementation is attributed in THIRD_PARTY_NOTICES.md. On macOS, launchd-managed LocalTerm users should rerun localterm install after upgrading LocalTerm and allow its microphone prompt.

The feature uses Codex Desktop's experimental gpt-live-1-codex/Quicksilver protocol rather than the public OpenAI Realtime API. Upstream protocol or entitlement changes may temporarily break it.

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. auto uses the edit endpoint when images are supplied; explicit edit requires images, while explicit generate does not accept them.
• 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: GPT Image model override for the standalone Codex Images API, for example gpt-image-2.
• outputFormat: png, jpeg, or webp. Codex returns PNG and the extension converts other formats locally.
• 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.

Web search

Use the command for a quick search:

/openai-websearch latest tanstack query release

Agents can call the openai_websearch tool directly. Supported parameters:

• query (required): the web search query.
• responseLength: short, medium, or long. Defaults to the configured value.

The tool returns a synthesized answer plus cited source URLs. It calls the undocumented chatgpt.com/backend-api/codex/alpha/search endpoint with your ChatGPT OAuth credentials (openai-codex login), so it can change or break without notice; OAuth/API-key-only setups without ChatGPT login are not supported.

Settings under websearch in the config file or the /openai-settings picker:

• enabled (default true), model (default gpt-5.6-luna), reasoningEffort (default max), responseLength (default short), maxOutputTokens (default 4096, clamped to 256-100000), and timeoutMs (default 25000, clamped to 5000-120000).

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.

Attribution

pi-better-openai was originally created by Matt Leong. This fork is maintained and published under the @monotykamary namespace while retaining Matt's authorship and the original Git history. Realtime voice adaptations have separate attribution in THIRD_PARTY_NOTICES.md.

Screenshots