codewhale/README.md

DeepSeek CLI 🤖

Your AI-powered terminal companion for DeepSeek models

Unofficial terminal UI (TUI) + CLI for the DeepSeek platform — 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)
• User input prompts: Ask structured, multiple-choice questions during tool flows
• Web browsing: web.run search/open/click/find/screenshot with citation-ready sources
• Structured data tools: weather, finance, sports, time, calculator
• 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
2. Install and run:

# 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

cargo install deepseek-tui --locked

Build from source

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 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:

# ~/.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.run – Browse the web (search/open/click/find/screenshot) with ref_ids for citations
• web_search – Quick web search (fallback when citations are not needed)
• request_user_input – Ask the user short multiple-choice questions
• multi_tool_use.parallel – Execute multiple read-only tools in parallel

Structured Data

• weather – Daily weather forecast for a location
• finance – Latest price for a stock, fund, index, or cryptocurrency
• sports – Schedules or standings for a league
• time – Current time for a UTC offset
• calculator – Evaluate arithmetic expressions

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 browsing: web.run uses DuckDuckGo HTML results and is auto‑approved.
• Web search: web_search is a quick fallback when citations are not needed.
• Skills: Reusable workflows stored as SKILL.md directories. The resolved skills dir prefers workspace-local .agents/skills, then ./skills, then ~/.deepseek/skills. 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

deepseek

One‑shot prompt (non‑interactive)

deepseek -p "Write a haiku about Rust"

Agentic execution with tool access

deepseek exec --auto "Fix lint errors in the current directory"

Resume latest session

deepseek --continue

Work on a specific project

deepseek --workspace /path/to/project

Review staged git changes

deepseek review --staged

Apply a patch file

deepseek apply patch.diff

List saved sessions

deepseek sessions --limit 50

Generate shell completions

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. If you want the preferred workspace-local path, create .agents/skills manually. 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

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.