DeepSeek TUI

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.

简体中文 README

Install

deepseek is distributed as Rust binaries: the dispatcher command (deepseek) and the companion TUI runtime (deepseek-tui). Pick whichever install path you already use; they all put the same commands on your PATH. The npm package is an installer/wrapper for the release binaries, not the agent runtime itself.

# 1. npm — easiest if you already use Node. The package downloads the
#    matching prebuilt Rust binaries from GitHub Releases.
npm install -g deepseek-tui

# 2. Cargo — no Node needed.
cargo install deepseek-tui-cli --locked   # `deepseek` (entry point)
cargo install deepseek-tui     --locked   # `deepseek-tui` (TUI binary)

# 3. Homebrew — macOS package manager.
brew tap Hmbown/deepseek-tui
brew install deepseek-tui

# 4. Direct download — no package manager or toolchain.
#    https://github.com/Hmbown/DeepSeek-TUI/releases
#    Prebuilt for Linux x64/ARM64, macOS x64/ARM64, Windows x64.

In mainland China, speed up the npm path with --registry=https://registry.npmmirror.com, or use the Cargo mirror below.

DeepWiki project index

---

What Is It?

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.

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.

Key Features

• Auto mode — --model auto / /model auto chooses both the model and thinking level for each turn
• Thinking-mode streaming — see DeepSeek reasoning blocks as the model works
• Full tool suite — file ops, shell execution, git, web search/browse, apply-patch, sub-agents, MCP servers
• 1M-token context — context tracking, manual or configured compaction, and prefix-cache telemetry
• Three modes — Plan (read-only explore), Agent (interactive with approval), YOLO (auto-approved)
• Reasoning-effort tiers — cycle through off → high → max with Shift + Tab
• Session save/resume — checkpoint and resume long-running sessions
• Workspace rollback — side-git pre/post-turn snapshots with /restore and revert_turn, without touching your repo's .git
• Durable task queue — background tasks can survive restarts
• HTTP/SSE runtime API — deepseek serve --http for headless agent workflows
• MCP protocol — connect to Model Context Protocol servers for extended tooling; please see docs/MCP.md
• Native RLM (rlm_query) — run batched analysis through cheap deepseek-v4-flash children using the same API client
• LSP diagnostics — inline error/warning surfacing after every edit via rust-analyzer, pyright, typescript-language-server, gopls, clangd
• User memory — optional persistent note file injected into the system prompt for cross-session preferences
• Localized UI — en, ja, zh-Hans, pt-BR with auto-detection
• Live cost tracking — per-turn and session-level token usage and cost estimates; cache hit/miss breakdown
• Skills system — composable, installable instruction packs from GitHub with no backend service required

---

How It's Wired

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.

See docs/ARCHITECTURE.md for the full walkthrough.

---

Quickstart

npm install -g deepseek-tui
deepseek --version
deepseek --model auto

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 or docs/INSTALL.md.

On first launch you'll be prompted for your DeepSeek API key. The key is saved to ~/.deepseek/config.toml so it works from any directory without OS credential prompts.

You can also set it ahead of time:

deepseek auth set --provider deepseek   # saves to ~/.deepseek/config.toml

export DEEPSEEK_API_KEY="YOUR_KEY"      # env var alternative; use ~/.zshenv for non-interactive shells
deepseek

deepseek doctor                         # verify setup

If deepseek doctor says the rejected key came from DEEPSEEK_API_KEY, remove the stale export from your shell startup file, open a fresh shell, then run deepseek auth set --provider deepseek. Saved config keys take precedence over the environment and are easier to rotate.

To rotate or remove a saved key: deepseek auth clear --provider deepseek.

Auto Mode

Use deepseek --model auto or /model auto when you want DeepSeek TUI to decide how much model and reasoning power a turn needs.

Auto mode controls two settings together:

• Model: deepseek-v4-flash or deepseek-v4-pro
• Thinking: off, high, or max

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.

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.

Use a fixed model or fixed thinking level when you want repeatable benchmarking, a strict cost ceiling, or a specific provider/model mapping.

Linux ARM64 (Raspberry Pi, Asahi, Graviton, HarmonyOS PC)

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 and place them side by side on your PATH.

China / Mirror-friendly Installation

If GitHub or npm downloads are slow from mainland China, use 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 both binaries (the dispatcher delegates to the TUI at runtime):

cargo install deepseek-tui-cli --locked   # provides `deepseek`
cargo install deepseek-tui     --locked   # provides `deepseek-tui`
deepseek --version

Prebuilt binaries can also be downloaded from GitHub Releases. Use DEEPSEEK_TUI_RELEASE_BASE_URL for mirrored release assets.

