DeepSeek TUI Context Compaction: Managing the 1M Token Limit

DeepSeek TUI automatically compacts conversation history using configurable token and message thresholds to stay within DeepSeek V4's 1 million token context window.

The DeepSeek TUI application, maintained in the Hmbown/DeepSeek-TUI repository, implements an intelligent context compaction system to prevent sessions from exceeding the DeepSeek V4 model's 1 million token limit. Rather than failing when the context window fills, the runtime proactively summarizes older messages while preserving critical context. This document explains the compaction mechanism, configuration options, and implementation details based on the actual source code.

How Context Compaction Works

The compaction system operates transparently during chat sessions. When the estimated token count or message count crosses defined thresholds, the engine triggers a summarization pass before sending the next request to the LLM.

The CompactionConfig Structure

At the heart of the system lies CompactionConfig, defined in [crates/tui/src/compaction.rs](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/compaction.rs#L20-L27). This struct holds user-controllable limits and the model name:

• enabled: Master switch for the compaction engine (default: true)
• token_threshold: Token limit that triggers compaction (default: 50,000)
• message_threshold: Message count limit that triggers compaction (default: 50)

use crate::compaction::CompactionConfig;

let cfg = CompactionConfig::default();
// enabled = true, token_threshold = 50_000, message_threshold = 50

Token Budget Calculation

The system employs a multi-step estimation strategy to predict token usage before sending requests to the API. In [crates/tui/src/compaction.rs](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/compaction.rs), two primary functions handle estimation:

1. estimate_tokens_for_message: Approximates tokens per message using roughly 4 characters per token, plus additional costs for tool calls and reasoning blocks.

2. estimate_input_tokens_conservative: Applies a × 3/2 multiplier to the raw count and adds fixed framing overhead, ensuring the estimate stays safely below the 1M hard limit.

// Conservative estimation prevents hitting the limit
pub fn estimate_input_tokens_conservative(messages: &[Message], system: Option<&SystemPrompt>) -> usize {
    // Implementation applies 1.5x safety margin
}

The Compaction Decision Logic

Each turn, the engine calls should_compact ([crates/tui/src/compaction.rs](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/compaction.rs#L76-L88)) to determine if compaction is necessary. This function calculates effective thresholds by subtracting the token cost of pinned messages (messages that must be preserved) from the configured limits. If the remaining unpinned messages exceed either threshold, compaction proceeds.

The Compaction Process

When should_compact returns true, the system executes a multi-phase preservation and summarization workflow.

Planning and Pinning Strategy

The plan_compaction function ([crates/tui/src/compaction.rs](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/compaction.rs#L50-L88)) intelligently selects which messages to preserve:

• Recent messages: The most recent turns remain untouched
• Working-set references: Any message mentioning a working-set file path
• Error messages: Critical for maintaining debugging context
• Tool-call artifacts: Essential for maintaining tool execution state

These pinned messages are exempt from summarization, while the remaining older content is marked for compression.

Execution and Summarization

The compact_messages_safe function ([crates/tui/src/compaction.rs](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/compaction.rs#L71-L84)) performs the actual compaction:

1. Sends unpinned messages to the LLM via create_summary
2. Generates a new system-prompt block containing the summary
3. Appends workflow context and a "pinned messages follow:" marker
4. Rebuilds the message list with the summary replacing the compacted history

This process includes retry logic for transient errors, ensuring the session remains stable even if the summarization request fails.

Configuration and Usage

DeepSeek TUI exposes both user-facing configuration and programmatic APIs for controlling compaction behavior.

User Configuration via TOML

Users can adjust compaction settings in ~/.deepseek/config.toml or workspace-local configuration files. The auto_compact flag (default ON) controls whether the UI automatically triggers compaction:

[compaction]
enabled = true          # Engine-level switch

auto_compact = false    # Disable UI-driven automatic compaction

token_threshold = 50000
message_threshold = 50

When auto_compact is disabled, the engine still calculates thresholds but requires manual intervention to trigger compaction.

Programmatic Control

Developers integrating with the TUI can force compaction or adjust thresholds at runtime:

Force manual compaction:

use crate::compaction::{compact_messages_safe, CompactionConfig};
use crate::client::DeepSeekClient;

async fn force_compact(client: &DeepSeekClient, msgs: &[Message]) -> anyhow::Result<()> {
    let cfg = CompactionConfig::default();
    let result = compact_messages_safe(client, msgs, &cfg, None, None, None).await?;
    println!("Compacted {} messages, used {} retries", 
             result.messages.len(), 
             result.retries_used);
    Ok(())
}

Adjust thresholds dynamically:

use crate::compaction::CompactionConfig;

let mut cfg = CompactionConfig::default();
cfg.token_threshold = 100_000;  // Raise to 100k tokens
cfg.message_threshold = 80;    // Allow more messages

UI Observability

During compaction, the UI displays status indicators. The widget in [crates/tui/src/tui/widgets/mod.rs](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/tui/widgets/mod.rs#L1479) shows compact-state labels, while [crates/tui/src/ui.rs](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/ui.rs#L3128-L3133) renders messages like "Context critical; compacting before send..." to inform users when summarization occurs.

Summary

• DeepSeek TUI context compaction prevents sessions from exceeding the DeepSeek V4 1M token limit through automatic summarization.
• The system uses CompactionConfig with default thresholds of 50,000 tokens and 50 messages to trigger compaction.
• Conservative token estimation applies a 1.5× safety multiplier to ensure the model never receives oversized contexts.
• Pinned messages (recent content, errors, tool calls, and working-set references) are preserved while older content is summarized.
• Users can disable auto_compact in ~/.deepseek/config.toml or programmatically adjust thresholds via the Rust API.

Frequently Asked Questions

What triggers context compaction in DeepSeek TUI?

Context compaction triggers when should_compact detects that unpinned messages exceed either the token_threshold (default 50,000) or message_threshold (default 50). The check runs before each LLM request, comparing the conservative token estimate against these limits after accounting for pinned message costs.

How does DeepSeek TUI estimate token usage?

The system estimates tokens using estimate_tokens_for_message, which applies a rough 4:1 character-to-token ratio plus overhead for tool calls. It then calls estimate_input_tokens_conservative, which multiplies the total by 1.5 and adds framing overhead to create a safety buffer against the 1 million token limit.

Can I manually trigger compaction instead of using auto-compact?

Yes. Set auto_compact = false in your ~/.deepseek/config.toml file under the [compaction] section. Then use the programmatic API by calling compact_messages_safe with your DeepSeekClient instance, passing the message slice and configuration to force immediate compaction.

What messages are preserved during compaction?

The plan_compaction function preserves recent messages, any message referencing a working-set file path, error messages, and tool-call artifacts. These pinned messages remain in full form while the engine summarizes older, unpinned content to maintain conversational coherence within the token budget.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}