Agentic Context Pruning (ACP)

Automatically reduces token usage in OpenCode by intelligently managing conversation context.

Installation

Add to your OpenCode config:

// opencode.jsonc
{
    "plugin": ["@tuanhung303/opencode-acp@latest"],
}

Using @latest ensures you always get the newest version automatically when OpenCode starts.

Restart OpenCode. The plugin will automatically start optimizing your sessions.

How ACP Works

ACP hooks into OpenCode's message flow to intelligently reduce context size before sending to the LLM:

flowchart LR
    subgraph OpenCode["OpenCode Core"]
        direction TB
        A[User Message] --> B[Session]
        B --> C[Transform Hook]
        C --> D[toModelMessages]
        D --> E[LLM Provider]
    end

    subgraph ACP["ACP Plugin"]
        direction TB
        C --> F[syncToolCache]
        F --> G[injectHashes]
        G --> H[Apply Strategies]
        H --> I[prune]
        I --> C
    end

    %% Arctic Clarity Color Palette (Lightened)
    style OpenCode fill:#F4F7F9,stroke:#5A6B8A,stroke-width:1.5px,color:#1E2A36
    style ACP fill:#E8F5F2,stroke:#9AC4C0,stroke-width:1.5px,color:#1E2A36
    style A fill:#FAFCFD,stroke:#D0D8E0,stroke-width:1px,color:#2D3E50
    style B fill:#FAFCFD,stroke:#D0D8E0,stroke-width:1px,color:#2D3E50
    style C fill:#FAFCFD,stroke:#D0D8E0,stroke-width:1px,color:#2D3E50
    style D fill:#FAFCFD,stroke:#D0D8E0,stroke-width:1px,color:#2D3E50
    style E fill:#FAFCFD,stroke:#D0D8E0,stroke-width:1px,color:#2D3E50
    style F fill:#F5FAF9,stroke:#A8C9C5,stroke-width:1px,color:#1E2A36
    style G fill:#F5FAF9,stroke:#A8C9C5,stroke-width:1px,color:#1E2A36
    style H fill:#F5FAF9,stroke:#A8C9C5,stroke-width:1px,color:#1E2A36
    style I fill:#F5FAF9,stroke:#A8C9C5,stroke-width:1px,color:#1E2A36

ACP uses multiple tools and strategies to reduce context size:

Tools

Discard — Exposes a discard tool that the AI can call to remove completed or noisy tool content from context.

Distill — Exposes a distill tool that the AI can call to distill valuable context into concise summaries before removing the tool content.

Strategies

Deduplication — Identifies repeated tool calls (e.g., reading the same file multiple times) and keeps only the most recent output. Runs automatically on every request with zero LLM cost.

Supersede Writes — Prunes write tool inputs for files that have subsequently been read. When a file is written and later read, the original write content becomes redundant since the current file state is captured in the read result. Runs automatically on every request with zero LLM cost.

Purge Errors — Prunes tool inputs for tools that returned errors after a configurable number of turns (default: 4). Error messages are preserved for context, but the potentially large input content is removed. Runs automatically on every request with zero LLM cost.

Todo Reminder — Monitors the agent's todo list activity. If the agent hasn't updated their todos for a configurable number of turns, a reminder is injected into the conversation prompting them to review and update their task list. This helps keep the agent focused and organized during long sessions.

Your session history is never modified—ACP replaces pruned content with placeholders before sending requests to your LLM.

Impact on Prompt Caching

LLM providers like Anthropic and OpenAI cache prompts based on exact prefix matching. When ACP prunes a tool output, it changes the message content, which invalidates cached prefixes from that point forward.

Trade-off: You lose some cache read benefits but gain larger token savings from reduced context size and performance improvements through reduced context poisoning. In most cases, the token savings outweigh the cache miss cost—especially in long sessions where context bloat becomes significant.

Note: In testing, cache hit rates were approximately 65% with ACP enabled vs 85% without.

Best use case: Providers that count usage in requests, such as Github Copilot and Google Antigravity have no negative price impact.

Configuration

ACP uses its own config file:

• Global: ~/.config/opencode/acp.jsonc (or acp.json), created automatically on first run
• Custom config directory: $OPENCODE_CONFIG_DIR/acp.jsonc (or acp.json), if OPENCODE_CONFIG_DIR is set
• Project: .opencode/acp.jsonc (or acp.json) in your project's .opencode directory

