@felan-ai/ext-codex

First-party Felan support for GPT coding tools and Codex image generation. The structured tools activate only when the selected model ID is GPT-family and the provider is exactly openai or openai-codex.

Active mode keeps ordinary read, bash, and all unrelated tools, replacing only edit and write with apply_patch. Switching to another model restores the ordinary editing tools. File operations use the current AgentRuntime. The local TUI presents patch calls with friendly action labels while headless modes continue to expose the stable tool name and raw results.

Entry points

• @felan-ai/ext-codex is the renderer-free default extension for daemon and headless loading. Its createCodexTools export returns execution-only tools.
• @felan-ai/ext-codex/runtime remains a renderer-free entry for direct access to createCodexExtension, createCodexExecutionTools, and request controls.

All default entries carry the same execution contribution. Agent Core resolves it from validated extension configuration and applies the configured stream wrapper; hosts do not need a Codex-specific wrapper or package-name branch. Rich patch-call rendering belongs to apps/felan; the package exports no TUI entry. The root and /runtime export the same portable API, including createCodexTools. Configured hosts should import the root without a package-specific path rewrite.

For eligible Responses requests, extensionConfig.codex.priority accepts normal, fast, or ultrafast:

{
  "extensionConfig": {
    "codex": { "priority": "ultrafast" }
  }
}

The fast boolean is deprecated and hidden from /settings; existing config files and CLI options remain supported. Explicit priority overrides it. Omit priority to retain fast: true (priority processing) or fast: false (no tier override). With neither configured, no premium tier is requested. normal explicitly requests the standard default tier, even when fast is true.

Ultrafast currently applies to the exact gpt-6-astra and gpt-6.1-sol model IDs on eligible OpenAI and Codex Responses routes. Other eligible GPT models fall back to fast (priority). Pi does not expose service-tier capability metadata, so this model rule is maintained in the extension rather than fetched from a catalog. Account, plan, workspace and endpoint eligibility still apply; rejected requests are not automatically retried at another tier.

Fast and Ultrafast consume premium usage. The commonly cited 2x/8x figures are not universal billing multipliers or guaranteed task-speed increases. Consult OpenAI's speed documentation and API pricing for your authentication method. Pi's native cost estimates do not currently include Ultrafast-specific pricing. Priority selection does not change the model's reasoning effort or transport.

postAgentRunCompaction is enabled by default. It makes eligible GPT runs defer Pi's automatic threshold compaction until the current agent run settles, which preserves the pre-0.84.4 timing while allowing the completed tool loop to finish. Set it to false to use Pi's standard timing. Manual and overflow-recovery compaction remain immediate. Pi still owns summary generation; this setting does not enable upstream OpenAI native Responses compaction.

For eligible Responses requests, the extension converts Pi's nullable function-tool strict value to false so optional arguments remain optional. Explicit true or false values, absent values, and non-function tools are left unchanged.

Pi includes GPT-6 Astra in its built-in OpenAI and OpenAI Codex catalogs. The existing GPT policy enables this extension's structured tools and native Responses controls without a custom models.json entry.

For GPT-6 Astra, Sol, Luna, and GPT-6.1 Sol using openai-responses with an OpenAI API key, Pi sends native configuration_update items itself and keeps request-level reasoning.effort fixed at medium. For openai-codex-responses on either eligible provider, this extension keeps the initial request-level effort and projects a configuration_update before the next user message. Older openai/openai-responses sessions ignore persisted codex-reasoning-update entries and resume at Pi's fixed medium request effort, so expect one prompt-cache miss if their original initial effort was not medium. The extension's updates are retained across session resume and forks; after Pi compaction, the new context establishes its own effort baseline. A queued user follow-up receives its change before its next response; a tool-only continuation does not. Changes without another user turn are recorded when the run settles. These extension updates require standard, single-agent Responses requests; pro mode, server-side multi-agent mode, Chat Completions, other GPT models, and Anthropic are not supported. Automatic server truncation and compaction cannot be combined with native updates; Pi's existing local compaction remains available. Actual cache hits also depend on provider cache eligibility and can be checked using response usage cached-token counts.

Reasoning updates do not change provider transport. forceCachedWebSockets still applies only to openai-codex / openai-codex-responses; the official OpenAI API continues to use Pi's native transport.

The extension excludes restart-durable jobs, web access, Code Mode/Responses Lite, prompt replacement, native Responses compaction, voice, and UI widgets.

Codex image generation

extensionConfig.codex.imageGeneration defaults to true. When the host supplies MODELS_SERVICE, the extension registers the image-only openai-codex-images provider with gpt-image-2 and gpt-image-2.5. @felan-ai/ext-model-tools exposes these through generate_images when the session has an authenticated openai-codex login. Run /login openai-codex to use the legacy Codex login. Signing in with ChatGPT on the openai provider does not enable these image models. The selected chat model does not need to use Codex. Sessions restricted by enabledModels list no image models, because the scope contains only chat models.

Requests use POST https://chatgpt.com/backend-api/codex/images/generations, or /images/edits on the same backend with up to five reference images. They set background to opaque, quality and size to auto, and the originator header to pi. Requests count against the ChatGPT plan's Codex usage, not OpenAI API billing. The models have no API price, so Felan reports returned token counts without USD cost accounting.

Set imageGeneration to false to disable provider registration without changing Codex chat behavior. Restart or create a session after changing it.

Development

pnpm --filter @felan-ai/ext-codex build
pnpm --filter @felan-ai/ext-codex type-check
pnpm --filter @felan-ai/ext-codex test

See NOTICE for upstream attribution.

Package boundary and requirements

Agent Core owns the runtime contract and Pi owns chat-provider transport. This package owns provider/model eligibility, structured patch replacement, request controls, and the image-only provider. It does not replace Pi's chat providers. File operations go through the active AgentRuntime.

The package requires a compatible @felan-ai/agent-core peer and TypeBox. Neither the root nor /runtime loads terminal renderers. Host mode remains current-user access and is not a sandbox.

Related documentation

• Codex tools configuration
• Runtime and security
• Extension catalog

Attribution

Selected implementation behavior is adapted from the reviewed @howaboua/pi-codex-conversion and @howaboua/pi-codex-imagegen sources. See NOTICE and LICENSE for source commits and attribution.