This is living internal context, not a feature specification or user contract. It records why pi-codex exists and how to judge future changes. Source, settings, README, and changelog own current behaviour. Update this file when the intent changes.
GPT coding models are trained around Codex prompts, tools, and transport. Pi is more extensible, but a mismatched harness can make GPT less effective while consuming more subscription quota.
pi-codex removes the choice between an efficient model-native environment and Pi's extension model, sessions, project context, skills, and UI. It gives GPT the Codex-shaped environment it knows without carrying Codex's fixed client or context overhead.
The intended user is a Pi power user. They want a complete environment rather than a kit they must assemble, but they understand enough about coding agents to value tool contracts, cache behaviour, context, and execution modes. pi-codex need not flatten those choices for beginners. Videos and writing can teach the ideas without enlarging the product or its model context.
Port model-facing Codex behaviour when it helps GPT work natively. Rethink it when Pi integration, extensibility, or quota efficiency demands something better. Do not copy every Codex workflow merely because it exists.
A new Codex feature belongs when it improves the essential experience or is likely to become part of the model's learned environment. Durable concepts eventually need only a small Pi-specific delta. Passing features and separately owned workflows can remain slash commands or other extensions. This boundary comes from real use and harness judgment, not a parity checklist.
pi-codex is also working evidence. It shows how capable GPT coding models can be, and how far a subscription can go, when prompts, schemas, caching, continuation, and compaction are engineered together.
The goal is a frictionless model environment for the fewest practical tokens.
- Preserve the model quality and behaviour available in Codex.
- Keep prompts, schemas, request shapes, and replay stable enough to retain cache hits and continuation.
- Preserve useful context instead of accumulating or aggressively flattening it for the sake of session length.
- Keep Pi and user-defined tools available without making every capability permanent provider context.
Assume GPT already knows durable Codex concepts. Prompt and tool text should contain the Pi delta, local capabilities, and corrections for observed failures. When a new model arrives, subtract first. Restore only what repeated real use proves necessary. Synthetic evaluations do not justify permanent instructions.
Normal cache preservation should be automatic when backend evidence shows it is safe and cost-effective. Keepalive is different: it spends requests while the user is idle, and a miss against a large context can cost more than expiry. Keep potentially expensive persistence explicit.
The spine is prompt, tools, request handling, transport, cache, continuation, replay, and context. Other capabilities earn their place by completing that environment:
- Structured Mode provides flat Codex-shaped tools over standard Responses.
- Code Mode and Responses Lite provide the model-native execution surface expected by supported GPT models.
- Notebook Mode extends Code Mode with persistent state and is the recommended experience.
- Web and image tools expose capabilities already included in the user's subscription.
- Native compaction integrates the provider's own context primitive.
- Realtime voice adds continuous control that Codex should provide but does not.
- Heavy prompt overwrite explores how little inherited Pi scaffold newer models need.
Recommendations are not coercion. Users choose the execution mode and optional features. Conservative defaults are an entry point, not the product's ceiling.
Code and Notebook Mode can compose tools locally behind the small exec contract. Promoted custom tools may add one compact usage line. Deferred tools add no tool-specific startup text until needed. The shipped examples are optional starting points.
Structured Responses tools are provider schemas and therefore consume context. Dynamic low-context discovery is a Code and Notebook property, not a missing Structured Mode feature.
Responses compaction V2 uses the provider's native checkpoint on the active Responses history. When possible, it reuses the working continuation and prompt-cache lane instead of paying to summarize the largest context through a fresh request.
Replay preserves the encrypted provider checkpoint, canonical output and tool history, a bounded tail of real user messages, and subsequent live work. Endpoint limits may require bounded tool-output truncation, but broad destructive trimming is not the goal.
Native compaction remains optional because its efficient checkpoint is not readable like a Pi prose summary. Users choose between inspectability and native cache, replay, and context fidelity.
Realtime voice turns Pi into a live, hands-free collaborator. The terminal remains the visual workspace and durable record. Voice is the continuous conversation and control surface.
Voice and Pi must feel like one assistant. Pi executes work and owns artifacts. Voice keeps the conversation alive.
The two sessions run concurrently. Tool calls, compaction, prewarm, and other ordered Pi work must not freeze speech. Dependency is per request: an answer that needs Pi may wait for Pi, while interruptions, corrections, and independent conversation remain immediate.
The realtime model is an intelligent speech interface, not the coding model. It may answer from known conversational context. It delegates actions, tools, unavailable facts, current project state, and substantial reasoning rather than extrapolating. It clarifies missed, cut-off, or materially ambiguous requests before delegation without interrogating harmless uncertainty.
A speakable Pi message must reach voice promptly. Long tool runs with no visible text may use completed reasoning summaries as progress, never full reasoning or spoken tool calls. Automatic delegation acknowledgements are optional because repetitive holding phrases quickly become irritating.
Once users learn that active work talks, unexplained silence looks like a frozen agent or broken voice. Reliable delivery of progress, blockers, failures, questions, and completion is functional behaviour.
Typed and spoken input control the same work. Starting voice must not disable the keyboard, TUI, tools, or other extensions. Typed turns and their results remain part of the spoken conversation without duplicate messages or cache damage.
Screenless use is first-class. Blind or disabled users, people away from their desk, and users connected through the LAN remote should be able to follow and steer work without seeing the terminal. Structured results reach voice as coherent units it can summarize; users can ask for more detail.
Other extensions may report a state for voice to acknowledge naturally. This is an enabling integration seam, not a prescribed notification framework.
Users own the realtime identity, tone, pacing, and presentation through a durable personal prompt, with optional trusted-project additions. Core one-assistant routing and honest delegation remain delicate product machinery. Prompt migrations preserve customization rather than overwriting it. Users who want to redesign the voice system can build from @howaboua/pi-gippity-control.
A clear spoken delegation has the same authority as typed input. Pi's normal safeguards still apply. Voice adds no approval ceremony. Finalized speech, replies, tools, and results remain in one Pi session for later review while partial recognition, duplicate transcripts, and routing internals stay hidden.
Optional context summarization seeds a call from current Pi work. Replacement calls can summarize current state again so a user need not reconstruct the conversation. Context seeding and automatic reconnect remain choices: some users prefer a bare start or a clean end to an abandoned session.
The GipPity LAN remote assumes a trusted LAN or user-controlled private network such as Tailscale. pi-codex does not own accounts, roles, enterprise access control, or the user's surrounding network security.
The broad aim is good GPT behaviour through any provider that implements the required contract. The deepest optimization targets OpenAI Codex subscriptions.
Provider names and routes are not backend identity. Renamed providers and work proxies may still carry genuine Codex traffic while adding monitoring, aggregation, or policy. They retain first-party behaviour.
Other backends may implement compatible Responses or Responses Lite contracts. pi-codex supports those declared contracts, not every provider's approximation. An incomplete backend owns its failure; do not accumulate provider-specific compatibility heuristics.
pi-codex owns GPT harness integration. It is not:
- a universal compatibility layer for every extension, terminal, provider quirk, or native environment
- a general UI, rendering, or theming framework
- an enterprise platform
- an alternate Pi distribution
- a menu that detaches transport, cache, compaction, and replay from the lifecycle that makes them reliable
Model-native names, schemas, and semantics outrank compatibility with unrelated extensions. Useful host options do not automatically belong in the model contract.
Support only combinations that can be used and troubleshot predictably. Documented rebinds, binary overrides, other extensions, and forks are valid answers for uncommon needs. Open source permits adaptation; it does not promise that every adaptation enters the maintained package.