Windows (Scoop)

Scoop is a Windows package manager. Once installed, run:

scoop install deepseek-tui

Install from source

Works on any Tier-1 Rust target — including musl, riscv64, FreeBSD, and older ARM64 distros.

# Linux build deps (Debian/Ubuntu/RHEL):
#   sudo apt-get install -y build-essential pkg-config libdbus-1-dev
#   sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel

git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI

cargo install --path crates/cli --locked   # requires Rust 1.88+; provides `deepseek`
cargo install --path crates/tui --locked   # provides `deepseek-tui`

Both binaries are required. Cross-compilation and platform-specific notes: docs/INSTALL.md.

Other API Providers

# NVIDIA NIM
deepseek auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"
deepseek --provider nvidia-nim

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

# Self-hosted SGLang
SGLANG_BASE_URL="http://localhost:30000/v1" deepseek --provider sglang --model deepseek-v4-flash

# Self-hosted vLLM
VLLM_BASE_URL="http://localhost:8000/v1" deepseek --provider vllm --model deepseek-v4-flash

# Self-hosted Ollama
ollama pull deepseek-coder:1.3b
deepseek --provider ollama --model deepseek-coder:1.3b

---

What's New In v0.8.15

A community-driven stabilization release focused on auth recovery, Windows terminals, Zed/ACP compatibility, setup friction, and clearer cost display. Full changelog.

• 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
• Zed / ACP adapter — deepseek serve --acp exposes a local stdio Agent Client Protocol server for Zed and other compatible editors
• Windows terminal fixes — UTF-8 console setup, dispatcher resume handling, clipboard fallback, Ctrl+E composer behavior, and safer Windows mouse defaults
• Yuan cost display — set cost_currency = "cny" (or yuan / rmb) to show footer, /cost, /tokens, and notification summaries in CNY
• 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
• Reliability fixes — workspace-scoped resume --last, capped API max_tokens, endpoint diagnostics in deepseek doctor, npm --version fallback, and current-date turn metadata

---

Usage

deepseek                                         # interactive TUI
deepseek "explain this function"                 # one-shot prompt
deepseek --model deepseek-v4-flash "summarize"   # model override
deepseek --model auto "fix this bug"             # auto-select model + thinking
deepseek --yolo                                  # auto-approve tools
deepseek auth set --provider deepseek            # 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 tool/plugin dirs
deepseek models                                  # list live API models
deepseek sessions                                # list saved sessions
deepseek resume --last                           # resume the most recent session in this workspace
deepseek resume <SESSION_ID>                     # resume a specific session by UUID
deepseek fork <SESSION_ID>                       # fork a session at a chosen turn
deepseek serve --http                            # HTTP/SSE API server
deepseek serve --acp                             # ACP stdio adapter for Zed/custom agents
deepseek pr <N>                                  # fetch PR and pre-seed review prompt
deepseek mcp list                                # list configured MCP servers
deepseek mcp validate                            # validate MCP config/connectivity
deepseek mcp-server                              # run dispatcher MCP stdio server
deepseek update                                  # check for and apply binary updates

Zed / ACP

DeepSeek can run as a custom Agent Client Protocol server for editors that spawn local ACP agents over stdio. In Zed, add a custom agent server:

{
  "agent_servers": {
    "DeepSeek": {
      "type": "custom",
      "command": "deepseek",
      "args": ["serve", "--acp"],
      "env": {}
    }
  }
}

The first ACP slice supports new sessions and prompt responses through your existing DeepSeek config/API key. Tool-backed editing and checkpoint replay are not exposed through ACP yet.

Keyboard Shortcuts

Key	Action
Tab	Complete / or @ entries; while running, queue draft as follow-up; otherwise cycle mode
Shift+Tab	Cycle reasoning-effort: off → high → max
F1	Searchable help overlay
Esc	Back / dismiss
Ctrl+K	Command palette
Ctrl+R	Resume an earlier session
Alt+R	Search prompt history and recover cleared drafts
Ctrl+S	Stash current draft (/stash list, /stash pop to recover)
@path	Attach file/directory context in composer
↑ (at composer start)	Select attachment row for removal

Full shortcut catalog: docs/KEYBINDINGS.md.

---

Modes

Mode	Behavior
Plan 🔍	Read-only investigation — model explores and proposes a plan (update_plan + checklist_write) before making changes
Agent 🤖	Default interactive mode — multi-step tool use with approval gates; model outlines work via checklist_write
YOLO ⚡	Auto-approve all tools in a trusted workspace; still maintains plan and checklist for visibility

