pi-codex-conversion

[!NOTE] This version is a major rewrite. If you hit regressions, reinstall the last pre-rewrite build with pi install npm:@howaboua/pi-codex-conversion@1.5.21 and please report the issue.

GPT/Codex models are strongest when the tool surface looks like the Codex CLI they were trained around: shell commands, resumable terminal sessions, and patch-based edits. This extension brings that workflow to Pi while keeping Pi's runtime, sessions, project context, skills, and UI. For the brave, PATH mode shifts the toolkit into Pi's internal PATH, instead of the JSON-defined tool schema.

Tool execution uses bundled Rust helpers for better process isolation and lower Pi runtime blast radius; see Why bundled Rust tools?. PATH mode exposes extra Codex tools as shell commands on an extension-injected internal PATH; see PATH_TOOLS.md.

PATH mode is very likely to consume less tokens, but YMMV. The system prompt has been tweaked to enable GPT models to one-shot call tools, even when they don't have a JSON schema definition. Any suggestions or tweaks are welcome! The whole point is that if the agent fails a tool call because it "didn't know the tool", this mode loses its advantages. It's been tested and it's working, but edge cases may still exist.

Install

pi install npm:@howaboua/pi-codex-conversion

What changes in Pi

• Adapter mode activates automatically for OpenAI gpt* and codex* models, then restores the previous tool set when you switch away.
• Pi's composed prompt is preserved; the extension only adds a small Codex-style tool-use nudge.
• Shell activity is rendered with Codex-like labels such as Ran, Explored, Read, and background-terminal status.
• PATH image outputs from view_image and imagegen render inline in chat.
• Raw command output is still available by expanding the tool result.

Active tools in adapter mode

Normal mode keeps the familiar Pi function-tool surface:

• exec_command — shell execution with Codex-style cmd parameters and resumable sessions
• write_stdin — continue or poll a running exec session
• apply_patch — patch edits through the bundled Rust patch tool
• view_image — inspect local images through the bundled Rust image tool when the model supports image input
• web_run — Codex-backed web search through the bundled Rust web tool when enabled and supported
• imagegen — Codex-backed image generation and image edits through the bundled Rust image generation tool when enabled and supported

PATH mode narrows the structured tool surface to shell control only:

• exec_command — shell execution with Codex-style cmd parameters and resumable sessions
• write_stdin — continue or poll a running exec session

GPT-5.6 Code Mode, available as an opt-in beta for Luna, Terra, and Sol, narrows the provider-visible surface further:

• exec — run isolated JavaScript that composes nested tools
• wait — resume or terminate a yielded JavaScript cell

Inside exec, Codex extras are nested native calls: tools.apply_patch(patch), tools.view_image(...), tools.web__run(...), and tools.image_gen__imagegen(...). tools.exec_command(...) and tools.write_stdin(...) use the same shell implementation as normal and PATH modes. Only outer exec and wait reach the provider, so nested schemas remain local to the V8 host. TOML tools from ~/.pi/agent/codex-conversion-custom-tools/ remain callable through tools.*; definitions are deferred by default and can be promoted with defer_loading = false. Working opt-in templates ship under examples/custom-tools/.

Nested calls retain their structured Pi rendering—shell summaries, parallel outputs, patch diffs, resumable sessions, web/image results, partial updates, and generic TOML-tool output—without exposing extra provider tools.

By default, Code Mode keeps the JavaScript machinery transparent and renders nested operations like direct Pi tools. Turn on Code Mode details for the outer exec/wait cells, expandable JavaScript, and printed runtime output. Tool renaming independently controls whether nested operations use polished Codex-style cells or their generic tool names.

Code Mode custom tools

Put custom tool definitions in ~/.pi/agent/codex-conversion-custom-tools/, or under $PI_CODING_AGENT_DIR/codex-conversion-custom-tools/ when configured. Each top-level TOML filename becomes a method on tools. Definitions stay deferred unless they set defer_loading = false.

The package includes disabled templates under examples/custom-tools/ for port_info, semantic_grep, spawn_agent, vent, and workflows_create. To enable one, copy its TOML and matching companion directory into the custom-tools directory without changing their relative layout. Installing the package does not enable any example.

In PATH mode, Codex-style extras live on the extension-injected internal PATH:

• apply_patch — patch edits
• view_image — inspect local images
• web_run — Codex-backed web search
• imagegen — Codex-backed image generation and image edits

Notably:

• there is no dedicated read, edit, or write tool in adapter mode
• local text-file inspection should happen through exec_command
• file creation and edits should default to apply_patch; in PATH mode that is the shell command
• in PATH mode, image/web tools run through exec_command as PATH tools, not Pi function tools
• Pi may still expose additional runtime tools such as parallel; the prompt is written to tolerate that

PATH mode examples

These commands run inside exec_command when PATH mode is enabled.

view_image '{"path":"/x.png"}'
web_run '{"search_query":[{"q":"..."}],"response_length":"short"}'
imagegen '{"prompt":"..."}'
imagegen '{"action":"edit","prompt":"...","images":["https://... or /x.png"]}'

For quote-heavy JSON, pass JSON through stdin:

imagegen <<'JSON'
{"prompt":"keep the creature's original style"}
JSON

Generated images are saved under .pi/openai-codex-images/ at the workspace/repo root, with the latest image mirrored to latest.png.

Settings

Use /codex to change adapter settings.

• /codex all — use the Codex tool and prompt adapter on every model
• /codex status — toggle the footer/statusline entry
• /codex fast — toggle priority service tier for the OpenAI Codex provider
• /codex compact — open native compaction settings
• /codex usage — show Codex subscription usage windows for the active OpenAI Codex model
• /codex reset — open the Usage tab, where banked rate-limit resets can be used with Ctrl+R
• /codex low, /codex medium, /codex high — set Responses API verbosity
• /codex ps — show the background shell widget

Settings are saved globally in ~/.pi/agent/pi-codex-conversion.json.

The settings UI has General, Tools, OpenAI, Beta, Usage, and About tabs. Usage refreshes automatically when opened, can be refreshed manually with R, and shows banked Codex rate-limit resets with their expiry above the usage windows. When resets are available, press Ctrl+R in the Usage tab to use one. After a reset attempt, press R before using another reset.

General controls PATH mode, scope, status UI, background shells, and whether native Responses compaction is enabled. Native compaction applies to OpenAI Codex and explicitly added providers; all-model scope only changes the tool and prompt adapter. PATH mode switches the adapter to the shell-only surface above.

Advanced users with custom Codex-compatible providers can add provider ids in General, or by editing ~/.pi/agent/pi-codex-conversion.json:

{
  "scope": {
    "additionalProviders": ["my-provider"]
  }
}

Tools shows required adapter behavior and optional web/image/apply-patch prompt features. General settings control tool renaming, compact tools, Code Mode details, and the background shell widget. OpenAI controls fast mode, verbosity, cached WebSocket upgrade, web search model, and compaction model/reasoning. Cached WebSockets are prewarmed at session startup. Web search and compaction default to gpt-5.6-luna.

Beta contains GPT-5.6 Code Mode, off by default and limited to OpenAI Codex Luna, Terra, and Sol. It atomically enables Codex's Responses Lite transport and code-mode-only toolkit: instructions and client tools become input items, exec and wait are the only provider-visible tools, and JavaScript restores parallel composition through nested calls. The same Responses Lite transport applies to native compaction.

Maintainers: see UPSTREAM_SYNC.md for the provider parity checklist and intentional exclusions.

The footer shows the active state, for example:

Codex adapter V: low • fast

Why bundled Rust tools?

The bundled tools are not only for Codex-shaped PATH mode. They also reduce the blast radius of heavy tool work.

If a Pi-native TypeScript tool allocates too much memory, blocks the runtime, or crashes badly, it can take the Pi process with it. When a bundled Rust tool fails, it usually fails as a child process: TypeScript reports a tool error, Pi stays alive, and the agent can retry or choose another path.

That matters most for process control, PTYs, patch application, image handling, and large command outputs. TypeScript still owns the Pi-facing parts: JSON schemas, model/auth gating, result conversion, rendering, and deciding what enters chat history.

Details worth knowing

• exec_command and write_stdin use a bundled Rust exec bridge; tty: true runs through a PTY for interactive commands.
• GPT-5.6 Code Mode starts its isolated V8 host lazily; the first exec downloads and verifies the pinned host binary when needed.
• PATH mode prepends the package bin directory to exec session PATH so bundled Codex tools are available in shell commands.
• imagegen waits up to five minutes in a foreground exec_command call before falling back to a resumable session.
• The package includes bundled binaries and vendored Rust source for the PATH tools.
• If native compaction fails, the extension falls back to Pi's normal compaction flow. When an older native compacted window exists, it is included in that Pi fallback summarization request so OpenAI can still use the prior opaque context server-side.

Command rendering examples

• rg -n foo src -> Explored / Search foo in src
• rg --files src | head -n 50 -> Explored / List src
• cat README.md -> Explored / Read README.md
• npm test -> Ran npm test
• write_stdin({ session_id, chars: "" }) -> Waited for background terminal
• write_stdin({ session_id, chars: "y\n" }) -> Interacted with background terminal

Development checkout

The Git checkout is mostly for development and mirrors the maintainer workflow. It uses committed binaries; rebuild local-platform binaries only after changing Rust source.

Published installs include prebuilt native binaries. For best compatibility on older Linux systems, or if a bundled tool fails with a loader error such as GLIBC_2.39 not found, use a Git checkout and build the tools on that machine instead of upgrading glibc manually:

cd /path/to/pi-codex-conversion
bun install
bun run build:path-tool codex-exec-shim exec_bridge

Run the current checkout without installing globally:

pi --no-extensions --no-skills -e /path/to/pi-codex-conversion

License

MIT