codewhale/README.md

# DeepSeek CLI 🤖

Your AI-powered terminal companion for DeepSeek models

[![CI](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/deepseek-tui)](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)
- **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](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 → 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 |
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`.

## 📚 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. 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/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.