A terminal-native coding agent built around DeepSeek V4's 1M-token context and prefix cache. Single binary, no Node/Python runtime required — ships an MCP client, sandbox, and durable task queue out of the box.

简体中文 README

npm i -g deepseek-tui

DeepSeek TUI is a coding agent that runs entirely in your terminal. It gives DeepSeek's frontier models direct access to your workspace — reading and editing files, running shell commands, searching the web, managing git, and orchestrating sub-agents — all through a fast, keyboard-driven TUI.

Built for DeepSeek V4 (deepseek-v4-pro / deepseek-v4-flash) with 1M-token context windows and native thinking-mode (chain-of-thought) streaming. See the model's reasoning unfold in real time as it works through your tasks.

• Native RLM (rlm_query tool) — fans out 1–16 cheap deepseek-v4-flash children in parallel against the existing DeepSeek client for batched analysis, decomposition, or parallel reasoning
• Thinking-mode streaming — shows DeepSeek's chain-of-thought as it reasons about your code
• Full tool suite — file ops, shell execution, git, web search/browse, apply-patch, sub-agents, MCP servers
• 1M-token context — automatic intelligent compaction when context fills up
• Three interaction modes — Plan (read-only explore), Agent (interactive with approval), YOLO (auto-approved). Decomposition-first system prompts teach the model to checklist_write, update_plan, and spawn sub-agents before acting
• Reasoning-effort tiers — cycle through off → high → max with Shift+Tab
• Session save/resume — checkpoint and resume long sessions
• Workspace rollback — side-git pre/post-turn snapshots with /restore and revert_turn, without touching your repo's .git
• HTTP/SSE runtime API — deepseek serve --http for headless agent workflows
• MCP protocol — connect to Model Context Protocol servers for extended tooling; see docs/MCP.md
• Live cost tracking — per-turn and session-level token usage and cost estimates
• Dark theme — DeepSeek-blue palette

DeepSeek TUI's architecture follows a dispatcher → TUI → engine → tools pattern. The deepseek CLI binary is a lightweight dispatcher that parses subcommands and delegates to the deepseek-tui companion binary for interactive sessions. The TUI runs a ratatui-based interface that communicates with an async engine executing an agent loop: user input flows to the LLM via a streaming client (OpenAI-compatible Chat Completions), tool calls are extracted from the response and dispatched through a typed tool registry (shell, file ops, git, web, sub-agents, MCP), and results stream back into the transcript.

Behind the scenes, the engine manages session state, turn tracking, and a durable task queue. The LSP subsystem (crates/tui/src/lsp/) provides post-edit diagnostics by spawning language servers (rust-analyzer, pyright, etc.) and injecting errors into the model's context before the next reasoning step. A recursive language model (RLM) subsystem gives the agent a sandboxed Python REPL for batch classification and sub-LLM orchestration. See docs/ARCHITECTURE.md for the full walkthrough.

npm install -g deepseek-tui
deepseek

If GitHub or npm downloads are slow from mainland China, install the Rust crates through a Cargo registry mirror:

