README.md - DeepSeek-TUI-2026

返回 DeepSeek-TUI-2026

README.md

1	# DeepSeek TUI
2
3	> Terminal coding agent for DeepSeek V4. It runs from the `deepseek` command, streams reasoning blocks, edits local workspaces with approval gates, and includes an auto mode that chooses both model and thinking level per turn.
4
5	[简体中文 README](README.zh-CN.md)
6
7	## Install
8
9	`deepseek` is distributed as Rust binaries: the dispatcher command
10	(`deepseek`) and the companion TUI runtime (`deepseek-tui`). Pick whichever
11	install path you already use; they all put the same commands on your `PATH`.
12	The npm package is an installer/wrapper for the release binaries, not the
13	agent runtime itself.
14
15	```bash
16	# 1. npm — easiest if you already use Node. The package downloads the
17	# matching prebuilt Rust binaries from GitHub Releases.
18	npm install -g deepseek-tui
19
20	# 2. Cargo — no Node needed.
21	cargo install deepseek-tui-cli --locked # `deepseek` (entry point)
22	cargo install deepseek-tui --locked # `deepseek-tui` (TUI binary)
23
24	# 3. Homebrew — macOS package manager.
25	brew tap Hmbown/deepseek-tui
26	brew install deepseek-tui
27
28	# 4. Direct download — no package manager or toolchain.
29	# https://github.com/Hmbown/DeepSeek-TUI/releases
30	# Prebuilt for Linux x64/ARM64, macOS x64/ARM64, Windows x64.
31	```
32
33	> In mainland China, speed up the npm path with
34	> `--registry=https://registry.npmmirror.com`, or use the
35	> [Cargo mirror](#china--mirror-friendly-installation) below.
36
37	[![CI](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml)
38	[![npm](https://img.shields.io/npm/v/deepseek-tui)](https://www.npmjs.com/package/deepseek-tui)
39	[![crates.io](https://img.shields.io/crates/v/deepseek-tui-cli?label=crates.io)](https://crates.io/crates/deepseek-tui-cli)
40	[DeepWiki project index](https://deepwiki.com/Hmbown/DeepSeek-TUI)
41
42	![DeepSeek TUI screenshot](assets/screenshot.png)
43
44	---
45
46	## What Is It?
47
48	DeepSeek TUI is a coding agent that runs in your terminal. It can read and edit files, run shell commands, search the web, manage git, and coordinate sub-agents from a keyboard-driven TUI.
49
50	It is built around DeepSeek V4 (`deepseek-v4-pro` / `deepseek-v4-flash`), including 1M-token context windows, streaming reasoning blocks, and prefix-cache-aware cost reporting.
51
52	### Key Features
53
54	- Auto mode — `--model auto` / `/model auto` chooses both the model and thinking level for each turn
55	- Thinking-mode streaming — see DeepSeek reasoning blocks as the model works
56	- Full tool suite — file ops, shell execution, git, web search/browse, apply-patch, sub-agents, MCP servers
57	- 1M-token context — context tracking, manual or configured compaction, and prefix-cache telemetry
58	- Three modes — Plan (read-only explore), Agent (interactive with approval), YOLO (auto-approved)
59	- Reasoning-effort tiers — cycle through `off → high → max` with `Shift + Tab`
60	- Session save/resume — checkpoint and resume long-running sessions
61	- Workspace rollback — side-git pre/post-turn snapshots with `/restore` and `revert_turn`, without touching your repo's `.git`
62	- Durable task queue — background tasks can survive restarts
63	- HTTP/SSE runtime API — `deepseek serve --http` for headless agent workflows
64	- MCP protocol — connect to Model Context Protocol servers for extended tooling; please see [docs/MCP.md](docs/MCP.md)
65	- Native RLM (`rlm_query`) — run batched analysis through cheap `deepseek-v4-flash` children using the same API client
66	- LSP diagnostics — inline error/warning surfacing after every edit via rust-analyzer, pyright, typescript-language-server, gopls, clangd
67	- User memory — optional persistent note file injected into the system prompt for cross-session preferences
68	- Localized UI — `en`, `ja`, `zh-Hans`, `pt-BR` with auto-detection
69	- Live cost tracking — per-turn and session-level token usage and cost estimates; cache hit/miss breakdown
70	- Skills system — composable, installable instruction packs from GitHub with no backend service required
71
72	---
73
74	## How It's Wired
75
76	`deepseek` (dispatcher CLI) → `deepseek-tui` (companion binary) → ratatui interface ↔ async engine ↔ OpenAI-compatible streaming client. Tool calls route through a typed registry (shell, file ops, git, web, sub-agents, MCP, RLM) and results stream back into the transcript. The engine manages session state, turn tracking, the durable task queue, and an LSP subsystem that feeds post-edit diagnostics into the model's context before the next reasoning step.
77
78	See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full walkthrough.
79
80	---
81
82	## Quickstart
83
84	```bash
85	npm install -g deepseek-tui
86	deepseek --version
87	deepseek --model auto
88	```
89
90	Prebuilt binaries are published for Linux x64, Linux ARM64 (v0.8.8+), macOS x64, macOS ARM64, and Windows x64. For other targets (musl, riscv64, FreeBSD, etc.), see [Install from source](#install-from-source) or [docs/INSTALL.md](docs/INSTALL.md).
91
92	On first launch you'll be prompted for your [DeepSeek API key](https://platform.deepseek.com/api_keys). The key is saved to `~/.deepseek/config.toml` so it works from any directory without OS credential prompts.
93
94	You can also set it ahead of time:
95
96	```bash
97	deepseek auth set --provider deepseek # saves to ~/.deepseek/config.toml
98
99	export DEEPSEEK_API_KEY="YOUR_KEY" # env var alternative; use ~/.zshenv for non-interactive shells
100	deepseek
101
102	deepseek doctor # verify setup
103	```
104
105	If `deepseek doctor` says the rejected key came from `DEEPSEEK_API_KEY`, remove
106	the stale export from your shell startup file, open a fresh shell, then run
107	`deepseek auth set --provider deepseek`. Saved config keys take precedence over
108	the environment and are easier to rotate.
109
110	> To rotate or remove a saved key: `deepseek auth clear --provider deepseek`.
111
112	### Auto Mode
113
114	Use `deepseek --model auto` or `/model auto` when you want DeepSeek TUI to decide how much model and reasoning power a turn needs.
115
116	Auto mode controls two settings together:
117
118	- Model: `deepseek-v4-flash` or `deepseek-v4-pro`
119	- Thinking: `off`, `high`, or `max`
120
121	Before the real turn is sent, the app makes a small `deepseek-v4-flash` routing call with thinking off. That router looks at the latest request and recent context, then selects a concrete model and thinking level for the real request. Short/simple turns can stay on Flash with thinking off; coding, debugging, release work, architecture, security review, or ambiguous multi-step tasks can move up to Pro and/or higher thinking.
122
123	`auto` is local to DeepSeek TUI. The upstream API never receives `model: "auto"`; it receives the concrete model and thinking setting chosen for that turn. The TUI shows the selected route, and cost tracking is charged against the model that actually ran. If the router call fails or returns an invalid answer, the app falls back to a local heuristic. Sub-agents inherit auto mode unless you assign them an explicit model.
124
125	Use a fixed model or fixed thinking level when you want repeatable benchmarking, a strict cost ceiling, or a specific provider/model mapping.
126
127	### Linux ARM64 (Raspberry Pi, Asahi, Graviton, HarmonyOS PC)
128
129	`npm i -g deepseek-tui` works on glibc-based ARM64 Linux from v0.8.8 onward. You can also download prebuilt binaries from the [Releases page](https://github.com/Hmbown/DeepSeek-TUI/releases) and place them side by side on your `PATH`.
130
131	### China / Mirror-friendly Installation
132
133	If GitHub or npm downloads are slow from mainland China, use a Cargo registry mirror:
134
135	```toml
136	# ~/.cargo/config.toml
137	[source.crates-io]
138	replace-with = "tuna"
139
140	[source.tuna]
141	registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"
142	```
143
144	Then install both binaries (the dispatcher delegates to the TUI at runtime):
145
146	```bash
147	cargo install deepseek-tui-cli --locked # provides `deepseek`
148	cargo install deepseek-tui --locked # provides `deepseek-tui`
149	deepseek --version
150	```
151
152	Prebuilt binaries can also be downloaded from [GitHub Releases](https://github.com/Hmbown/DeepSeek-TUI/releases). Use `DEEPSEEK_TUI_RELEASE_BASE_URL` for mirrored release assets.
153
154	### Windows (Scoop)
155
156	[Scoop](https://scoop.sh) is a Windows package manager. Once installed, run:
157
158	```bash
159	scoop install deepseek-tui
160	```
161
162
163	<details id="install-from-source">
164	<summary>Install from source</summary>
165
166	Works on any Tier-1 Rust target — including musl, riscv64, FreeBSD, and older ARM64 distros.
167
168	```bash
169	# Linux build deps (Debian/Ubuntu/RHEL):
170	# sudo apt-get install -y build-essential pkg-config libdbus-1-dev
171	# sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel
172
173	git clone https://github.com/Hmbown/DeepSeek-TUI.git
174	cd DeepSeek-TUI
175
176	cargo install --path crates/cli --locked # requires Rust 1.88+; provides `deepseek`
177	cargo install --path crates/tui --locked # provides `deepseek-tui`
178	```
179
180	Both binaries are required. Cross-compilation and platform-specific notes: [docs/INSTALL.md](docs/INSTALL.md).
181
182	</details>
183
184	### Other API Providers
185
186	```bash
187	# NVIDIA NIM
188	deepseek auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"
189	deepseek --provider nvidia-nim
190
191	# Fireworks
192	deepseek auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"
193	deepseek --provider fireworks --model deepseek-v4-pro
194
195	# Self-hosted SGLang
196	SGLANG_BASE_URL="http://localhost:30000/v1" deepseek --provider sglang --model deepseek-v4-flash
197
198	# Self-hosted vLLM
199	VLLM_BASE_URL="http://localhost:8000/v1" deepseek --provider vllm --model deepseek-v4-flash
200	```
201
202	---
203
204	## What's New In v0.8.15
205
206	A community-driven stabilization release focused on auth recovery, Windows
207	terminals, Zed/ACP compatibility, setup friction, and clearer cost display.
208	[Full changelog](CHANGELOG.md).
209
210	- Friendlier auth recovery — runtime API-key failures now explain when the active key came only from `DEEPSEEK_API_KEY` and no saved config key is present
211	- Zed / ACP adapter — `deepseek serve --acp` exposes a local stdio Agent Client Protocol server for Zed and other compatible editors
212	- Windows terminal fixes — UTF-8 console setup, dispatcher resume handling, clipboard fallback, Ctrl+E composer behavior, and safer Windows mouse defaults
213	- Yuan cost display — set `cost_currency = "cny"` (or `yuan` / `rmb`) to show footer, `/cost`, `/tokens`, and notification summaries in CNY
214	- Setup and skill polish — workspace trust persists globally, plain Markdown `SKILL.md` files load correctly, global Agents/Cursor skill paths are discovered, and the TUI shows skills in slash autocomplete
215	- Reliability fixes — workspace-scoped `resume --last`, capped API `max_tokens`, endpoint diagnostics in `deepseek doctor`, npm `--version` fallback, and current-date turn metadata
216
217	---
218
219	## Usage
220
221	```bash
222	deepseek # interactive TUI
223	deepseek "explain this function" # one-shot prompt
224	deepseek --model deepseek-v4-flash "summarize" # model override
225	deepseek --model auto "fix this bug" # auto-select model + thinking
226	deepseek --yolo # auto-approve tools
227	deepseek auth set --provider deepseek # save API key
228	deepseek doctor # check setup & connectivity
229	deepseek doctor --json # machine-readable diagnostics
230	deepseek setup --status # read-only setup status
231	deepseek setup --tools --plugins # scaffold tool/plugin dirs
232	deepseek models # list live API models
233	deepseek sessions # list saved sessions
234	deepseek resume --last # resume the most recent session in this workspace
235	deepseek resume <SESSION_ID> # resume a specific session by UUID
236	deepseek fork <SESSION_ID> # fork a session at a chosen turn
237	deepseek serve --http # HTTP/SSE API server
238	deepseek serve --acp # ACP stdio adapter for Zed/custom agents
239	deepseek pr <N> # fetch PR and pre-seed review prompt
240	deepseek mcp list # list configured MCP servers
241	deepseek mcp validate # validate MCP config/connectivity
242	deepseek mcp-server # run dispatcher MCP stdio server
243	deepseek update # check for and apply binary updates
244	```
245
246	### Zed / ACP
247
248	DeepSeek can run as a custom Agent Client Protocol server for editors that
249	spawn local ACP agents over stdio. In Zed, add a custom agent server:
250
251	```json
252	{
253	"agent_servers": {
254	"DeepSeek": {
255	"type": "custom",
256	"command": "deepseek",
257	"args": ["serve", "--acp"],
258	"env": {}
259	}
260	}
261	}
262	```
263
264	The first ACP slice supports new sessions and prompt responses through your
265	existing DeepSeek config/API key. Tool-backed editing and checkpoint replay are
266	not exposed through ACP yet.
267
268	### Keyboard Shortcuts
269
270	\| Key \| Action \|
271	\|---\|---\|
272	\| `Tab` \| Complete `/` or `@` entries; while running, queue draft as follow-up; otherwise cycle mode \|
273	\| `Shift+Tab` \| Cycle reasoning-effort: off → high → max \|
274	\| `F1` \| Searchable help overlay \|
275	\| `Esc` \| Back / dismiss \|
276	\| `Ctrl+K` \| Command palette \|
277	\| `Ctrl+R` \| Resume an earlier session \|
278	\| `Alt+R` \| Search prompt history and recover cleared drafts \|
279	\| `Ctrl+S` \| Stash current draft (`/stash list`, `/stash pop` to recover) \|
280	\| `@path` \| Attach file/directory context in composer \|
281	\| `↑` (at composer start) \| Select attachment row for removal \|
282
283	Full shortcut catalog: [docs/KEYBINDINGS.md](docs/KEYBINDINGS.md).
284
285	---
286
287	## Modes
288
289	\| Mode \| Behavior \|
290	\| --- \| --- \|
291	\| Plan 🔍 \| Read-only investigation — model explores and proposes a plan (`update_plan` + `checklist_write`) before making changes \|
292	\| Agent 🤖 \| Default interactive mode — multi-step tool use with approval gates; model outlines work via `checklist_write` \|
293	\| YOLO ⚡ \| Auto-approve all tools in a trusted workspace; still maintains plan and checklist for visibility \|
294
295	---
296
297	## Configuration
298
299	User config: `~/.deepseek/config.toml`. Project overlay: `<workspace>/.deepseek/config.toml` (denied: `api_key`, `base_url`, `provider`, `mcp_config_path`). [config.example.toml](config.example.toml) has every option.
300
301	Key environment variables:
302
303	\| Variable \| Purpose \|
304	\|---\|---\|
305	\| `DEEPSEEK_API_KEY` \| API key \|
306	\| `DEEPSEEK_BASE_URL` \| API base URL \|
307	\| `DEEPSEEK_HTTP_HEADERS` \| Optional custom model request headers, e.g. `X-Model-Provider-Id=your-model-provider` \|
308	\| `DEEPSEEK_MODEL` \| Default model \|
309	\| `DEEPSEEK_PROVIDER` \| `deepseek` (default), `nvidia-nim`, `fireworks`, `sglang`, `vllm` \|
310	\| `DEEPSEEK_PROFILE` \| Config profile name \|
311	\| `DEEPSEEK_MEMORY` \| Set to `on` to enable user memory \|
312	\| `NVIDIA_API_KEY` / `FIREWORKS_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` \| Provider auth \|
313	\| `SGLANG_BASE_URL` \| Self-hosted SGLang endpoint \|
314	\| `VLLM_BASE_URL` \| Self-hosted vLLM endpoint \|
315	\| `NO_ANIMATIONS=1` \| Force accessibility mode at startup \|
316	\| `SSL_CERT_FILE` \| Custom CA bundle for corporate proxies \|
317
318	UI locale is separate from model language — set `locale` in `settings.toml`, use `/config locale zh-Hans`, or rely on `LC_ALL`/`LANG`. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) and [docs/MCP.md](docs/MCP.md).
319
320	---
321
322	## Models & Pricing
323
324	\| Model \| Context \| Input (cache hit) \| Input (cache miss) \| Output \|
325	\|---\|---\|---\|---\|---\|
326	\| `deepseek-v4-pro` \| 1M \| $0.003625 / 1M* \| $0.435 / 1M* \| $0.87 / 1M* \|
327	\| `deepseek-v4-flash` \| 1M \| $0.0028 / 1M \| $0.14 / 1M \| $0.28 / 1M \|
328
329	Legacy aliases `deepseek-chat` / `deepseek-reasoner` map to `deepseek-v4-flash`. NVIDIA NIM variants use your NVIDIA account terms.
330
331	DeepSeek Pro rates currently reflect a limited-time 75% discount, which remains valid until 15:59 UTC on 31 May 2026. After that time, the TUI cost estimator will revert to the base Pro rates.
332
333	> [!Note]
334	> For the latest DeepSeek-V4-Pro pricing, including the current 75% discount valid until 15:59 UTC on 31 May 2026, please consult the official [DeepSeek pricing page](https://api-docs.deepseek.com/zh-cn/quick_start/pricing). All rates listed in the README correspond to the officially published values.
335
336	---
337
338	## Publishing Your Own Skill
339
340	DeepSeek TUI discovers skills from workspace directories (`.agents/skills` → `skills` → `.opencode/skills` → `.claude/skills` → `.cursor/skills`) and global directories (`~/.agents/skills` → `~/.claude/skills` → `~/.deepseek/skills`). Each skill is a directory with a `SKILL.md` file:
341
342	```text
343	~/.agents/skills/my-skill/
344	└── SKILL.md
345	```
346
347	Frontmatter required:
348
349	```markdown
350	---
351	name: my-skill
352	description: Use this when DeepSeek should follow my custom workflow.
353	---
354
355	# My Skill
356	Instructions for the agent go here.
357	```
358
359	Commands: `/skills` (list), `/skill <name>` (activate), `/skill new` (scaffold), `/skill install github:<owner>/<repo>` (community), `/skill update` / `uninstall` / `trust`. Community installs from GitHub require no backend service. Installed skills appear in the model-visible session context; the agent can auto-select relevant skills via the `load_skill` tool when your task matches their descriptions.
360
361	---
362
363	## Documentation
364
365	\| Doc \| Topic \|
366	\|---\|---\|
367	\| [ARCHITECTURE.md](docs/ARCHITECTURE.md) \| Codebase internals \|
368	\| [CONFIGURATION.md](docs/CONFIGURATION.md) \| Full config reference \|
369	\| [MODES.md](docs/MODES.md) \| Plan / Agent / YOLO modes \|
370	\| [MCP.md](docs/MCP.md) \| Model Context Protocol integration \|
371	\| [RUNTIME_API.md](docs/RUNTIME_API.md) \| HTTP/SSE API server \|
372	\| [INSTALL.md](docs/INSTALL.md) \| Platform-specific install guide \|
373	\| [MEMORY.md](docs/MEMORY.md) \| User memory feature guide \|
374	\| [SUBAGENTS.md](docs/SUBAGENTS.md) \| Sub-agent role taxonomy and lifecycle \|
375	\| [KEYBINDINGS.md](docs/KEYBINDINGS.md) \| Full shortcut catalog \|
376	\| [RELEASE_RUNBOOK.md](docs/RELEASE_RUNBOOK.md) \| Release process \|
377	\| [LOCALIZATION.md](docs/LOCALIZATION.md) \| UI locale matrix & switching \|
378	\| [OPERATIONS_RUNBOOK.md](docs/OPERATIONS_RUNBOOK.md) \| Ops & recovery \|
379
380	Full Changelog: [CHANGELOG.md](CHANGELOG.md).
381
382	---
383
384	## Thanks
385
386	This project ships with help from a growing community of contributors:
387
388	- [merchloubna70-dot](https://github.com/merchloubna70-dot) — 28 PRs spanning features, fixes, and VS Code extension scaffolding (#645–#681)
389	- [WyxBUPT-22](https://github.com/WyxBUPT-22) — Markdown rendering for tables, bold/italic, and horizontal rules (#579)
390	- [loongmiaow-pixel](https://github.com/loongmiaow-pixel) — Windows + China install documentation (#578)
391	- [20bytes](https://github.com/20bytes) — User memory docs and help polish (#569)
392	- [staryxchen](https://github.com/staryxchen) — glibc compatibility preflight (#556)
393	- [Vishnu1837](https://github.com/Vishnu1837) — glibc compatibility improvements (#565)
394	- [shentoumengxin](https://github.com/shentoumengxin) — Shell `cwd` boundary validation (#524)
395	- [toi500](https://github.com/toi500) — Windows paste fix report
396	- [xsstomy](https://github.com/xsstomy) — Terminal startup repaint report
397	- [melody0709](https://github.com/melody0709) — Slash-prefix Enter activation report
398	- [lloydzhou](https://github.com/lloydzhou) and [jeoor](https://github.com/jeoor) — Compaction cost reports
399	- [Agent-Skill-007](https://github.com/Agent-Skill-007) — README clarity pass (#685)
400	- [woyxiang](https://github.com/woyxiang) — Windows Scoop install docs (#696)
401	- [wangfeng](mailto:wangfengcsu@qq.com) — Pricing/discount info update (#692)
402	- [zichen0116](https://github.com/zichen0116) — CODE_OF_CONDUCT.md (#686)
403	- [dfwqdyl-ui](https://github.com/dfwqdyl-ui) — model ID case-sensitivity compatibility report (#729)
404	- [Oliver-ZPLiu](https://github.com/Oliver-ZPLiu) — stale `working...` state bug report and Windows clipboard fallback (#738, #850)
405	- [reidliu41](https://github.com/reidliu41) — resume hint and workspace trust persistence fixes (#863, #870)
406	- [xieshutao](https://github.com/xieshutao) — plain Markdown skill fallback (#869)
407	- [GK012](https://github.com/GK012) — npm wrapper `--version` fallback (#885)
408	- Hafeez Pizofreude — SSRF protection in `fetch_url` and Star History chart
409	- Unic (YuniqueUnic) — Schema-driven config UI (TUI + web)
410	- Jason — SSRF security hardening
411
412	---
413
414	## Contributing
415
416	See [CONTRIBUTING.md](CONTRIBUTING.md). Pull requests welcome — check the [open issues](https://github.com/Hmbown/DeepSeek-TUI/issues) for good first contributions.
417
418	Support: [Buy me a coffee](https://www.buymeacoffee.com/hmbown).
419
420	> [!Note]
421	> Not affiliated with DeepSeek Inc.
422
423	## License
424
425	[MIT](LICENSE)
426
427	## Star History
428
429	[![Star History Chart](https://api.star-history.com/chart?repos=Hmbown/DeepSeek-TUI&type=date&legend=top-left)](https://www.star-history.com/?repos=Hmbown%2FDeepSeek-TUI&type=date&logscale=&legend=top-left)
430

430 lines MARKDOWN