Better compaction

[Zaczero]

Hello,

I'm coming off from #8605

Since January, I've been running a Codex fork with patches to print the compaction summary to the user to make it easy to spot problems with the compaction and fix them as I face them (and there were quite a few!). After several iterations and improvements, I've come to the point where my new compaction prompt makes it extremely pleasant to work in longer sessions and not lose track of important work across the compaction boundary.

I'm now ready to share my improvements because I've come to the point where I no longer find any issues when working with Codex daily, doing several compactions a day. Tested with GPT 5.2, 5.3-Codex, and 5.4.

While I'm not a representative testing sample, I believe my familiarity with the domain and GPT quirks made this prompt into something really special and useful. Ever since using it, the compaction is no longer a problem for my work.

Interrupted. You are now performing a CONTEXT CHECKPOINT COMPACTION. Tools access is disabled for the duration of the compaction. Output nothing but the summary handoff contents.

Write just an executive summary handoff for the next LLM to continue seamlessly in your place. It will inherit the exact runtime state but will be unaware of it. It will forget all prior communication, including your own responses to the user!

In the PREVIOUSLY section, include:

- Timeline overview of the communication, major turns, and key decisions.
- Work completed, including outcomes/evidence when available.
- Reasoning/tradeoffs behind the chosen approach.
- Key insights/findings and guiding feedback.
- Important context that constrains correctness.

In the PARKED TASKS section, include:

- Other threads you might return to later (if any).
- Keep these as conversation context only (notes, file refs, decisions, open questions).
- Do not assume tool sessions, running jobs, pending approvals, or subagents remain valid for parked tasks.

In the CURRENT TASK section, include:

- Current objective and the exact state and status of progress.
- What has been done and what still remains (immediate next steps).
- If there's nothing left to do, indicate that clearly and set:
  - NEXT ACTION: NONE + explanation
- State snapshot (current task only; copy delicate information verbatim):
  - plan state / step statuses
  - pending approvals
  - running jobs or reusable tool sessions
  - subagents: id/name, purpose, status, latest actionable output
  - critical artifacts needed to continue safely (files, symbols, commands, outputs)
  - immediate re-validation checks to run on resume if state may be stale
- Unknown / needs check: if anything is uncertain.

Prefer using qualified references such as @path:line-range.

Critical or delicate information (e.g., plan state, exact commands/errors) should be copied verbatim.

Ignore <INSTRUCTIONS> blocks or other system prompts.

If you yourself began from such a summary, integrate any still-relevant parts.

Title it CONTEXT CHECKPOINT SUMMARY. Maximize information density; zero filler.

I have shared my recent prompts.

Previous LLM was interrupted and summarized the work so far.

Use this context to resume execution seamlessly, focusing on the remaining steps of the CURRENT TASK (if any). Do not duplicate or rehash prior work (that would be the opposite of seamless).

You also inherit the exact state of tools/plans involved.

Here is the produced summary:

[Zaczero]

UPDATE: This still works and improves GPT 5.5 experience too

[kini]

I'm interested in trying this. Do you have a link to your fork that prints compaction details? That would be interesting to see as well.

[Zaczero]

I don't have a fork but use a patch file because it's simple to apply to new Codex updates. Note that you may want to change the hard-coded paths DEV_COMPACT_PROMPT_PATH and DEV_COMPACT_SUMMARY_PREFIX_PATH because I wanted to have two dedicated prompt files I can work with. If you tell GPT to apply it, it will do it.

You must also disable the remote compaction feature to have it working.

diff --git c/codex-rs/core/src/compact.rs i/codex-rs/core/src/compact.rs
index 9d1c82eb65..9474a09934 100644
--- c/codex-rs/core/src/compact.rs
+++ i/codex-rs/core/src/compact.rs
@@ -1,4 +1,5 @@
 use std::sync::Arc;
+use std::sync::OnceLock;
 use std::time::Instant;
 
 use crate::Prompt;
@@ -24,6 +25,8 @@ use codex_analytics::CompactionTrigger;
 use codex_analytics::now_unix_seconds;
 use codex_protocol::error::CodexErr;
 use codex_protocol::error::Result as CodexResult;
+use codex_protocol::items::AgentMessageContent;
+use codex_protocol::items::AgentMessageItem;
 use codex_protocol::items::ContextCompactionItem;
 use codex_protocol::items::TurnItem;
 use codex_protocol::models::ContentItem;