# ~/.cargo/config.toml
[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

Then install the canonical deepseek dispatcher and (optionally) the companion TUI binary:

cargo install deepseek-tui-cli --locked   # provides `deepseek`
cargo install deepseek-tui     --locked   # provides `deepseek-tui` (optional)
deepseek --version

You can also download prebuilt binaries directly from the GitHub Releases page when GitHub release assets are reachable. TUNA, rsproxy, Tencent COS, or Aliyun OSS mirrors can also be used with DEEPSEEK_TUI_RELEASE_BASE_URL when a mirrored release-asset directory is available.

On first launch you'll be prompted for your DeepSeek API key. You can also set it ahead of time:

# via CLI
deepseek login --api-key "YOUR_DEEPSEEK_API_KEY"

# via env var
export DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY"
deepseek

deepseek auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"
deepseek --provider nvidia-nim

# or per-process:
DEEPSEEK_PROVIDER=nvidia-nim NVIDIA_API_KEY="..." deepseek

deepseek auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"
deepseek --provider fireworks --model deepseek-v4-pro

# SGLang is self-hosted; auth is optional for localhost deployments.
SGLANG_BASE_URL="http://localhost:30000/v1" deepseek --provider sglang --model deepseek-v4-flash

git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI
cargo install --path crates/tui --locked   # requires Rust 1.85+

Quick patch on top of v0.8.6 to unblock copy/select.

The selection-tightening from v0.8.6 restricted copy/select to user and assistant message bodies, which made it impossible to copy text out of system notes, thinking blocks, or tool output. v0.8.7 drops that gate so the rendered transcript block is selectable end-to-end again.

Known issue in v0.8.7: deepseek update fails with no asset found for platform … because the platform-string mapping in the self-updater uses aarch64/x86_64 instead of the release artifact's arm64/x64 (#503). Until this is fixed in v0.8.8, update via:

npm i -g deepseek-tui          # or
cargo install deepseek-tui-cli --locked

Full changelog: CHANGELOG.md.

/init walks the workspace, auto-detects the project type (Cargo.toml, package.json, pyproject.toml, etc.), and writes a starter AGENTS.md with build/test commands, workspace layout, and conventions derived from git log. Re-running shows a diff of the proposed update without overwriting changes.

After every apply_patch/edit_file/write_file, the engine sends a textDocument/didChange to the LSP server and surfaces errors/warnings inline in the tool result. Configurable via /lsp on|off and the [lsp] config section. Currently supports rust-analyzer, pyright, typescript-language-server, gopls, and clangd.

deepseek update fetches the latest GitHub release, downloads the platform-correct binary with SHA256 verification, and atomically replaces the running binary. No more remembering cargo install or npm install -g.

/share exports the current session as a static HTML page and uploads it to a GitHub Gist via the gh CLI, producing a clickable URL you can paste anywhere.

README hero updated with intent statement and architecture summary. ARCHITECTURE.md cleaned up for v0.8.6 (swarm references removed, current crate map). CONTRIBUTING.md now has a "shape of a PR" section.

Full changelog: CHANGELOG.md.

fetch_url now validates target hostnames and IPs before connecting — localhost-only HTTP for loopback, DNS pinning for remote hosts, and blocked internal IP ranges. Contributed by Hafeez Pizofreude (#261) and Jason.

/config tui opens a forms-style config editor powered by schemaui. Bare /config opens the legacy native modal; /config web launches a browser surface (requires the web feature). Contributed by Unic (YuniqueUnic) via #365.

ApiProvider::DeepseekCN targets api.deepseeki.com for China-based users. Auto-detects when zh-* is the system locale on first run.

All writes to ~/.deepseek/ now go through write_atomic (tempfile + fsync + rename), preventing corruption from mid-write crashes.

spawn_supervised catches and logs task panics with crash dumps instead of silently dropping the task.

/config model deepseek-v4-flash, /config locale zh-Hans, etc. change settings live in-session without opening the editor.

Full changelog: CHANGELOG.md.

v0.8.5 shipped with help from these contributors:

• Hafeez Pizofreude — SSRF protection in fetch_url and Star History chart
• Unic (YuniqueUnic) — Schema-driven config UI (TUI + web)
• Jason — SSRF security hardening

Completed background shell jobs now release their live process and pipe handles as soon as completion is observed, while keeping the job record inspectable. This prevents long-running sessions from hitting Too many open files (os error 24), which could make checkpoint saves fail and cause shell spawning, message send, close, and Esc/cancel paths to lag or fail.

Windows gets a longer Python bootstrap readiness timeout for the REPL runtime tests, matching GitHub runner startup contention without weakening bootstrap failures on other platforms.

The README now includes a TUNA Cargo mirror setup and direct release asset guidance for users with slow GitHub/npm access.

New regression coverage proves completed background shell jobs drop their live process handles after exec_shell_wait.

Full changelog: CHANGELOG.md.

A running foreground command can now be moved to the background interactive session — press Ctrl+B while a command is executing to open shell controls, then either detach it (it continues running and can be polled with exec_shell_wait) or cancel the current turn.

New tool: exec_shell_cancel — cancel a specific background shell task by task_id, or cancel all running background tasks with all: true.

Cancel-aware exec_shell_wait — canceling a turn while exec_shell_wait is blocking now stops the wait but leaves the background task running.

Filenames containing multi-byte characters (e.g., dialogue_line__冰糖.mp3) no longer panic the matches_glob function — byte-index slicing was replaced with char_indices() boundary-safe iteration.

The fanout card no longer pre-seeds with zero-state workers, eliminating the "0 done · 0 running · 0 failed · N pending" vs sidebar "N running" contradiction. The sidebar now shows "dispatching N" before the first progress event arrives from a agent_swarm invocation.

Full changelog: CHANGELOG.md.

DeepSeek TUI now speaks your language. The new locale setting in settings.toml controls UI chrome — composer, history search, /config, help overlay, and status hints — without changing model output language.

Unsure what to pick? Run locale in your terminal; the first matching tag is used automatically.

Paste-burst detection catches rapid-key pastes in terminals that don't send bracketed-paste events — CRLF is normalized, and multiline pastes stay buffered until you stop typing. Configurable via paste_burst_detection.

Forgot that prompt you wrote an hour ago? Alt+R opens a live search across input history and recovered drafts. Type to filter, Enter to accept, Esc to restore what you were typing.

During a running turn, queued messages, pending steers, and context chips appear above the composer so you can see what will be sent next. Alt+↑ pops the last queued message back for editing.

/config now groups settings by section (Model, Permissions, Display, ...) with a live filter. ↑/↓ (or j/k when the filter is empty) navigate; Enter/e edit the selected row; Esc clears the filter or closes.

? (with empty input), F1, or Ctrl+/ opens a searchable help overlay. Type to filter commands and keybindings; multi-term searches act as AND.

Full history: CHANGELOG.md.

DeepSeek TUI targets DeepSeek V4 models with 1M-token context windows by default.

Legacy aliases deepseek-chat and deepseek-reasoner silently map to deepseek-v4-flash.

NVIDIA NIM hosted variants (deepseek-ai/deepseek-v4-pro, deepseek-ai/deepseek-v4-flash) use your NVIDIA account terms — no DeepSeek platform billing.

*DeepSeek lists the Pro rates above as a limited-time 75% discount valid until 2026-05-05 15:59 UTC; the TUI cost estimator falls back to base Pro rates after that timestamp.

deepseek                                      # interactive TUI
deepseek "explain this function"              # one-shot prompt
deepseek --model deepseek-v4-flash "summarize" # model override
deepseek --yolo                               # YOLO mode (auto-approve tools)
deepseek login --api-key "..."                # save API key
deepseek doctor                               # check setup & connectivity
deepseek doctor --json                        # machine-readable diagnostics
deepseek setup --status                       # read-only setup status
deepseek setup --tools --plugins              # scaffold local tool/plugin dirs
deepseek models                               # list live API models
deepseek sessions                             # list saved sessions
deepseek resume --last                        # resume latest session
deepseek serve --http                         # HTTP/SSE API server
deepseek mcp list                             # list configured MCP servers
deepseek mcp validate                         # validate MCP config/connectivity
deepseek mcp-server                           # run dispatcher MCP stdio server

~/.deepseek/config.toml — see config.example.toml for every option.

Key environment overrides:

Quick diagnostics: deepseek setup --status checks API key, MCP, sandbox, and .env state without network calls; deepseek doctor --json is suitable for CI; deepseek setup --tools --plugins scaffolds local tool and plugin directories.

DeepSeek context caching is automatic — when the API returns cache hit/miss token fields, the TUI includes them in usage and cost tracking.

Full reference: docs/CONFIGURATION.md and docs/MCP.md.

UI locale is separate from model language — set locale in settings.toml or via the LC_ALL/LANG environment variables. See docs/CONFIGURATION.md.

DeepSeek-TUI discovers skills from the active skills directory. Workspace-local .agents/skills wins when present, then ./skills, then the configured global directory (~/.deepseek/skills by default). Each skill is a directory with a SKILL.md file:

~/.deepseek/skills/my-skill/
└── SKILL.md

SKILL.md must start with YAML frontmatter:

---
name: my-skill
description: Use this when DeepSeek should follow my custom workflow.
---

# My Skill

Instructions for the agent go here.

Run /skills to list discovered skills, /skill <name> to activate one for the next message, or /skill new to use the bundled skill-creator helper. Installed skills are also listed in the model-visible session context so the agent can choose relevant skills when the user names them or when the task matches their descriptions.

DeepSeek-TUI can also install community skills directly from a GitHub repo, with no backend service in the loop:

1. Create a public GitHub repo with a SKILL.md at the root containing the usual --- frontmatter (name, description).
2. Multi-skill bundles use skills/<name>/SKILL.md instead — the installer picks the first match and names the install after the frontmatter name.
3. Push to main (or master); the installer fetches archive/refs/heads/main.tar.gz and falls back to master.tar.gz.
4. Users install via /skill install github:<owner>/<repo> — installs are gated by the [network] policy, validated for path traversal and size, and placed under ~/.deepseek/skills/<name>/.
5. Submit a PR to the curated index.json (default registry) to make the skill installable by name (/skill install <name>) instead of the GitHub spec.
6. Use /skill update <name>, /skill uninstall <name>, or /skill trust <name> for installed community skills. Trust is only needed when you want scripts bundled with a skill to be eligible for execution.

See CONTRIBUTING.md. Pull requests welcome!

Not affiliated with DeepSeek Inc.

MIT