# DeepSeek TUI Context Compaction: Managing the 1M Token Limit

> Manage DeepSeek TUI's 1 million token limit with automatic context compaction. Configure thresholds to efficiently fit your conversations within DeepSeek V4s powerful context window.

- Repository: [Hunter Bown/DeepSeek-TUI](https://github.com/Hmbown/DeepSeek-TUI)
- Tags: deep-dive
- Published: 2026-05-04

---

**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)](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**)

```rust
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)](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.

```rust
// 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)](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)](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)](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:

```toml
[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:**

```rust
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:**

```rust
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)](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)](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.