Skip to content

Feature: generic /compact command, auto-compaction, and fork-aware conversations #4317

Closed as not planned
Closed as not planned
Feature: generic /compact command, auto-compaction, and fork-aware conversations#4317
Assignees
rekram1-node

Description

@riatzukiza
riatzukiza
opened on Nov 14, 2025

Summary

Add a provider-agnostic /compact command and auto-compaction support to opencode core, along with fork-aware conversation IDs that play nicely with Codex-style prompt_cache_key semantics.

Background

In openai/codex (codex-rs), compaction is a first-class feature:

  • codex-rs/core/src/compact.rs, core/src/tasks/compact.rs, and docs/slash_commands.md define:
    • A /compact slash command that summarizes conversation history.
    • An auto_compact_token_limit based on model metadata (openai_model_info.rs).
    • A SUMMARIZATION_PROMPT used to create a handoff summary.
  • Tests like core/tests/suite/compact_resume_fork.rs verify interactions between compaction, resume, and forks, especially with respect to prompt_cache_key.

In the Codex OAuth plugin for opencode:

  • We currently strip OpenCode’s own auto-compaction system prompts in CODEX_MODE because they reference a summary file path that doesn’t exist for our stateless ChatGPT backend.
  • We rely on store: false + include: ["reasoning.encrypted_content"] to preserve context, but we do not have a coherent /compact story at the host level.

Problem

Without core support for compaction and fork-aware conversation IDs:

  • Each provider has to reinvent compaction semantics (or avoid them entirely), leading to inconsistent behavior across backends.
  • Codex-style prompt_cache_key reuse across resume/fork flows is hard to get right because opencode doesn’t expose explicit fork events to providers.
  • The Codex plugin can emulate compaction internally, but it cannot:
    • Register a shared /compact slash command.
    • Coordinate auto-compaction decisions across sessions in a provider-agnostic way.

Proposed Changes

  1. Add a generic /compact command in opencode core

    • Define a new slash command (e.g. /compact) that:
      • Requests a summary of the current conversation from the active provider.
      • Replaces (or augments) conversation history with the returned summary so future turns operate on a compacted context.
    • Design the protocol so that providers receive a clear “compact this conversation” signal, not just a normal user message.

  2. Introduce autoCompactTokenLimit in core configuration

    • Add a per-provider and per-model autoCompactTokenLimit field in opencode’s config model (analogous to Codex’s auto_compact_token_limit).
    • Track approximate token usage per conversation (input + output), and when a configurable threshold is crossed:
      • Automatically trigger the compact action (e.g. run /compact under the hood) before sending the next user prompt.
    • Allow users to override or disable auto-compaction globally and per-project.

  3. Fork-aware conversation IDs and provider hooks

    • Extend the core session manager so that:
      • Conversations have explicit, stable IDs.
      • Forks (branching from an existing conversation) are modeled as first-class operations with parentConversationId and optional forkId/branchId.
    • Provide a provider hook (e.g. onConversationFork) that:
      • Allows providers to adjust their own cache keys (prompt_cache_key for Codex) when forks occur.
      • Enables Codex-like semantics where:
        • Overrides do not change prompt_cache_key.
        • Forks do generate new cache keys derived from the parent.

  4. Provider API surface for compaction

    • Define a provider capability flag (e.g. supportsCompaction) and a method like compactConversation(context) -> summary.
    • Implement this in the Codex plugin by:
      • Reusing the official compact prompt from Codex CLI or a close approximation.
      • Leveraging encrypted reasoning content to maintain continuity.
    • Other providers (OpenAI Platform, local models, etc.) can opt in with their own prompts.

Why This Belongs in Core

  • Compaction and conversation forking are cross-provider concerns: every backend has context limits and benefits from summarization.
  • A generic /compact command and auto-compaction framework let plugins focus on the prompt and model details instead of reimplementing session semantics.
  • Codex-specific details (like prompt_cache_key) become easier to integrate cleanly when opencode’s session model exposes the right hooks.

Acceptance Criteria

  • There is a new /compact command in opencode that providers can implement.
  • Configuration supports autoCompactTokenLimit (or similar) per provider/model.
  • Conversations and forks have explicit IDs exposed to providers.
  • Providers can implement fork-aware caching (Codex: prompt_cache_key, others: own fields) with clear lifecycle events.
  • The Codex OAuth plugin and at least one non-Codex provider are able to adopt the new compaction hooks in a consistent way.

