Hunter Bown
289 lines
10 KiB
Markdown
289 lines
10 KiB
Markdown
# DeepSeek CLI 🤖
|
||
|
||
Your AI-powered terminal companion for DeepSeek models
|
||
|
||
[](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml)
|
||
[](https://crates.io/crates/deepseek-tui)
|
||
|
||
Unofficial terminal UI (TUI) + CLI for the [DeepSeek platform](https://platform.deepseek.com) — chat with DeepSeek models and collaborate with AI assistants that can read, write, execute, and plan with approval-gated tool access.
|
||
|
||
**Not affiliated with DeepSeek Inc.**
|
||
|
||
## ✨ Features
|
||
|
||
- **Interactive TUI** with multiple modes (Normal, Plan, Agent, YOLO, RLM, Duo)
|
||
- **Comprehensive tool access** – File operations, shell execution, task management, and sub-agent systems
|
||
- **File operations**: List directories, read/write/edit files, apply patches, search files with regex
|
||
- **Shell execution**: Run commands with timeout support, background execution with task management
|
||
- **Task management**: Todo lists, implementation plans, persistent notes
|
||
- **Sub-agent system**: Spawn, coordinate, and cancel background agents (including swarms)
|
||
- **Web search**: Integrated web search with DuckDuckGo
|
||
- **Multi‑model support** – DeepSeek‑Reasoner, DeepSeek‑Chat, and other DeepSeek models
|
||
- **Context‑aware** – loads project‑specific instructions from `AGENTS.md`
|
||
- **Session management** – resume, fork, and search past conversations
|
||
- **Skills system** – reusable workflows stored as `SKILL.md` directories
|
||
- **Model Context Protocol (MCP)** – integrate external tool servers
|
||
- **Sandboxed execution** (macOS) for safe shell commands
|
||
- **Git integration** – code review, patch application, diff analysis
|
||
- **Cross‑platform** – works on macOS, Linux, and Windows
|
||
|
||
## 🚀 Quick Start
|
||
|
||
1. **Get an API key** from [https://platform.deepseek.com](https://platform.deepseek.com)
|
||
2. **Install and run**:
|
||
|
||
```bash
|
||
# Install via Cargo
|
||
cargo install deepseek-tui --locked
|
||
|
||
# Set your API key
|
||
export DEEPSEEK_API_KEY="YOUR_DEEPSEEK_API_KEY"
|
||
|
||
# Bootstrap MCP + skills templates (recommended)
|
||
deepseek setup
|
||
|
||
# Start chatting
|
||
deepseek
|
||
```
|
||
|
||
3. Press `F1` or type `/help` for the in‑app command list.
|
||
|
||
If anything looks off, run `deepseek doctor` to diagnose configuration issues.
|
||
|
||
## 📦 Installation
|
||
|
||
### From crates.io
|
||
|
||
```bash
|
||
cargo install deepseek-tui --locked
|
||
```
|
||
|
||
### Build from source
|
||
|
||
```bash
|
||
git clone https://github.com/Hmbown/DeepSeek-TUI.git
|
||
cd DeepSeek-TUI
|
||
cargo build --release
|
||
./target/release/deepseek --help
|
||
```
|
||
|
||
### Direct download
|
||
|
||
Download a prebuilt binary from [GitHub Releases](https://github.com/Hmbown/DeepSeek-TUI/releases) and put it on your `PATH` as `deepseek`.
|
||
|
||
## ⚙️ Configuration
|
||
|
||
On first run, the TUI can prompt for your API key and save it to `~/.deepseek/config.toml`. You can also create the file manually:
|
||
|
||
```toml
|
||
# ~/.deepseek/config.toml
|
||
api_key = "YOUR_DEEPSEEK_API_KEY" # must be non‑empty
|
||
default_text_model = "deepseek-reasoner" # optional
|
||
allow_shell = false # optional
|
||
max_subagents = 3 # optional (1‑20)
|
||
```
|
||
|
||
Useful environment variables:
|
||
|
||
- `DEEPSEEK_API_KEY` (overrides `api_key`)
|
||
- `DEEPSEEK_BASE_URL` (default: `https://api.deepseek.com`; China users may use `https://api.deepseeki.com`)
|
||
- `DEEPSEEK_PROFILE` (selects `[profiles.<name>]` from the config; errors if missing)
|
||
- `DEEPSEEK_CONFIG_PATH` (override config path)
|
||
- `DEEPSEEK_MCP_CONFIG`, `DEEPSEEK_SKILLS_DIR`, `DEEPSEEK_NOTES_PATH`, `DEEPSEEK_MEMORY_PATH`, `DEEPSEEK_ALLOW_SHELL`, `DEEPSEEK_MAX_SUBAGENTS`
|
||
|
||
To bootstrap MCP and skills at their resolved locations, run `deepseek setup`. To
|
||
only create an MCP template, run `deepseek mcp init`.
|
||
|
||
See `config.example.toml` and `docs/CONFIGURATION.md` for a full reference.
|
||
|
||
## 🎮 Modes
|
||
|
||
In the TUI, press `Tab` to cycle modes: **Normal → Plan → Agent → YOLO → RLM → Duo → Normal**.
|
||
|
||
| Mode | Description | Approval Behavior |
|
||
|------|-------------|-------------------|
|
||
| **Normal** | Chat; asks before file writes or shell | Manual approval for writes & shell |
|
||
| **Plan** | Design‑first prompting; same approvals as Normal | Manual approval for writes & shell |
|
||
| **Agent** | Multi‑step tool use; asks before shell | Manual approval for shell, auto‑approve file writes |
|
||
| **YOLO** | Enables shell + trust + auto‑approves all tools (dangerous) | Auto‑approve all tools |
|
||
| **RLM** | Externalized context + REPL helpers; auto‑approves tools (best for large files) | Auto‑approve tools |
|
||
| **Duo** | Player‑coach autocoding with iterative validation (based on g3 paper) | Depends on phase |
|
||
|
||
Approval behavior is mode‑dependent, but you can also override it at runtime with `/set approval_mode auto|suggest|never`.
|
||
|
||
## 🛠️ Tools
|
||
|
||
DeepSeek CLI exposes a comprehensive set of tools to the model across 5 categories, with 16+ individual tools available, all with approval gating based on the current mode.
|
||
|
||
### Tool Categories
|
||
|
||
#### File Operations
|
||
- **`list_dir`** – List directory contents with file/directory metadata
|
||
- **`read_file`** – Read UTF‑8 files from the workspace
|
||
- **`write_file`** – Create or overwrite files
|
||
- **`edit_file`** – Search and replace text in files
|
||
- **`apply_patch`** – Apply unified diff patches with fuzzy matching
|
||
- **`grep_files`** – Search files by regex pattern with context lines
|
||
- **`web_search`** – Search the web and return concise results
|
||
|
||
#### Shell Execution
|
||
- **`exec_shell`** – Run shell commands with timeout support
|
||
- **Background execution** – Run commands in background with task ID return
|
||
|
||
#### Task Management
|
||
- **`todo_write`** – Create and update todo lists with status tracking
|
||
- **`update_plan`** – Manage structured implementation plans
|
||
- **`note`** – Append persistent notes across sessions
|
||
|
||
#### Sub‑Agents
|
||
- **`agent_spawn`** – Create background sub‑agents for focused tasks
|
||
- **`agent_swarm`** – Launch a dependency‑aware swarm of sub‑agents
|
||
- **`agent_result`** – Retrieve results from sub‑agents
|
||
- **`agent_list`** – List all active and completed agents
|
||
- **`agent_cancel`** – Cancel running sub‑agents
|
||
|
||
### System Behavior
|
||
|
||
- **Workspace boundary**: File tools are restricted to `--workspace` unless you enable `/trust` (YOLO enables trust automatically).
|
||
- **Approvals**: The TUI requests approval depending on mode and tool category (file writes, shell).
|
||
- **Web search**: `web_search` uses DuckDuckGo HTML results and is auto‑approved.
|
||
- **Skills**: Reusable workflows stored as `SKILL.md` directories (default: `~/.deepseek/skills`, or `./skills` per workspace). Use `/skills` and `/skill <name>`. Bootstrap with `deepseek setup --skills` (add `--local` for `./skills`).
|
||
- **MCP**: Load external tool servers via `~/.deepseek/mcp.json` (supports `servers` and `mcpServers`). MCP tools currently execute without TUI approval prompts, so only enable servers you trust. See `docs/MCP.md`.
|
||
|
||
## 🧠 RLM (Reasoning & Large‑scale Memory)
|
||
|
||
RLM mode is designed for "too big for context" tasks: large files, whole‑doc sweeps, and big pasted blocks.
|
||
|
||
- Auto‑switch triggers: "largest file", explicit "RLM", large file requests, and large pastes.
|
||
- Shortcut: `/rlm` (or `/aleph`) enters RLM mode directly.
|
||
- In **RLM mode**, `/load @path` loads a file into the external context store (outside RLM mode, `/load` loads a saved chat JSON).
|
||
- Use `/repl` to enter expression mode (e.g. `search("pattern")`, `lines(1, 80)`).
|
||
- Power tools: `rlm_load`, `rlm_exec`, `rlm_status`, `rlm_query`.
|
||
|
||
`rlm_query` can be expensive: prefer batching and check `/status` if you're doing lots of sub‑queries.
|
||
|
||
## 👥 Duo Mode
|
||
|
||
> **Note:** Duo mode is experimental and may not work correctly in all cases. Use with caution.
|
||
|
||
Duo mode implements the player‑coach autocoding paradigm for iterative development with built‑in validation:
|
||
|
||
- **Player**: implements requirements (builder role)
|
||
- **Coach**: validates implementation against requirements (critic role)
|
||
- Tools: `duo_init`, `duo_player`, `duo_coach`, `duo_advance`, `duo_status`
|
||
|
||
Workflow: `init → player → coach → advance → (repeat until approved)`
|
||
|
||
## 📚 Examples
|
||
|
||
### Interactive chat
|
||
|
||
```bash
|
||
deepseek
|
||
```
|
||
|
||
### One‑shot prompt (non‑interactive)
|
||
|
||
```bash
|
||
deepseek -p "Write a haiku about Rust"
|
||
```
|
||
|
||
### Agentic execution with tool access
|
||
|
||
```bash
|
||
deepseek exec --auto "Fix lint errors in the current directory"
|
||
```
|
||
|
||
### Resume latest session
|
||
|
||
```bash
|
||
deepseek --continue
|
||
```
|
||
|
||
### Work on a specific project
|
||
|
||
```bash
|
||
deepseek --workspace /path/to/project
|
||
```
|
||
|
||
### Review staged git changes
|
||
|
||
```bash
|
||
deepseek review --staged
|
||
```
|
||
|
||
### Apply a patch file
|
||
|
||
```bash
|
||
deepseek apply patch.diff
|
||
```
|
||
|
||
### List saved sessions
|
||
|
||
```bash
|
||
deepseek sessions --limit 50
|
||
```
|
||
|
||
### Generate shell completions
|
||
|
||
```bash
|
||
deepseek completions zsh > _deepseek
|
||
deepseek completions bash > deepseek.bash
|
||
deepseek completions fish > deepseek.fish
|
||
```
|
||
|
||
## 🔧 Troubleshooting
|
||
|
||
### No API key
|
||
Set `DEEPSEEK_API_KEY` environment variable or run `deepseek` and complete onboarding.
|
||
|
||
### Config not found
|
||
Check `~/.deepseek/config.toml` (or `DEEPSEEK_CONFIG_PATH`).
|
||
|
||
### Wrong region / base URL
|
||
Set `DEEPSEEK_BASE_URL` to `https://api.deepseeki.com` (China).
|
||
|
||
### Session issues
|
||
Run `deepseek sessions` and try `deepseek --resume latest`.
|
||
|
||
### Skills missing
|
||
Run `deepseek setup --skills` to create a global skills directory, or add `--local`
|
||
to create `./skills` for the current workspace. Then run `deepseek doctor` to see
|
||
which skills directory is selected.
|
||
|
||
### MCP tools missing
|
||
Run `deepseek mcp init` (or `deepseek setup --mcp`), then restart. `deepseek doctor`
|
||
now checks the MCP path resolved from your config/env overrides.
|
||
|
||
### Sandbox errors (macOS)
|
||
Run `deepseek doctor` to confirm sandbox availability. On macOS, ensure
|
||
`/usr/bin/sandbox-exec` exists. For other platforms, sandboxing is limited.
|
||
|
||
## 📖 Documentation
|
||
|
||
- `docs/CONFIGURATION.md` – Complete configuration reference
|
||
- `docs/MCP.md` – Model Context Protocol guide
|
||
- `docs/ARCHITECTURE.md` – Project architecture
|
||
- `docs/RLM.md` – RLM mode deep‑dive
|
||
- `docs/MODES.md` – Mode comparison and usage
|
||
- `CONTRIBUTING.md` – How to contribute to the project
|
||
|
||
## 🧪 Development
|
||
|
||
```bash
|
||
cargo build
|
||
cargo test
|
||
cargo fmt
|
||
cargo clippy
|
||
```
|
||
|
||
See `CONTRIBUTING.md` for detailed guidelines.
|
||
|
||
## 📄 License
|
||
|
||
MIT
|
||
|
||
---
|
||
|
||
DeepSeek is a trademark of DeepSeek Inc. This is an unofficial project.
|