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

> Explore DeepSeek TUI architecture discover how the dispatcher engine and tools framework manage events sessions and parallel execution using a modular registry system.

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

---

**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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/core/tool_parser.rs) extracts the tool signature from the LLM response
2. **Lookup**: [`crates/tui/src/tools/registry.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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:

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

```

The engine routes this to [`subagent/mod.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/tools/file.rs)) generated via macros for safe read/write/list operations, and network restrictions ([`crates/tui/src/network_policy.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/memory.rs) and [`crates/state/src/lib.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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:

```bash
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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/mcp.rs) allows external programs to drive TUI sessions. Launching the MCP server opens a communication channel:

```bash
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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/cli/src/lib.rs)) spawns the `deepseek-tui` engine to keep CLI operations lightweight
- **Central engine**: [`crates/tui/src/core/engine.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/core/engine.rs) orchestrates the event loop, session state, and tool execution
- **Tool framework**: [`crates/tui/src/tools/registry.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/tools/registry.rs) manages parallel tool calls with sandboxed execution via [`execpolicy/mod.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/execpolicy/mod.rs)
- **Session management**: Automatic compaction via [`compaction.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/compaction.rs) prevents memory exhaustion during long conversations
- **External integration**: The MCP server ([`mcp.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/tui/src/compaction.rs), replaces older turns with summary tokens, and rewrites the persistent state in [`crates/state/src/lib.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/crates/state/src/lib.rs), significantly reducing memory footprint for long-running conversations.