DeepSeek TUI Architecture: How the Dispatcher, Engine and Tool Framework Work Together

DeepSeek TUI implements a two-binary architecture where a lightweight dispatcher delegates to a dedicated TUI engine that orchestrates events, sessions, and parallel tool execution through a modular registry system.

DeepSeek TUI is a Rust-based terminal interface for interacting with Large Language Models. The DeepSeek TUI architecture cleanly separates the command-line dispatcher from the interactive engine, enabling lightweight CLI parsing while supporting heavy-weight features like sub-agent spawning and session compaction.

Two-Binary Architecture: Dispatcher and Engine

The project distributes two binaries: the public deepseek dispatcher and the deepseek-tui engine. This separation allows the dispatcher to remain minimal while the TUI handles complex UI logic.

The dispatcher logic resides in crates/cli/src/lib.rs. When you execute a command, it parses CLI flags (profile, provider, model) and resolves configuration. It then discovers the sibling TUI binary via sibling_tui_candidate and spawns it using std::process::Command, handing over all arguments.

This design ensures that resource-intensive operations—rendering the interface, managing WebSocket connections, and running tool sandboxes—occur in a separate process from the simple argument parsing and update-checking logic.

The Core TUI Engine

The interactive UI engine lives in crates/tui/src/core/engine.rs. It functions as the central nervous system, coordinating multiple subsystems through a unified event loop.

Event Loop and Session Management

The engine pulls user input, timer ticks, and tool callbacks, feeding them into a session managed by crates/tui/src/core/session.rs. The session maintains:

• Complete LLM message history
• Token usage tracking
• Compaction hooks for memory management

When the session grows beyond configurable thresholds (common with 1M-token context models), the engine triggers compaction via crates/tui/src/compaction.rs. This prunes stale entries by collapsing older turns into summary tokens, preserving logical flow while freeing RAM and disk space.

LLM Client Integration

API communication happens through crates/tui/src/llm_client/mod.rs. This module sends OpenAI-compatible requests to DeepSeek's /chat/completions endpoint and handles special "thinking" tokens required by V4 models. The client streams responses back to the engine for real-time display.

Execution Policy Engine

Before running potentially unsafe actions like shell commands, the engine consults crates/tui/src/execpolicy/mod.rs. This execution-policy engine applies user-defined rules (such as AskForApproval) to ensure commands meet security requirements before spawning subprocesses.

Tool Framework and Registry

Tools are first-class citizens in DeepSeek TUI. When the LLM emits a tool call, the engine orchestrates the request through a three-phase pipeline:

1. Parsing: core/tool_parser.rs extracts the tool signature from the LLM response
2. Lookup: crates/tui/src/tools/registry.rs maps the tool name to its Rust implementation
3. Execution: The engine runs the function in a sandboxed context, subject to the exec-policy

The tool registry supports parallel execution—the dispatcher can fire multiple tool-related RPCs in a single turn, which the engine aggregates and processes concurrently.

Sub-Agent Tool for Parallel Processing

The sub-agent tool (crates/tui/src/tools/subagent/mod.rs) spawns separate LLM instances for concurrent tasks. When the model decides a sub-task needs isolated reasoning, it emits a JSON payload:

{
  "tool_call_id": "123",
  "name": "subagent",
  "arguments": {"prompt": "Summarize the previous answer in plain English"}
}

The engine routes this to subagent/mod.rs, which spawns a new LLM process. The parent session receives the result as a normal message, enabling parallel reasoning without blocking the main UI.

File I/O and Network Policy Tools

Built-in tools include file operations (crates/tui/src/tools/file.rs) generated via macros for safe read/write/list operations, and network restrictions (crates/tui/src/network_policy.rs) that enforce outbound request policies.

Session Persistence and Memory Management

Long-running sessions store data through crates/tui/src/memory.rs and crates/state/src/lib.rs. These modules persist session snapshots, thread lists, and user-defined notes to disk.

To prevent unbounded growth, users can trigger manual compaction:

deepseek session compact --threshold 0.6

This invokes the compaction logic that rewrites the on-disk snapshot with condensed history, critical when working with models supporting million-token contexts.

MCP Server for External Control

The Multi-Client Protocol server in crates/tui/src/mcp.rs allows external programs to drive TUI sessions. Launching the MCP server opens a communication channel:

deepseek mcp --socket /tmp/deepseek.sock

External applications can then send commands (run, apply patch) over stdio or Unix sockets, enabling IDE integrations and automation scripts to control the TUI programmatically.

Configuration and Runtime Overrides

Configuration management lives in crates/config/src/lib.rs. The dispatcher supports CliRuntimeOverrides that allow temporary overrides of provider, model, or sandbox mode. These overrides pass through environment variables (such as DEEPSEEK_API_KEY_SOURCE) before the TUI binary receives them.

Summary

• Two-binary architecture: The deepseek dispatcher (crates/cli/src/lib.rs) spawns the deepseek-tui engine to keep CLI operations lightweight
• Central engine: crates/tui/src/core/engine.rs orchestrates the event loop, session state, and tool execution
• Tool framework: crates/tui/src/tools/registry.rs manages parallel tool calls with sandboxed execution via execpolicy/mod.rs
• Session management: Automatic compaction via compaction.rs prevents memory exhaustion during long conversations
• External integration: The MCP server (mcp.rs) provides stdio/socket control for third-party applications

Frequently Asked Questions

How does the dispatcher find the TUI binary?

The dispatcher uses sibling_tui_candidate logic in crates/cli/src/lib.rs to locate the deepseek-tui executable in the same directory as itself. It then spawns the TUI via std::process::Command with all original arguments preserved, ensuring the TUI receives identical CLI inputs.

What happens when a tool call requires user approval?

The engine consults crates/tui/src/execpolicy/mod.rs before executing sensitive tools. If the policy requires approval (such as AskForApproval), the UI pauses execution and prompts the user. Only after explicit confirmation does the engine invoke the actual Rust function from tools/registry.rs.

Can multiple tools run simultaneously?

Yes. The architecture supports parallel tool execution. The LLM can emit multiple tool calls in a single response turn, and the dispatcher runs them concurrently. Results aggregate back into the session history through crates/tui/src/core/session.rs, maintaining conversation coherence while improving throughput.

How do I compact a session manually?

Run the command deepseek session compact --threshold 0.6 to trigger the compaction engine. This walks the message history in crates/tui/src/compaction.rs, replaces older turns with summary tokens, and rewrites the persistent state in crates/state/src/lib.rs, significantly reducing memory footprint for long-running conversations.

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