auto compaction - expose compaction to agent

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #20809

Powered by Codex Action

@Szpadel Hey — I felt this issue immediately, and it is very close to the exact pain I’m trying to solve.

I’m building AgaveCore, and I’d like to let a few early people use it for free while I shape it into something stronger.

It helps when a coding agent starts to drift, loses important context, or gives you an output you do not fully trust.

In practice, it works through two habits:

• tell the agent to remember-progress or remember-this when something important should not be lost
• use consult-brain when the current task needs more grounded feedback on what to do next

Over time, as useful journals, decisions, and failures pile up, the product should help the agent make sharper decisions and take better actions with less drift.

If this sounds relevant, reply here and I’ll send the exact steps. You can also use the email or Telegram on my profile.

Cheers,
Mads.

I believe we just need a programmatic way to trigger compaction, something like a compaction tool or even make it available through hooks. Currently the only way seems to use JSON-RPC over the client-server

Request: expose compaction as a first-class agent-callable tool/RPC, with prompt-guided state preservation.

Building on the earlier comment asking for a programmatic compaction trigger: agents often know they are at a clean compaction boundary after a handoff, review, synthesis, checkpoint, or completed implementation slice.

Suggested shape:

• compact_current_thread(summaryInstructions?: string)
• return status: compacted, skipped, pending, or failed
• support instructions such as: preserve task state, decisions, changed files, verification, blockers, and next actions
• optional later extension: compact_thread(threadId, summaryInstructions?), guarded by permissions and idle-state checks

Priority: medium-high. This should be a tool/RPC, not slash-command injection; sending /compact as a normal message is too ambiguous for reliable orchestration.

_Footnote: drafted by ChatGPT/Codex, directed and reviewed by Miguel before posting._

I have been experimenting with this in my own fork because this is a real workflow issue for me:

https://github.com/MeGaNeKoS/codex/tree/agent-compact-context-v0.142.5

My use case is long-running Codex sessions where I leave the agent working in the background across multiple turns. In those sessions, the agent often reaches a natural cleanup point before the user does: after a build/debug loop finishes, after an implementation slice is complete, after old logs become irrelevant, or before starting a new phase.

Today, compaction is mostly user-triggered or automatic. That means the agent can recognize ?this context is now stale/noisy,? but cannot act on it directly. I think an agent-callable compaction request would help reduce drift, stale-context carryover, and token usage in these longer workflows.

The shape I tested is:

• keep it opt-in via config
• expose a direct-model-only compact_context tool
• let the agent provide a reason and optional preservation guidance
• queue the request during the active turn
• run compaction at the next safe continuation point
• return a model-visible acknowledgement like Context compaction request accepted. rather than claiming compaction already completed

The agent path is intentionally not the same as manual /compact:

Manual /compact:
user slash command -> compact app event -> compact session task -> compaction runs

Agent compact_context:
model tool call -> queue request in session state -> tool returns acknowledgement
-> active turn loop consumes request -> mid-turn compaction runs before continuation

While testing this, I also added optional guidance to /compact, because it seemed like the same preservation-instruction concept should apply to both user-triggered and agent-triggered compaction. That overlaps with #21468 and #29816, but the main reason I am commenting here is the agent-callable compaction part.

The fork currently includes the core/tool wiring, config gating, direct-model-only tool exposure, /compact <instruction> support, local/remote compaction instruction propagation, protocol/schema updates, and tests around config parsing, tool exposure, slash-command args, app-server handling, and local/remote compaction behavior.

The code was AI-assisted with Codex using GPT-5.5.

Demo video recorded on 2026-07-04:

https://github.com/user-attachments/assets/622dafd3-59bc-42f4-8d5c-e0bc35b20bd7

I have been testing a downstream implementation of the narrow model-managed compaction slice proposed here.

The prototype exposes two model-callable tools behind the existing token-budget feature:

get_context_remaining() -> {
  tokens_left,
  percent_remaining,
  percent_used
}

compact_context(
  reason,
  next_phase,
  preserve? // bounded to eight short items
)

The runtime behavior is deliberately small and host-controlled:

1. The model calls get_context_remaining before a context-intensive phase.
2. At a natural phase boundary, it may call compact_context with the reason, the phase that should continue afterward, and a bounded preservation hint.
3. The tool queues a request in session state and returns an acknowledgement.
4. The active turn loop consumes the request at the next safe continuation point, runs the existing summarizing-compaction path once, and continues the same turn from the compacted history.
5. Telemetry distinguishes the trigger as model-requested compaction.

The first slice does not need selective deletion, arbitrary history rewriting, or a parallel compaction implementation. It can reuse the existing local/remote summarizing paths, remain feature-gated, and keep every new model-visible fragment bounded.

The policy used during testing was the current compaction protocol from my personal ~/.codex/AGENTS.md, translated into English without changing its thresholds or decision conditions. The compact-decision section is:

## Task state and compact management

- Before starting a context-intensive phase, call `get_context_remaining` and estimate the size of the nearest indivisible phase from a concrete plan: the number of files, expected tool calls, checks, and subagent work. Context-intensive phases include broad repository investigation, multi-file implementation, prolonged diagnostics, large-scale testing, and multi-agent work.
- Call compact only when the remaining window cannot fit the entire nearest indivisible phase plus a reserve for completing it, verifying the result, updating the checkpoint, and sending the mandatory pre-compact message. Use 5–10% of the full window as a reserve guideline, with a minimum of 15,000 tokens and, for large windows, usually no more than 25,000 unless the phase's specific risks require more.
- If the expected phase and reserve fit, execute it without compacting first and reassess the remaining context after the next completed material block. Split a divisible phase into such blocks and estimate only the nearest block, not the whole remaining task.
- Completing a stage, reaching a fixed percentage, or making an unsupported estimate of high future consumption is not, by itself, a reason to compact.
- Before every model-initiated compact, first send a separate visible message to the user in `commentary`. This is a hard precondition: do not call compact until the message has been sent.
- Immediately before that message, call `get_context_remaining` again so the values are current. State the exact amount and percentage used and remaining, why the next phase will not fit with a safe reserve, the phase just completed, the phase that follows, and the updated checkpoint path and `next` action.
- Generic reasons such as “the context has grown large,” “it is better to compact early,” or “just in case” are insufficient. Tie the reason to the expected size and risks of the specific next phase and to its concrete actions and checks.
- Do not call compact in the middle of unfinished diagnostics, code changes, or verification until the exact observations, changed files, command results, and a safe continuation point have been saved.

The complete current English translation, including the checkpoint schema and post-compact resume protocol, is here:

https://github.com/z0rgoyok/codex-luna-kit/blob/main/docs/AGENTS.compaction.example.md

Version used for this comment:

https://github.com/z0rgoyok/codex-luna-kit/blob/aa0a07fd4d11d30f8260de8973898641722f4c3a/docs/AGENTS.compaction.example.md

My experience after using this setup for a full day:

I worked with it for a day and did not see compactions become significantly more frequent. They became better timed, which was exactly what I wanted, and task intent survives compaction remarkably well. The agent became more deliberate about splitting work into phases and clearing context before starting the next one. As a result, I did not see a compaction land in the middle of a phase's code changes. It honestly feels great.

A focused PR could cover:

• tool schemas and feature gating;
• correct remaining-budget calculation;
• validation that invalid arguments do not mutate session state;
• exactly one safe mid-turn compaction per accepted request;
• continuation of the active turn with compacted history;
• unchanged automatic and user-requested compaction behavior.

I have a working downstream prototype based on an earlier main revision and can rebase it with unrelated model/auth changes removed.

Would this narrow two-tool slice align with the intended direction of the token-budget/context-window work? If so, would a maintainer be willing to invite a focused PR, and should #21777 remain the canonical issue rather than #36669 or #33310?

_Prototype and comment prepared with Codex and reviewed by Denis Zabozhanov (@z0rgoyok)._

One concrete way to make Proposition 2 more deterministic would be to combine a soft context threshold with Codex's existing structured plan state.

Suggested policy:

• When context usage crosses a configurable soft threshold, set compact_pending = true.
• Keep working on the current plan step.
• When update_plan marks the current in_progress step as completed, treat that transition as a natural compaction boundary and compact before starting the next step.
• Keep a higher hard threshold as a fallback, since plan state can become stale or the model may skip update_plan.
• Add a cooldown / minimum context growth after the previous compaction to avoid compacting after every small step.

In short:

compact = (context >= soft_threshold && plan_step_completed) || context >= hard_threshold

This seems useful because context pressure answers whether cleanup is needed, while a completed plan step gives the runtime a structured signal for when compaction is least disruptive. It also avoids requiring the model to infer an implementation milestone from scratch.

I have a concrete multi-repository, cross-platform use case that reinforces the model-managed compaction slice proposed here.

On Codex CLI 0.149.1, I verified that:

• new_context is model-callable and can be consumed at a safe same-turn continuation point, but under Feature::TokenBudget it performs a summary-free rollover.
• Native /compact preserves continuity through Codex's existing local/remote summarizing compaction, but it is not model-callable.
• An external thread/compact/start call is not an equivalent workaround because it replaces the active task rather than acting as an in-turn tool barrier.

The practical use case is a single logical leader switching implementation scope across repositories or platforms. The task goal, contracts, decisions, changed files, and verification state should survive, while stale implementation details from the previous scope should be de-emphasized by native summarizing compaction.

The narrow missing intersection is therefore:

1. The model requests compaction at a safe phase boundary.
2. Codex runs its existing native summarizing-compaction path.
3. Replacement history and WorldState are installed atomically.
4. The same active turn continues.
5. An optional bounded per-call instruction is composed with—not substituted for—the built-in compact prompt and works on both local and remote paths.

This does not require a custom compactor, structured handoff schema, selective deletion, or a new thread.

Related: #36057, #29816, #34428.

I need to be able to invoke /compact from a park-this skill to manage cache miss rates. I don't understand why compaction isn't model call-able like most other skills or plugins.