Structured mode reads files through the shell and edits with apply_patch. There are no separate text read, edit or write tools.

Provider scope can stay on Codex and configured, expand to all providers, or use extra tools only.

Custom-tool contract changes and removals, including promoted tools, are announced before the next model request without rebuilding the standing Code or Notebook instructions. ALL_TOOLS contains complete callable contracts.

/codex saves changes immediately. During a run, they take effect after it settles, including retries and queued continuations. Voice stop, mute and server controls remain immediate.

Open tabs directly with /codex tools, /codex openai, /codex display, /codex voice, /codex usage or /codex about.

Usage tracking

/codex usage shows recorded API-equivalent spend, per-model tokens and estimated quota shares. Spend-rate comparisons use the previous reset window and previous calendar month. /codex usage analyse asks your agent to inspect longer-term trends and reasoning levels through a bundled read-only Node script.

Tracking matches the openai-codex-responses API, including renamed providers. The standard setup is openai-codex on ChatGPT's subscription endpoint. Renamed providers and custom endpoints show an accuracy warning; the warning also remains on totals containing their recorded usage. Usage and reset requests follow the configured endpoint and headers. Proxies must expose the Codex subscription usage API and account-bearing authentication; unsupported endpoints report an error. Aggregator routing and billing are not reconciled.

On first viewing Usage, a background scan imports recorded session costs for the current window and an approximate previous week. Earlier manual reset times cannot be recovered; analysis reports retain the window provenance. Session files lack reliable account identity: local history attaches once to the first viewed account. Missing or unsaved calls cannot be recovered.

Totals persist in codex-usage.json in Pi's agent directory, with no conversation content. Later views read running aggregates without rescanning sessions. New tracking is account-separated and includes local Codex responses, native compaction and generated cache keepalive. Other apps, devices and separately implemented tool requests are not included.

Opening or refreshing Usage records the weekly allowance and reset prediction. A changed prediction can split the provisional window; completed windows keep their recorded totals and quota estimates. Partial windows, missing prices and gaps remain visible. Quota shares are cost-weighted estimates because the account allowance can include activity outside Pi. These dollar values are API equivalents, not subscription charges.

Configuration scope

The first setting chooses Global or This project:

• Global: ~/.pi/agent/pi-codex-conversion.json.
• This project: creates a snapshot at .pi/pi-codex-conversion.json. Every tab and Edit config targets it. Only trusted folders are read.
• Switching back to Global removes project overrides. Without a project file, all settings inherit globally.
• Luna cache keepalive remains global. Astra, Sol and Terra keepalive follows the project, across model versions.

Fast Mode has independent settings for Astra, Sol, Terra and Luna, shared across each family's model versions. Choose off, on for priority processing, or Ultrafast. Existing boolean preferences still work. PI_CODEX_FAST=1, 0 or ultrafast overrides every family for one Pi process. Availability depends on the model and account. Ultrafast API-equivalent estimates use the published rates for GPT-6 Astra and GPT-6.1 Sol, six times Standard. Other models retain base-rate estimates without an unknown Ultrafast premium. These estimates are not subscription quota rates. Run /reload after editing config files by hand.

On Codex transport, the Daybreak toggle keeps your selected model and chooses an access program from the connected account's model catalog: Blue first, otherwise Red. When enabled, unconfirmed support stops the request rather than silently using ordinary routing. Turning Daybreak off requests Standard when advertised, otherwise leaves the program unset. The server still checks approval and model access. Existing Daybreak model aliases remain available. See OpenAI's Daybreak guide for supported combinations.

tools.customRustBinariesDir overrides bundled helpers by filename, including exec_bridge, apply_patch, view_image and pi-codex-voice. Build on the target machine, collect the binaries in one directory, set its path, then /reload.

Code Mode always uses the pinned official OpenAI runtime, downloaded on first use. It does not use local builds or tools.customRustBinariesDir.

Optional controls

• Heavy system prompt overwrite: on removes roughly 40% of Pi's known default scaffold while preserving other extensions' additions. GPT (experimental) builds on that baseline with denser PCC instructions and participating toolkit guidance. Tool arguments and capabilities stay unchanged. Savings depend on execution mode and context. Off by default. Existing boolean configuration still works. Set prompt.heavySystemPromptOverwrite to "gpt" for GPT mode.
• Current time reminders: choose 30 or 60 minutes under General. Active Responses adapters receive a persisted UTC developer message on the first inference in each context and when the interval has elapsed. No timer, extra turn or system-prompt change. Off by default.
• Auto reasoning: lets GPT-6 Astra, Sol and Luna, plus GPT-6.1 Sol, adjust effort through change_reasoning on Codex transport. Offers low, medium, high, xhigh and max, never below your selected level, and restores that level after the run settles, including retries and compaction. Enable tools.autoReasoning under Tools. Off by default.

On these GPT-6 models, auto reasoning and Shift+Tab use native configuration updates that preserve the request prefix and continuation eligibility. Cache hits still depend on the server. Updates survive resume and native compaction. Server-side automatic truncation and compaction are incompatible, but explicit Responses compaction V2 is supported. Other models retain Pi's usual reasoning selector.

Luna Reserve

After ordinary Codex quota runs out, eligible accounts may receive a limited Luna Reserve allowance, shown as gpt-reserve in backend usage. The extension switches only with backend authorization, then asks you to send continue. It never retries for you or redeems a reset credit.

Your original model and reasoning return on the next input after the backend confirms ordinary quota has recovered. Choosing another model cancels that automatic return for the branch. Reserve is not in the ordinary model picker.

Choose under /codex context:

Defaults are Compaction, Pi summary and 64k retention, with Local remembered for notes storage. Hidden controls retain their saved values.

• Compaction: Pi's manual and automatic compaction, without notes or rollover tools.
• Notes and history: the model saves notes and retrieves history. Explicit new windows start without a conversation summary.
• Notes + history + compaction: Pi's automatic compaction and /compact use the selected method while notes and history lookup remain available. Compaction stays in the current window and does not require saved notes.

Notes-based strategies are experimental. Purple markers identify windows. new_context preserves the shell, Notebook runtime, workspace and full Pi JSONL. Changing strategy preserves the current conversation and usable checkpoints. A notes-only rollover cuts the previous conversation from active context, not stored history.

Resume notes-based sessions with the same storage. Changing storage neither copies notes nor starts a window or disables compaction. Switching to Compaction removes recovery tools without turning notes into a summary.

Storage and compaction

• Local: reads prior windows and stores model-invisible note updates in Pi's JSONL.
• Tree: archives windows as Pi side branches. Archive summaries stay visible in the transcript, outside model context. History search prioritizes summaries but can retrieve every raw entry.
• Remote: uses Codex's encrypted history and notes service. Requires openai-codex-responses and fails without switching storage. Other transports ignore it.

Local and Tree require an active Responses adapter. Other provider APIs do not expose notes-based context management.

Pi summary is readable. Codex V2 is an encrypted checkpoint. Both adds a readable summary on a separate request lane, at extra summarization cost. Codex uses the checkpoint while other providers can use the summary. Both supports every storage backend and either compaction-based strategy. V2 retention budgets recent user messages kept verbatim, not total context.

V2 and Both require Codex or an explicitly configured compatible passthrough. Other routes use Pi summary without erasing the saved method. Selecting Pi summary preserves an existing V2 checkpoint until the next successful compaction converts it. Choose Both before the checkpoint you need across providers, or convert to Pi summary before switching. Tree checkpoints remain usable by reference after changing storage.

Old configurations migrate on read without rewriting the file. Hybrid becomes Notes + history + compaction with Codex V2, or Both when Parallel Pi summary was enabled. V2 with Parallel Pi summary becomes Compaction with Both. Saving removes the old switches.

Rollover and recovery

Use notes for tree summaries is on by default for Local, Tree and Remote. Choosing a summary in Pi's tree navigator saves a handoff note for the destination, even before the first window marker. Local and Tree preserve existing destination notes. Remote note contents remain encrypted and cannot be independently verified. Interrupted or failed handoffs cancel the jump. Turn the setting off to use Pi's ordinary branch summary without a note-writing run, while keeping notes and history enabled. Either choice navigates to your selected destination and does not roll over the window. No summary remains a plain jump.