{
    "$schema": "https://raw.githubusercontent.com/opencode-acp/opencode-acp/master/acp.schema.json",
    // Enable or disable the plugin
    "enabled": true,
    // Enable debug logging to ~/.config/opencode/logs/acp/
    "debug": false,
    // Notification display: "off", "minimal", or "detailed"
    "pruneNotification": "detailed",
    // Slash commands configuration
    "commands": {
        "enabled": true,
        // Additional tools to protect from pruning via commands (e.g., /acp sweep)
        "protectedTools": [],
    },
    // Protect from pruning for <turns> message turns
    "turnProtection": {
        "enabled": false,
        "turns": 4,
    },
    // Protect file operations from pruning via glob patterns
    // Patterns match tool parameters.filePath (e.g. read/write/edit)
    "protectedFilePatterns": [],
    // LLM-driven context pruning tools
    "tools": {
        // Shared settings for all prune tools
        "settings": {
            // Additional tools to protect from pruning
            "protectedTools": [],
        },
        // Removes tool content from context without preservation (for completed tasks or noise)
        "discard": {
            "enabled": true,
        },
        // Distills key findings into preserved knowledge before removing raw content
        "distill": {
            "enabled": true,
            // Show distillation content as an ignored message notification
            "showDistillation": false,
        },
        // Reminds agent to review/update todo list when stale
        "todoReminder": {
            "enabled": true,
            // Turns before first reminder (default: 12)
            "initialTurns": 12,
            // Turns between subsequent reminders (default: 6)
            "repeatTurns": 6,
        },
    },
    // Automatic pruning strategies
    "strategies": {
        // Remove duplicate tool calls (same tool with same arguments)
        "deduplication": {
            "enabled": true,
            // Additional tools to protect from pruning
            "protectedTools": [],
        },
        // Prune write tool inputs when the file has been subsequently read
        "supersedeWrites": {
            "enabled": false,
        },
        // Prune tool inputs for errored tools after X turns
        "purgeErrors": {
            "enabled": true,
            // Number of turns before errored tool inputs are pruned
            "turns": 4,
            // Additional tools to protect from pruning
            "protectedTools": [],
        },
    },
}

Commands

ACP provides a /acp slash command:

• /acp — Shows available ACP commands
• /acp context — Shows a breakdown of your current session's token usage by category (system, user, assistant, tools, etc.) and how much has been saved through pruning.
• /acp stats — Shows cumulative pruning statistics across all sessions.
• /acp sweep — Prunes all tools since the last user message. Accepts an optional count: /acp sweep 10 prunes the last 10 tools. Respects commands.protectedTools.

Turn Protection

When enabled, turn protection prevents tool outputs from being pruned for a configurable number of message turns. This gives the AI time to reference recent tool outputs before they become prunable. Applies to both discard and distill tools, as well as automatic strategies.

Todo Reminder

When enabled, ACP monitors the agent's todo list activity. If the agent hasn't updated their todos for a configurable number of turns, a reminder is injected into the conversation prompting them to review and update their task list.

• First reminder: After 12 turns of inactivity (configurable via initialTurns)
• Subsequent reminders: Every 6 turns until agent updates (configurable via repeatTurns)
• Prunable: The reminder is appended to assistant messages and can be discarded like any other content
• Only with pending todos: Reminders only appear when there are pending or in_progress todos

The reminder resets when todowrite is called—todoread alone does not reset the counter.

Protected Tools

By default, these tools are always protected from pruning across all strategies: task, todowrite, todoread, discard, distill, batch, write, edit, plan_enter, plan_exit

The protectedTools arrays in each section add to this default list.

Config Precedence

Settings are merged in order: Defaults → Global (~/.config/opencode/acp.jsonc) → Config Dir ($OPENCODE_CONFIG_DIR/acp.jsonc) → Project (.opencode/acp.jsonc). Each level overrides the previous, so project settings take priority over config-dir and global, which take priority over defaults.

Restart OpenCode after making config changes.

Limitations

Subagents — ACP is disabled for subagents. Subagents are not designed to be token efficient; what matters is that the final message returned to the main agent is a concise summary of findings. ACP's pruning could interfere with this summarization behavior.

License

MIT