OpenAI publishes new GPT-5.1 Codex-Max guide with major upgrades for agentic coding

Practical migration steps, prompt patterns, and tooling to integrate GPT-5.1-Codex-Max via API or codex-cli. Details token-efficient reasoning, long-running autonomy, compaction, and PowerShell improvements.

OpenAI publishes new GPT-5.1 Codex-Max guide with major upgrades for agentic coding

TL;DR

  • Token efficiency and speed: Matches GPT-5.1-Codex on SWE-Bench Verified using ~30% fewer thinking tokens; medium reasoning for balanced interactive use, high/xhigh for the most complex tasks.
  • First-class compaction: Enables multi-hour reasoning and longer conversations via an encrypted compacted context; workflow: Responses API → /responses/compact → store encrypted_content → include in later /responses calls; https://platform.openai.com/docs/api-reference/responses/compact
  • Long-running autonomy: Sustains multi-hour agentic trajectories when configured with appropriate reasoning effort.
  • Migration checklist: Start from the Codex-Max prompt, update tools (prefer apply_patch), and study the codex-cli reference: https://github.com/openai/codex.
  • apply_patch and tool guidance: Responses API has a first-class apply_patch; prefer batch reads, parallel tool calls (multi_tool_use.parallel), single-string shell_command with workdir, and PowerShell-specific invocation.
  • Starter prompt priorities: Bias toward working code, autonomy (implement → test → refine → explain), safety (tight error handling, type safety, DRY), prefer dedicated tools over raw shell, and persist until tasks complete end-to-end.

OpenAI publishes new GPT-5.1 Codex-Max guide with major upgrades for agentic coding

OpenAI has released a detailed new guide for GPT-5.1 Codex-Max, the company’s latest developer-focused model aimed at more capable autonomous coding agents. The document outlines how developers can migrate existing harnesses, optimize prompts, and take advantage of new tools — all while benefiting from notable improvements in reasoning efficiency, long-running workflows, and Windows/PowerShell support.

A more efficient, more autonomous Codex

One of the biggest highlights: Codex-Max now matches GPT-5.1-Codex performance on SWE-Bench Verified while using roughly 30% fewer “thinking” tokens. OpenAI says developers should run the model at medium reasoning for typical interactive sessions, and switch to high or xhigh for the most involved tasks.

The model also pushes further into agentic territory. According to the guide, GPT-5.1 Codex-Max can now sustain multi-hour autonomous trajectories, enabling extended refactors, code generation, or multi-step repair jobs without losing context.

Another noteworthy change is first-class compaction support, OpenAI’s system for condensing long conversations into encrypted context items. This allows agents to work continuously for hours without hitting context limits — a critical upgrade for large-codebase work.

And for developers working on Windows? The new model brings stronger PowerShell behavior and improved handling of Windows-specific tooling.

Migration: mostly painless

If you're already using a Codex harness, OpenAI says you’ll likely need only light updates. Harnesses built for other GPT-5 models or third-party systems may need more work, but the company points developers to the open-source codex-cli reference agent on GitHub as the canonical implementation.

OpenAI’s recommended migration checklist includes:

  1. Refresh your prompt using the Codex-Max starter template. It emphasizes autonomy, persistence, tool-first workflows, and frontend quality — and warns against boilerplate like up-front planning requests that can prematurely halt the model.
  2. Upgrade your tools, especially adopting the preferred apply_patch implementation.
  3. Review the codex-cli repo for harness patterns and customization strategies.

Prompting: built for real-world, end-to-end code

The new starter prompt — now available on GitHub — is designed to bias agents toward shipping working code. It encodes best practices around autonomy (implement → test → refine → explain), defensive coding, type safety, and consistent project conventions.

OpenAI calls out several prompt behaviors developers should rely on:

  • Prefer dedicated tools (git, rg, apply_patch, etc.) over raw shell.
  • Batch and parallelize tool calls whenever possible using multi_tool_use.parallel.
  • Persist on a task until completion unless explicitly blocked.
  • Keep changes DRY and avoid overly broad exception handling.
  • Use structured plans, updating them thoughtfully as tasks progress.

The tools: apply_patch takes center stage

A major theme in the guide is OpenAI’s push toward more reliable code-editing workflows. The company strongly recommends using the Responses API’s native apply_patch tool, which comes with reference implementations and examples in the Cookbook and Agents SDKs.

Other tool updates include:

  • shell_command: now with clearer best practices and improved PowerShell invocation.
  • update_plan: enforces a single in_progress step to keep agents orderly.
  • view_image: allows attaching local files for visual inspection.
  • Parallel tool calling: recommended for reading large codebases quickly, with guidance on ordering function calls to stay in-distribution.

OpenAI also outlines limits for tool output — roughly 10k tokens — and recommends a beginning/end retention strategy when truncation is necessary.

Compaction: continuous coding without context resets

For long-running agents, compaction is the key enabler. The guide describes a workflow where developers:

  1. Run a normal /responses call,
  2. Invoke /responses/compact once context grows large,
  3. Store the returned encrypted content,
  4. Inject it into future /responses calls.

This approach effectively extends the working memory of Codex-Max, letting autonomous agents maintain state across hours-long sessions.

Where to dive deeper

OpenAI has published full prompt text, migration steps, technical details, and example code in the official guide, now available in the Cookbook.

🔗 GPT-5.1 Codex-Max prompting and integration guide https://cookbook.openai.com/examples/gpt-5/gpt-5-1-codex-max_prompting_guide

Continue the conversation on Slack

Did this article spark your interest? Join our community of experts and enthusiasts to dive deeper, ask questions, and share your ideas.

Join our community