---

Configuration

User config: ~/.deepseek/config.toml. Project overlay: <workspace>/.deepseek/config.toml (denied: api_key, base_url, provider, mcp_config_path). config.example.toml has every option.

Key environment variables:

Variable	Purpose
DEEPSEEK_API_KEY	API key
DEEPSEEK_BASE_URL	API base URL
DEEPSEEK_HTTP_HEADERS	Optional custom model request headers, e.g. X-Model-Provider-Id=your-model-provider
DEEPSEEK_MODEL	Default model
DEEPSEEK_PROVIDER	deepseek (default), nvidia-nim, fireworks, sglang, vllm, ollama
DEEPSEEK_PROFILE	Config profile name
DEEPSEEK_MEMORY	Set to on to enable user memory
NVIDIA_API_KEY / FIREWORKS_API_KEY / SGLANG_API_KEY / VLLM_API_KEY / OLLAMA_API_KEY	Provider auth
SGLANG_BASE_URL	Self-hosted SGLang endpoint
VLLM_BASE_URL	Self-hosted vLLM endpoint
OLLAMA_BASE_URL	Self-hosted Ollama endpoint
OLLAMA_MODEL	Self-hosted Ollama model tag
NO_ANIMATIONS=1	Force accessibility mode at startup
SSL_CERT_FILE	Custom CA bundle for corporate proxies

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 and docs/MCP.md.

---

Models & Pricing

Model	Context	Input (cache hit)	Input (cache miss)	Output
deepseek-v4-pro	1M	$0.003625 / 1M*	$0.435 / 1M*	$0.87 / 1M*
deepseek-v4-flash	1M	$0.0028 / 1M	$0.14 / 1M	$0.28 / 1M

Legacy aliases deepseek-chat / deepseek-reasoner map to deepseek-v4-flash. NVIDIA NIM variants use your NVIDIA account terms.

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.

Note

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. All rates listed in the README correspond to the officially published values.

---

Publishing Your Own Skill

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:

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

Frontmatter required:

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

# My Skill
Instructions for the agent go here.

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.

---

Documentation

Doc	Topic
ARCHITECTURE.md	Codebase internals
CONFIGURATION.md	Full config reference
MODES.md	Plan / Agent / YOLO modes
MCP.md	Model Context Protocol integration
RUNTIME_API.md	HTTP/SSE API server
INSTALL.md	Platform-specific install guide
MEMORY.md	User memory feature guide
SUBAGENTS.md	Sub-agent role taxonomy and lifecycle
KEYBINDINGS.md	Full shortcut catalog
RELEASE_RUNBOOK.md	Release process
LOCALIZATION.md	UI locale matrix & switching
OPERATIONS_RUNBOOK.md	Ops & recovery

Full Changelog: CHANGELOG.md.

---

Thanks

This project ships with help from a growing community of contributors:

• merchloubna70-dot — 28 PRs spanning features, fixes, and VS Code extension scaffolding (#645–#681)
• WyxBUPT-22 — Markdown rendering for tables, bold/italic, and horizontal rules (#579)
• loongmiaow-pixel — Windows + China install documentation (#578)
• 20bytes — User memory docs and help polish (#569)
• staryxchen — glibc compatibility preflight (#556)
• Vishnu1837 — glibc compatibility improvements (#565)
• shentoumengxin — Shell cwd boundary validation (#524)
• toi500 — Windows paste fix report
• xsstomy — Terminal startup repaint report
• melody0709 — Slash-prefix Enter activation report
• lloydzhou and jeoor — Compaction cost reports
• Agent-Skill-007 — README clarity pass (#685)
• woyxiang — Windows Scoop install docs (#696)
• wangfeng — Pricing/discount info update (#692)
• zichen0116 — CODE_OF_CONDUCT.md (#686)
• dfwqdyl-ui — model ID case-sensitivity compatibility report (#729)
• Oliver-ZPLiu — stale working... state bug report and Windows clipboard fallback (#738, #850)
• reidliu41 — resume hint and workspace trust persistence fixes (#863, #870)
• xieshutao — plain Markdown skill fallback (#869)
• GK012 — npm wrapper --version fallback (#885)
• Hafeez Pizofreude — SSRF protection in fetch_url and Star History chart
• Unic (YuniqueUnic) — Schema-driven config UI (TUI + web)
• Jason — SSRF security hardening

---

Contributing

See CONTRIBUTING.md. Pull requests welcome — check the open issues for good first contributions.

Support: Buy me a coffee.

Note

Not affiliated with DeepSeek Inc.

License

MIT

Star History