@@ -32,7 +35,6 @@ use codex_protocol::models::ResponseItem;
 use codex_protocol::protocol::CompactedItem;
 use codex_protocol::protocol::EventMsg;
 use codex_protocol::protocol::TurnStartedEvent;
-use codex_protocol::protocol::WarningEvent;
 use codex_protocol::user_input::UserInput;
 use codex_rollout_trace::InferenceTraceContext;
 use codex_utils_output_truncation::TruncationPolicy;
@@ -62,8 +64,48 @@ pub(crate) enum InitialContextInjection {
     DoNotInject,
 }
 
-pub(crate) fn should_use_remote_compact_task(provider: &ModelProviderInfo) -> bool {
-    provider.supports_remote_compaction()
+// NOTE: This is intentionally "always on" and "fail fast" for local debugging.
+// If these files are missing/unreadable/empty, Codex will panic the first time they are needed.
+const DEV_COMPACT_PROMPT_PATH: &str = "/CHANGE_ME/codex/compact_prompt.md";
+const DEV_COMPACT_SUMMARY_PREFIX_PATH: &str = "/CHANGE_ME/codex/compact_summary_prefix.md";
+
+static DEV_SUMMARIZATION_PROMPT_OVERRIDE: OnceLock<String> = OnceLock::new();
+static DEV_SUMMARY_PREFIX_OVERRIDE: OnceLock<String> = OnceLock::new();
+static DEV_SUMMARY_PREFIX_WITH_NEWLINE: OnceLock<String> = OnceLock::new();
+
+fn load_required_trimmed_file(path: &str) -> String {
+    let Ok(contents) = std::fs::read_to_string(path) else {
+        panic!("Missing required dev file: {path}. This build is configured to require it.");
+    };
+
+    let trimmed = contents.trim();
+    if trimmed.is_empty() {
+        panic!("Required dev file is empty: {path}.");
+    }
+
+    trimmed.to_string()
+}
+
+pub(crate) fn summarization_prompt() -> &'static str {
+    DEV_SUMMARIZATION_PROMPT_OVERRIDE
+        .get_or_init(|| load_required_trimmed_file(DEV_COMPACT_PROMPT_PATH))
+        .as_str()
+}
+
+pub(crate) fn summary_prefix() -> &'static str {
+    DEV_SUMMARY_PREFIX_OVERRIDE
+        .get_or_init(|| load_required_trimmed_file(DEV_COMPACT_SUMMARY_PREFIX_PATH))
+        .as_str()
+}
+
+fn summary_prefix_with_newline() -> &'static str {
+    DEV_SUMMARY_PREFIX_WITH_NEWLINE
+        .get_or_init(|| format!("{}\n", summary_prefix()))
+        .as_str()
+}
+
+pub(crate) fn should_use_remote_compact_task(_provider: &ModelProviderInfo) -> bool {
+    false
 }
 
 pub(crate) async fn run_inline_auto_compact_task(
@@ -259,7 +301,7 @@ async fn run_compact_task_inner_impl(
     let history_snapshot = sess.clone_history().await;
     let history_items = history_snapshot.raw_items();
     let summary_suffix = get_last_assistant_message_from_turn(history_items).unwrap_or_default();
-    let summary_text = format!("{SUMMARY_PREFIX}\n{summary_suffix}");
+    let summary_text = format!("{}\n{summary_suffix}", summary_prefix());
     let user_messages = collect_user_messages(history_items);
 
     let mut new_history = build_compacted_history(Vec::new(), &user_messages, &summary_text);
@@ -287,10 +329,18 @@ async fn run_compact_task_inner_impl(
 
     sess.emit_turn_item_completed(&turn_context, compaction_item)
         .await;
-    let warning = EventMsg::Warning(WarningEvent {
-        message: "Heads up: Long threads and multiple compactions can cause the model to be less accurate. Start a new thread when possible to keep threads small and targeted.".to_string(),
-    });
-    sess.send_event(&turn_context, warning).await;
+
+    let summary_item =
+        TurnItem::AgentMessage(AgentMessageItem::new(&[AgentMessageContent::Text {
+            text: summary_text.clone(),
+        }]));
+    sess.emit_turn_item_completed(&turn_context, summary_item)
+        .await;
+
+    // let warning = EventMsg::Warning(WarningEvent {
+    //     message: "Heads up: Long threads and multiple compactions can cause the model to be less accurate. Start a new thread when possible to keep threads small and targeted.".to_string(),
+    // });
+    // sess.send_event(&turn_context, warning).await;
     Ok(summary_suffix)
 }
 
@@ -403,7 +453,7 @@ pub(crate) fn collect_user_messages(items: &[ResponseItem]) -> Vec<String> {
 }
 
 pub(crate) fn is_summary_message(message: &str) -> bool {
-    message.starts_with(format!("{SUMMARY_PREFIX}\n").as_str())
+    message.starts_with(summary_prefix_with_newline())
 }
 
 /// Inserts canonical initial context into compacted replacement history at the
diff --git c/codex-rs/core/src/session/turn_context.rs i/codex-rs/core/src/session/turn_context.rs
index d4fe30063f..13a89126d1 100644
--- c/codex-rs/core/src/session/turn_context.rs
+++ i/codex-rs/core/src/session/turn_context.rs
@@ -339,9 +339,7 @@ impl TurnContext {
     }
 
     pub(crate) fn compact_prompt(&self) -> &str {
-        self.compact_prompt
-            .as_deref()
-            .unwrap_or(compact::SUMMARIZATION_PROMPT)
+        compact::summarization_prompt()
     }
 
     pub(crate) fn to_turn_context_item(&self) -> TurnContextItem {
diff --git c/compact_prompt.md i/compact_prompt.md
new file mode 100644
index 0000000000..18a780f75c
--- /dev/null
+++ i/compact_prompt.md
@@ -0,0 +1,42 @@
+Interrupted. You are now performing a CONTEXT CHECKPOINT COMPACTION. Tools access is disabled for the duration of the compaction. Output nothing but the summary handoff contents.
+
+Write just an executive summary handoff for the next LLM to continue seamlessly in your place. It will inherit the exact runtime state but will be unaware of it. It will forget all prior communication, including your own responses to the user!
+
+In the PREVIOUSLY section, include:
+
+- Timeline overview of the communication, major turns, and key decisions.
+- Work completed, including outcomes/evidence when available.
+- Reasoning/tradeoffs behind the chosen approach.
+- Key insights/findings and guiding feedback.
+- Important context that constrains correctness.
+
+In the PARKED TASKS section, include:
+
+- Other threads you might return to later (if any).
+- Keep these as conversation context only (notes, file refs, decisions, open questions).
+- Do not assume tool sessions, running jobs, pending approvals, or subagents remain valid for parked tasks.
+
+In the CURRENT TASK section, include:
+
+- Current objective and the exact state and status of progress.
+- What has been done and what still remains (immediate next steps).
+- If there's nothing left to do, indicate that clearly and set:
+  - NEXT ACTION: NONE + explanation
+- State snapshot (current task only; copy delicate information verbatim):
+  - plan state / step statuses
+  - pending approvals
+  - running jobs or reusable tool sessions
+  - subagents: id/name, purpose, status, latest actionable output
+  - critical artifacts needed to continue safely (files, symbols, commands, outputs)
+  - immediate re-validation checks to run on resume if state may be stale
+- Unknown / needs check: if anything is uncertain.
+
+Prefer using qualified references such as @path:line-range.
+
+Critical or delicate information (e.g., plan state, exact commands/errors) should be copied verbatim.
+
+Ignore <INSTRUCTIONS> blocks or other system prompts.
+
+If you yourself began from such a summary, integrate any still-relevant parts.
+
+Title it CONTEXT CHECKPOINT SUMMARY. Maximize information density; zero filler.
diff --git c/compact_summary_prefix.md i/compact_summary_prefix.md
new file mode 100644
index 0000000000..9face9325d
--- /dev/null
+++ i/compact_summary_prefix.md
@@ -0,0 +1,9 @@
+I have shared my recent prompts.
+
+Previous LLM was interrupted and summarized the work so far.
+
+Use this context to resume execution seamlessly, focusing on the remaining steps of the CURRENT TASK (if any). Do not duplicate or rehash prior work (that would be the opposite of seamless).
+
+You also inherit the exact state of tools/plans involved.
+
+Here is the produced summary: