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

Prebuilt binaries are published for Linux x64, Linux ARM64 (v0.8.8+), macOS x64, macOS ARM64, and Windows x64. For everything else — musl, riscv64, FreeBSD, etc. — see Build from source below or the full docs/INSTALL.md walkthrough.

npm i -g deepseek-tui works on glibc-based ARM64 Linux from v0.8.8 onward. If you're stuck on v0.8.7 or earlier (where you'll see Unsupported architecture: arm64), upgrade or use cargo install:

# requires Rust 1.85+ (https://rustup.rs)
cargo install deepseek-tui-cli --locked   # provides `deepseek`
cargo install deepseek-tui     --locked   # provides `deepseek-tui`

You can also download deepseek-linux-arm64 and deepseek-tui-linux-arm64 directly from the Releases page and drop both side by side into a directory on your PATH. Cross-compiling from x64 to ARM64 is documented in docs/INSTALL.md.

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 the companion TUI binary (both are required — the dispatcher delegates to the TUI runtime):

cargo install deepseek-tui-cli --locked   # provides `deepseek`
cargo install deepseek-tui     --locked   # provides `deepseek-tui`
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

# Linux build deps (Debian/Ubuntu/openEuler/Kylin):
#   sudo apt-get install -y build-essential pkg-config libdbus-1-dev
#   # RHEL family: 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.85+; provides `deepseek`
cargo install --path crates/tui --locked   # provides `deepseek-tui`

A stabilization-focused release: a thick band of UX polish on top of the v0.8.6 / v0.8.7 base, plus runtime fixes for the rough edges that surfaced in production sessions. No model or API changes; every existing config and session keeps working.

• Visual retry / backoff banner when the upstream rate-limits or 5xxs, with a per-second countdown so a stalled session is obviously stalled instead of silently frozen (#499).
• MCP health chip in the footer — a coloured MCP n/n glyph reflects how many configured servers are actually reachable, hidden when no servers are configured (#502).
• Tool-output spillover routes full bodies to ~/.deepseek/tool_outputs/<id>.txt with a 32 KiB head visible in the cell; the existing details pager appends the full output so nothing is hidden, just paged (#500).
• Multi-day duration formatting — humanize_duration walks s → m → h → d → w and caps at two units, so a long-running session reads 2d 3h instead of 188415s (#447).
• Cumulative worked Nh Mm footer chip appears once a session crosses 60s, dropping first under narrow widths so it never shoves more important chips off-screen (#448).
• OSC 8 hyperlinks — URLs in the transcript are Cmd+click-openable on iTerm2, Terminal.app, Ghostty, Kitty, WezTerm, Alacritty, and modern gnome-terminal/konsole; legacy terminals just show the visible text (#498).
• Inline diff rendering for edit_file and write_file — tool results emit a unified diff at the head of the body, picked up by the diff-aware renderer with line numbers and coloured +/- gutters (#505).
• Composer prompt stash — Ctrl+S parks the current draft to ~/.deepseek/composer_stash.jsonl, /stash list shows parked drafts, /stash pop restores LIFO, /stash clear wipes the file. Self-healing JSONL parser, 200-entry cap, multi-line drafts preserved (#440).
• Slash-menu layout no longer jitters the chat area as the matched-entry count changes mid-typing — reported on Windows 10 PowerShell + WSL where the per-cell write cost made the redraw visibly laggy. The composer now reserves its panel-max envelope for the whole slash/mention session.

• NO_ANIMATIONS=1 env var (also 1 / true / yes / on) forces low_motion = true and fancy_animations = false at startup regardless of saved settings; new docs/ACCESSIBILITY.md documents every motion / output knob (#450).
• Keyboard-enhancement flags pop on every shutdown path including panic, Ctrl+Z suspend, and external-editor invocation, so a crashed TUI never leaves your terminal in raw mode (#443/#444).
• Kitty keyboard protocol (DISAMBIGUATE_ESCAPE_CODES) pushed at startup so kitty-protocol terminals report unambiguous events for Option/Alt-modified keys; legacy terminals are unaffected (#442).

• Sub-agent cap raised 5 → 10 (configurable via [subagents].max_concurrent, hard ceiling 20). Completed agents no longer count against the running cap (#509).
• Multi-agent fan-out UI freeze fixed — SharedSubAgentManager is now Arc<RwLock<…>>; read paths take read locks instead of contending on a Mutex (#510).
• Sub-agent output summarized before being folded into the parent's context, so a child returning 100KB of evidence doesn't wreck the parent's window (#511).
• Implementer + Verifier sub-agent roles wired into agent_spawn / agent_assign schemas so the model surfaces them by name (#404).
• agent_list defaults to current-session view — prior sessions filtered out unless include_archived=true (#405).
• Compact agent_spawn rendering in live mode collapses to a single header line; transcript replay keeps the full block (#409).
• agent_swarm / spawn_agents_on_csv / /swarm removed in v0.8.5 — confirmed gone in this release; multi-child fanout is no longer a model-callable tool.

• load_skill model-callable tool — takes a skill id, returns the SKILL.md body plus sibling companion-file list in one call. Available in Plan and Agent / Yolo modes (#434).
• Cross-tool skill discovery — skills catalogue and load_skill walk .agents/skills, skills, .opencode/skills, .claude/skills, and ~/.deepseek/skills with first-wins precedence (#432).
• /hooks read-only lifecycle hook listing groups configured hooks by event with name / command preview / timeout / condition. Notes the global [hooks].enabled state. /hooks events lists every supported HookEvent value (#460).
• Every HookEvent now has a live producer — tool_call_before / tool_call_after / message_submit / on_error fire from the runtime in addition to the existing session-lifecycle and mode-change events. Hooks remain read-only observers in v0.8.8 (#455).
• instructions = [...] config array lets you stack additional system-prompt files; paths capped at 100 KiB each, project array replaces user array wholesale (#454).
• deepseek pr <N> subcommand fetches a PR's title / body / diff via gh and launches the TUI with a review prompt already in the composer. Codepoint-safe diff cap at 200 KiB; optional --repo / --checkout (#451).
• User-memory MVP (opt-in) — ~/.deepseek/memory.md injected into the system prompt as a <user_memory> block; # foo typed in the composer appends a timestamped bullet without firing a turn; /memory [show|path|clear|edit] for inspection. Default off; enable with [memory] enabled = true or DEEPSEEK_MEMORY=on (#489–#493).

• Project-config keys denied at workspace scope — a malicious ./.deepseek/config.toml can no longer override api_key, base_url, provider, or mcp_config_path. The loosest values (approval_policy = "auto", sandbox_mode = "danger-full-access") are also denied at project scope (#417).
• SSL_CERT_FILE honoured in the HTTPS client so corporate-CA / MITM-proxy users can connect — PEM bundle and DER fallback; failures log a warning and continue (#418).
• Execpolicy heredoc parsing — normalize_command strips heredoc bodies before shlex tokenization so auto_allow = ["cat > file.txt"] matches the heredoc form cat <<EOF > file.txt\nbody\nEOF. Recognises <<DELIM / <<-DELIM / <<'DELIM' / <<"DELIM"; leaves <<< (here-string) untouched (#419).
• Don't auto-approve git -C ... runtime fix shipped on v0.8.7 main (#416) — included for completeness.

• Linux ARM64 prebuilts added to the release matrix; npm wrapper picks the right binary on aarch64-linux automatically. New docs/INSTALL.md covers every install path (npm, cargo, prebuilt, source).
• deepseek update fixed — the v0.8.7 self-updater used Rust ARCH constants (aarch64/x86_64) instead of release-asset naming (arm64/x64), so the command failed on every platform. Now maps correctly and rejects .sha256 siblings as primary binaries (#503).
• CI workflow cleanup — pruned three duplicated/dead workflows; release.yml build job now allows the parity gate to be skipped on manual workflow_dispatch (#507).

• Composer Option+Backspace deletes by word now (#488).
• Offline composer queue is session-scoped — legacy unscoped queues fail closed instead of leaking content into unrelated chats (#487).
• display_path test race + Windows separator — tests no longer mutate $HOME; home-relative suffix joins with MAIN_SEPARATOR_STR so Windows shows ~\projects\foo (#506).
• Footer reads statusline colours from app.ui_theme (#449).

Full changelog: CHANGELOG.md.

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 issues in v0.8.7 (fixed in v0.8.8):

• 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).
• npm i -g deepseek-tui exits with Unsupported architecture: arm64 on platform linux on ARM64 Linux because v0.8.7 didn't publish a deepseek-linux-arm64 asset.

Until v0.8.8 ships, install via:

# x64 Linux / macOS / Windows
npm i -g deepseek-tui

# ARM64 Linux (HarmonyOS, openEuler, Asahi, Raspberry Pi, Graviton, …) —
# build from source with Cargo (Rust 1.85+):
cargo install deepseek-tui-cli --locked   # provides `deepseek`
cargo install deepseek-tui     --locked   # provides `deepseek-tui`

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 (removed swarm tool surface, 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 legacy fanout 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