The model receives history, notes, rollover and remaining-context tools. Code and Notebook modes use tools.history({ action, ...args }) and tools.notes({ action, ...args }) inside exec, with required arguments upfront and detailed help in ALL_TOOLS. Remote calls accept ordinary query and note text directly in JavaScript. These inputs appear in execution source and traces. Protected results reach the model automatically through their originating exec, including after wait, while JavaScript receives only receipts. Remote results cannot be inspected inside JavaScript and need no extra delivery call. Direct native Remote tools retain encrypted inputs. wait resumes or terminates unfinished cells. new_context stays native. Checkpoint reminders arrive at 85% used and 90%, unless the current run has already saved notes. They may request a checkpoint after a final reply but never force rollover, interrupt tools or validate notes. Percentages use the model's full configured window.

Remote results remain tied to their original context family and Codex account. An account mismatch makes pinned notes unavailable without moving them to another account or store. Agents can exchange needed context through messages. Re-reading a completed result does not count as a new note checkpoint.

With Notes and history, /compact reuses notes from the last completed run and opens a window without starting a new turn. New input or another run makes those notes stale. Without fresh notes, or with checkpoint instructions, it asks the agent to save state, then opens the window after that run settles. A failed or missing note leaves the current window in place. With Notes + history + compaction, explicit new_context attempts compaction before rollover.

New window requests controls agent requests independently of the continuity strategy. off hides new_context. pi-limits requires Pi to accept the history for compaction, including with notes-only continuity. A declined request continues in the same window. unrestricted permits requests at any size. If normal compaction has nothing to summarise, it opens a new identity without trimming the existing context. Other failures do not open a window. Manual /compact and idle rollover are unaffected.

Before new_context, the immediately preceding tool invocation must successfully save a context note. Direct notes writes, nested writes completed by exec, and writes completed through wait count. Failed or unfinished writes and intervening read-only calls do not count.

Note save markers in /codex display is off by default. When enabled, completed turns with confirmed saved notes get a ✓ Notes saved marker. The next user prompt gets a Notes bookmark in /tree once it arrives. Select that prompt with No summary to return to the saved-notes boundary with your prompt back in the editor. Run plain /compact in Notes and history, then resubmit the prompt. A new window opens without another note-writing turn. Tree navigation preserves the checkpoint's original idle age. Existing user labels are preserved, and turning markers off keeps saved bookmarks.

Idle rollover is off by default and applies only to Notes and history, with Local, Tree or Remote storage. Choose 5, 15, 25 or 55 minutes. After that duration since a run settled, the next prompt opens a window first only if the latest completed run saved fresh notes. Otherwise the prompt starts normally in the current window, without a checkpoint request. The original prompt and attachments proceed through normal preparation. Resume uses the recorded settlement time. Older runs without a recorded settlement do not trigger idle rollover. Existing idleNotesRollover: true configuration retains 25 minutes; false remains off. This is a cache optimisation, not a cache-expiry check. If rollover fails, input and attachments remain pending. Submit another prompt to retry, or reload to cancel pending input.

Automatic overflow recovery compacts in the current window. Notes-only sessions use Pi summary for this emergency recovery. Other strategies use the selected method. Pi's automatic compaction must be enabled.

Shared agent context

Share subagent context shares notes and history with newly spawned agents through a compatible subagent extension. It is off by default. Children get unique agent paths and native Pi thread IDs under the parent's session identity, not a shared transcript.

Identity survives rollover and resume. Forks start independent families. Turning sharing off affects future spawns, not existing children. Existing sessions are never rebound.

Remote sharing requires the same Codex account and Remote storage throughout. Local and Tree retain notes in their owning sessions and rely on the integrating extension for transport. Remote failures never switch storage. See Extension APIs below for integration.

Set Codex diagnostics to Status or Status + log under /codex openai. Off by default. The existing openai.cacheDiagnostics configuration key and values are unchanged.

Pi's footer shows cache percentage. The extension-status row explains transport and continuation:

Codex adapter V: low • notebook mode Codex Cache • HIT • WS delta

A miss stays visible for three seconds before the row jumps to the latest state. WebSocket continuation and prompt caching are separate. A full request can still hit the cache.

Status + log adds • log and writes to ~/.pi/agent/pi-codex-logs/<session-derived-name>.log. Logs cover response, prewarm and native compaction requests, cache and continuation decisions, model settings, routing-hint presence, parent-link presence, allowlisted worker classification, token usage, retries, fallback and safe failures. Parent identifiers and routing-header values are not recorded. previous_response_present is a boolean, not a response ID.

Logs exclude prompts, messages, tool arguments, images, credentials, provider payloads and response IDs.

On a reused WebSocket, request settings describe the current body but handshake headers are not resent. request_headers_sent=false makes that boundary explicit. A routing hint is advisory, not evidence of a routing decision.

Local request IDs correlate retries and fallback without using server IDs. Timings use a monotonic clock. send_ms, first_event_ms, first_visible_text_ms and completion_ms are measured from the local transport attempt start, including connection acquisition. First visible text means receipt of the first nonempty text delta, not a screen-paint timestamp. Completion means receipt of a terminal response event. request_elapsed_ms spans provider preparation and recovery, not the harness's whole user turn. For reused prewarm readiness without a sent request, only elapsed time is available.

output_tokens_per_second is completed provider-reported output tokens divided by the interval from send to completion. It includes reasoning tokens where the provider includes them in output usage. It is not visible-text speed or an inference-only rate. Non-generating prewarm and failed attempts report no throughput. Missing local boundaries are null.

Optional backend timing fields retain their original names. Missing fields are "missing" and explicit backend nulls remain null. Backend delta counts are not token counts, engine counters are not billing usage, and engine_service_total_ms is not inference duration.

Pi's generic cache warmer is disabled on Codex and Responses Lite because they cannot honor its one-token output cap and warming would disturb continuation. Native Codex uses separately configured, isolated keepalive. Other routes retain Pi's warmer.

Keepalive is opt-in and sends quota-consuming requests while idle. In /codex under OpenAI, Astra, Sol and Terra offer Off or a 25 or 55 minute request interval for this project. Luna offers a global Off or 5, 10 or 15 minute duration, with a separate 2.5 or 4.5 minute request interval. Changing Luna's interval does not enable keepalive or extend its duration. Requests stop when that duration expires, and completed requests can reduce how many fit within it. Existing enabled settings retain their 25 minute or 2.5 minute interval.

These are request intervals, not guaranteed cache lifetimes. Reports suggest around an hour for Astra and Sol and five minutes for Luna 6, but retention can vary. Keepalive intervals are independent of notes-managed idle rollover and task-boundary reminders.

Select Code or Notebook under /codex → General. This applies wherever the adapter is active, including all providers scope. Providers retain their normal transport. Compatible Codex models use Responses Lite automatically. Configured OpenAI Responses proxies can opt in through Proxy Responses Lite.

The model composes tools in a JavaScript cell:

const status = await tools.exec_command({ cmd: "git status --short" });
text(status);

Notebook adds persistent JavaScript and TypeScript bindings in Deno. Call notebook({}) for state-management guidance, then send JSON action objects in input. Explicit { input: "help" } also returns guidance. The first turn receives status and retained bindings automatically.

Pi extension and MCP tools

Pi-callable extension tools automatically appear in tools, with no extra registration. ALL_TOOLS lists active direct tools and tools with codemode exposure. Native extension tools with deferred exposure appear in the catalogue only while active in Pi, but remain callable by name while inactive. Catalogue changes leave standing tool instructions unchanged. An explicit integration takes precedence for the same Pi tool, including its custom behaviour and activation gate. Hidden and model-only tools are not imported.

Configure MCP servers once in Pi's built-in MCP extension. Its callable tools and resource helpers use the same bridge and remain discoverable in ALL_TOOLS. Pi's extension switches, tool restrictions and disabled servers are respected. Pi retains connection management, authentication, permissions and tool hooks; its native codemode extension is not required.

exec waits for pending MCP connections named in its source before starting the cell. Using ALL_TOOLS waits for all enabled servers. Names assembled dynamically or hidden in retained functions may not identify a server. Missing-tool errors identify the MCP namespace when known, otherwise flag ambiguous name prefixes. If that server connects, retry in a new exec cell. Repeated failures may require disabling that server. Calls are never retried automatically and servers are never disabled automatically.

MCP discovery starts from Pi's server summaries. Read, find or filter the synchronous ALL_TOOLS array for complete usage, schemas and server instructions. Each cell's catalogue contains tools connected when that cell starts. Custom and deferred tools use the same catalogue, not another discovery tool.

Notebook status and tool notices follow Pi's theme. Use Ctrl+O to expand or collapse them all, or click an individual notice in fullscreen mode.

MCP server tools return their complete result object, including content, structuredContent and isError. Use image(block) for image content. Individual MCP calls finish or cancel before the enclosing exec or wait returns; cells can yield between calls.

Notebook hooks

Pinned functions can react without another model call. Use the top-level notebook tool with { input: '{"action":"pin","names":["onToolResult"],"hook":"tool_result"}' }, not a call inside exec.

The handler receives { type: "tool_result", toolName, input, status, result?, error? } for subsequent tools.* calls. Filter by toolName. Input is captured before execution. Status is "success" for a returned result or "error" for a throw.

Handlers get independent snapshots and run in name order, awaited before the caller continues. Independent calls may overlap. Handlers cannot replace outcomes, and their own tool calls do not trigger more handlers. Failures are reported without changing the original result.

Use hook: "startup" for initialization after project, session and profile restoration, once per fresh kernel. It receives { type: "startup" }. Pinning does not invoke it. Import dependencies inside the function and recreate handles through globalThis. Pi tools cannot run during startup. Startup failures block execution, but unpin remains available.

Ordinary pins are passive. Omit hook to preserve its setting, use hook: false to remove it, or unpin. Hooks restore with the kernel. Other sessions' changes apply only on restoration. Hooks observe Notebook tool calls only. External side effects are not rolled back.

TOML custom tools

Custom tools pair a top-level TOML definition with a command accepting one string. Put them in:

~/.pi/agent/codex-conversion-custom-tools/
<project>/.pi/codex-conversion-custom-tools/

Promoted tools add one standing usage line. Deferred tools appear in the availability inventory, with complete contracts in ALL_TOOLS. Neither adds a per-tool provider schema.

See the disabled working examples and definition contract. For progressive skills, prefer pi-better-skills-tool. The legacy skills example requires --no-skills.

Voice uses your Pi OpenAI Codex login independently of the active model. The spoken model handles conversation and routes work. Pi keeps the tools, files and actual job.

Audio follows system defaults. Use voice.inputDevice or voice.outputDevice to pin an endpoint. Dictation puts an editable transcript in Pi's input.

Fresh installs use Cove for voice and Luna with high reasoning for context summarisation. Calls resume after transport drops. Refresh voice context summarizes and restarts voice at context rollovers or compaction, preserving mute and LAN ownership. If summarisation fails, the old call remains untouched.

Choose Primary voice and Alternate voice in the Voice tab or LAN UI. New calls use the primary voice. With Shepherdr, each voice transfer to another session alternates the voice and gives an arrival greeting. Reconnects and context refreshes keep the current voice. Defaults are Cove and Ember.

The voice prompt lives at ~/.pi/agent/REALTIME-SYSTEM-PROMPT.md. Trusted projects can append .pi/REALTIME-SYSTEM-PROMPT.md. Keep project instructions in AGENTS.md. Outdated prompts trigger a pointer to the bundled changelog, never an automatic rewrite of your customizations. Template and changelog paths appear in the Voice tab.

/codex voice realtime
/codex voice mute
/codex voice dictation
/codex voice stop
/codex voice server

/codex voice server starts GipPity over HTTPS and prints its addresses. Open one on your phone or another machine and accept the local certificate. Handy for a devbox without a mic, or talking to Pi remotely over Tailscale.

GipPity offers voice, mute, editable dictation, typed prompts, Pi activity and settled replies. Moving devices does not restart the host's voice call. It follows Pi's theme and can be saved as a phone app.

The server stops when its owning Pi session changes. It has no authentication. Use a trusted network.

GPT-6.1 Sol and GPT-6 Astra, Sol and Luna support Responses Lite and native reasoning updates. All default to 272K context in this provider. GPT-6.1 Sol supports reasoning from low through max, without off or minimal. Cost estimates use published Standard API rates, including cache reads, writes and the long-context tier above 272K input tokens.

Default scope covers Codex-like GPT routes and Responses providers listed under Additional providers. Switching to an unrelated model restores Pi's ordinary tools.

Voice, usage and image descriptions can use the Codex login while another provider's model is active. Image descriptions use GPT-6 Luna. The separate web and image-generation extensions also use that login independently.

Native compaction requires OpenAI Codex or an explicitly configured compatible passthrough. Unsupported states fail visibly or use Pi compaction. Enable Both before creating a checkpoint you need across providers, or convert it to Pi summary before switching.

Lite has graduated into this package and receives no updates after its final release. Remove it first because both packages share commands and configuration:

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

Your existing ~/.pi/agent/pi-codex-conversion.json still loads. Web search and image generation are now separate:

pi install npm:@howaboua/pi-codex-web-run
pi install npm:@howaboua/pi-codex-imagegen

The old canonical package's PATH mode and binaries are gone. Old settings normalize to the structured adapter. Use structured tools or Code Mode custom commands instead.

• No voice device: let the setup turn inspect endpoints, save the chosen IDs, then restart voice.
• GipPity microphone blocked: use Pi's HTTPS URL and accept its certificate. Browsers block microphones on plain LAN HTTP.
• Code Mode cannot start: its pinned host is prepared lazily and honors proxy environment variables. Pi reports setup failures.
• Bundled helper cannot run: build it on the target machine, set tools.customRustBinariesDir, then /reload. Do not replace system glibc. Web search and image generation need no native helper.
• Configured provider fails: it must implement its declared API. Proxy Responses Lite and native compaction require their respective backend contracts.

For anything stranger, clone the repository and ask your Clanka:

git clone https://github.com/IgorWarzocha/howaboua-pi-stuff.git
cd howaboua-pi-stuff
bun install
pi --no-extensions --no-skills -e ./packages/pi-codex-conversion

See UPSTREAM_SYNC.md, CHANGELOG.md and GitHub issues.

Pi extension API

Normal Pi registration is enough for automatic Code and Notebook access. Use this optional API to customize usage, blocking behavior, result conversion or rendering:

import {
	adaptToolForCodeMode,
	registerCodeModeExtensionTools,
} from "@howaboua/pi-codex-conversion/code-mode";

const registration = registerCodeModeExtensionTools(pi, () => [
	adaptToolForCodeMode(tool, { usage: "await tools.example(input)" }),
], {
	isActive: () => extensionRuntime.isActive(),
});
extensionRuntime.onActiveChange(() => registration.refresh());
pi.on("session_shutdown", () => registration.unregister());

See the complete example. Declare @howaboua/pi-codex-conversion 3.0.24 or newer as a peer dependency. Import lazily if your extension must work without Pi Codex.

Adapted tools retain Pi context, UI, schema, progress and rendering. JavaScript receives model-usable content. Code Mode owns nested-call preflight and translates non-JavaScript tool names consistently in prompts and ALL_TOOLS.

Activation is also sampled at normal session and input boundaries. Prompt, registry and outer-tool filtering then stay fixed through the run.

Working integrations include pi-ask for blocking UI, pi-better-skills-tool and pi-browser for freeform input, pi-codex-web-run and pi-codex-imagegen for namespaced structured results, and pi-shepherdr for activation and per-call blocking.

GPT prompt mode

The optional @howaboua/pi-codex-conversion/prompt-mode export provides registerGptPromptMode(pi, apply). The synchronous apply(active, context) callback selects your extension's own compact wording before prompt and tool capture. Re-register native definitions only when their text changes. Return their current name, promptSnippet and promptGuidelines so the prepared prompt uses the same metadata. Keep tool names, arguments and execution unchanged.

The returned registration exposes active for help and nested-tool providers, plus dispose(). Registration works in either load order and disposes on shutdown. Without an active PCC adapter the mode is false. Optional integrations should retain ordinary wording when the module is unavailable. Do not compress user content, project instructions or other extensions' text.

See PCC GPT prompt mode for the callback contract, preparation timing and an integration example.

Developer messages

import { sendCodexDeveloperMessage } from "@howaboua/pi-codex-conversion/developer-messages";

sendCodexDeveloperMessage(pi, "Re-evaluate the plan before editing.", {
	deliverAs: "steer",
	triggerTurn: false,
});

Messages persist in Pi's purple block and reach compatible Responses models as developer. Display metadata stays model-invisible. deliverAs accepts steer, followUp and nextTurn. triggerTurn can start an idle turn for the first two.

Sending without a compatible adapter throws, never falling back to a user message. Optional integrations can use trySendCodexDeveloperMessage, which returns false when the broker or adapter is unavailable. Delivery failures still throw.

Use trySendCodexDeveloperCustomMessage(pi, { customType, content, display, details }, options) to retain your renderer and restoration fields. Content must be nonempty text. Details must be a plain object or omitted. A copied details object gains the reserved @howaboua/pi-codex-conversion/developer-message key.

Lazy integrations should check that this export exists. Fall back to an ordinary custom message only on absence or false, never after a delivery error. Older brokers return false.

Persisted messages use ordinary Pi conversion on incompatible models and regain the developer role on compatible Responses models. Custom messages retain their renderer and restoration fields.

Nested tool hooks

Pi's tool_call and tool_result events see outer exec and wait, not nested calls. Subscribe separately:

import {
  registerCodeModeToolPreflight,
  registerCodeModeToolCompletion,
} from "@howaboua/pi-codex-conversion/code-mode-hooks";

const guard = registerCodeModeToolPreflight(pi, async (call) => {
  // Return { block: true, reason } to reject a nested call before execution.
});
const observer = registerCodeModeToolCompletion(pi, async (call) => {
  // Persist call.toolName, call.toolCallId, call.input, call.status and call.result.
});

Registrations expose available and dispose(), handle either load order and dispose on shutdown. The older code-mode-preflight import remains supported. Older preflight-only brokers lack completion.

Completion runs once when a recognized nested call settles. input precedes preparation. result is the full captured Pi result, including details and images, or the returned value when no Pi result was captured. Errors include status: "error", an error string and phase: "preflight" | "execution". Without a captured result, result is undefined. Failed calls may have side effects. Cancellation is visible through signal.aborted.

Subscribers receive independent structured clones and run in registration order, awaited even after cancellation. Settle promptly. Subscriber failures and uncloneable values go to stderr without changing the outcome. Preflight can block. Completion only observes and does not expand agent-visible output.

Context sharing

The optional context-sharing API does not require Shepherdr.

Its optional bindRelationship(ctx, relationship) method links a fresh worker's native Pi thread to its parent before the first task. Parent and worker keep distinct session IDs. This linkage is independent of shared notes and the sharing setting. Shepherdr binds fresh spawns automatically with subagentKind: "collab_spawn". Resume preserves linkage; forks do not inherit it. Check method availability on the live service. See the parent and worker relationship contract for the signature and lifecycle.

import { connectCodexContextSharing } from "@howaboua/pi-codex-conversion/context-sharing";

const connection = connectCodexContextSharing(pi);
// In a prepared parent session:
const service = connection.service;
if (!service?.canCreateChild(ctx)) return; // Otherwise launch an independent child.
// For local storage, register your host router and supply its routing descriptor.
const prepared = await service.createChild(ctx, { name: "worker", routing });
// Launch Pi normally and deliver binding through your integration.
// In the fresh, idle child, before sending its first task:
const adopted = await childService.bind(childCtx, prepared.binding);
// Back in the parent: verify the returned child identity, then finish adoption.
await prepared.adopt();

Pi owns session creation and persistence. createChild requires parental opt-in. bind accepts that explicit binding regardless of the child's setting for future spawns. It validates storage and account, rejecting used sessions or different existing bindings. describe(ctx) reports identity and storage. verify(ctx) checks Remote account compatibility.

For Local and Tree, register a router in each participant with registerRouter, pass its opaque routing descriptor to createChild, and route incoming requests through the target's service.execute(ctx, request, signal). Validate family membership, preserve errors and never write directly to another session file. Dispose the connection on shutdown.

The extension API guide covers the complete lifecycle, Board membership, external Notes ownership and existing-session attachment contracts.

Realtime announcements

Ask an active voice session to speak:

import { reportRealtimeVoicePrompt } from "@howaboua/pi-codex-conversion/realtime-voice";

const announcement = {
	id: "my-extension:finished",
	prompt: "Briefly tell the user that the task finished.",
};
reportRealtimeVoicePrompt(pi, { ...announcement, active: true });
reportRealtimeVoicePrompt(pi, { ...announcement, active: false });

For ongoing states, send active: true at the start and active: false at the end. For one-off announcements, send both immediately.

Normal development uses published Pi packages from bun install. To test upstream changes, build a Pi checkout and link it explicitly:

bun run pi:link-checkout -- /absolute/path/to/pi

This validates the built transcript exports and CLI, then replaces only this repository's Pi dependency links. Run bun install to restore manifest-resolved packages.

Build the extension and launch the checkout's CLI:

bun run --cwd packages/pi-codex-conversion build
PI_CHECKOUT="$(cd /absolute/path/to/pi && pwd -P)"
EXTENSION="$(pwd -P)/packages/pi-codex-conversion"
node "$PI_CHECKOUT/packages/coding-agent/dist/cli.js" \
  --no-extensions --no-skills -e "$EXTENSION"