Activity

  1. github-actions commented on Nov 14, 2025

    @github-actions
    github-actionsBot
    on Nov 14, 2025 – with GitHub Actions
    Contributor

    This issue might be a duplicate of existing issues. Please check:

    Feel free to ignore if none of these address your specific case.

  2. riatzukiza commented on Nov 14, 2025

    @riatzukiza
    riatzukiza
    on Nov 14, 2025
    ContributorAuthor

    Small clarification: opencode already exposes a '/compact' command, but today it works by injecting a provider-specific system prompt that assumes a file-based summary path (used by the existing OpenAI integration). From the Codex plugin's point of view, that behavior is tightly coupled to one provider implementation and can't be reused safely for the ChatGPT backend (we currently strip those prompts in CODEX_MODE for this reason).

    The intent of this feature request is not to add a brand-new command name, but to generalize the existing '/compact' command into a provider-agnostic capability with a structured hook, for example:

    • Core: expose a semantic 'compact this conversation' action and surface it as '/compact' in the UI.
    • Providers: implement a compactConversation(context) -> summary/updated-history hook (or similar) that maps this semantic action into whatever compaction prompt/state update makes sense for that backend.

    That way:

    • Existing behavior for the current OpenAI integration can be preserved under the same '/compact' name.
    • Providers like the Codex OAuth plugin can implement compaction in a way that works with a stateless ChatGPT backend (no shared summary file), instead of having to strip the host's compaction prompts.

    If it helps, I'm happy to draft a more concrete provider API shape for this (capability flag + hook signature) as a follow-up.

  3. rekram1-node
    added
    discussionUsed for feature requests, proposals, ideas, etc. Open discussion
    on Nov 14, 2025

  4. disarticulate commented on Mar 21, 2026

    @disarticulate
    disarticulate
    on Mar 21, 2026

    can opencode just autoclose all the issues, then open the ones they're actually going to work on.

    All these issues sitting stale because everyones generating issues instead of pushing pull requersts, etc. It'd make it easier to understand what opencode staff actually care about.

  5. alario-tang commented on Mar 31, 2026

    @alario-tang
    alario-tang
    on Mar 31, 2026

    I think the current compaction architecture is on the right track, but long-session robustness still feels limited by how reactive the recovery path is.

    After reading the current flow in:

    • packages/opencode/src/session/prompt.ts
    • packages/opencode/src/session/processor.ts
    • packages/opencode/src/session/compaction.ts

    the main pattern seems to be:

    1. run normally
    2. detect overflow after a step completes, or after provider-side context rejection
    3. switch into compaction
    4. stop if compaction itself still overflows

    That is clean, but probably leaves resilience on the table in tool-heavy or media-heavy sessions.

    The improvements that seem highest leverage to me are:

    • pre-request context governance, not only post-failure compaction
    • compaction self-retry when the compaction request itself exceeds context
    • a small repeated-failure circuit breaker to avoid retry loops
    • stronger post-compaction continuation guarantees so the next turn does not immediately degrade again

    The current processor.ts -> compaction.ts handoff is readable, so this feels like something that could be added incrementally rather than requiring a rewrite.

    I think the biggest missing piece is compaction self-retry. Right now if compaction overflows, the flow stops. A retry path that progressively drops the oldest rounds until the summary request fits would probably make pathological long sessions much more recoverable.

  6. thdxr
    assigned
    rekram1-node
    on May 3, 2026
  7. thdxr
    removed
    discussionUsed for feature requests, proposals, ideas, etc. Open discussion
    on May 3, 2026

  8. nilltadios commented on May 3, 2026

    @nilltadios
    nilltadios
    on May 3, 2026

    I think there is a narrower cache issue that fits under this broader provider-agnostic compaction work.

    Current /compact builds a special compaction request in packages/opencode/src/session/compaction.ts by converting history with stripMedia: true and toolOutputMaxChars: 2000, then appending the compaction prompt as the final user message.

    Appending the compaction prompt at the end is good for prefix caching, but rewriting the prior history can break provider prompt-cache prefix matches. For providers with discounted cached input, /compact can become much more expensive than a normal turn over the same session.

    A minimal fix might be:

    1. First attempt /compact with the same model-message history a normal chat turn would send.
    2. Append the compaction instruction as the final user message.
    3. If that overflows, fall back to the current stripped/truncated path.

    Related prior issues:

  9. github-actions commented on Jul 4, 2026

    @github-actions
    github-actionsBot
    on Jul 4, 2026 – with GitHub Actions
    Contributor

    To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

  10. github-actions
    closed this as not plannedon Jul 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions