codewhale/README.md

DeepSeek CLI

An unofficial terminal UI and CLI for the DeepSeek platform.

Chat with DeepSeek models directly from your terminal. The assistant can read and write files, run shell commands, search the web, manage tasks, and coordinate sub-agents — all with configurable approval gating.

Not affiliated with DeepSeek Inc.

Getting Started

1. Install

# From crates.io (requires Rust 1.85+)
cargo install deepseek-tui --locked

# Or build from source
git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI
cargo install --path . --locked

Prebuilt binaries are also available on GitHub Releases.

2. Set your API key

Get a key from platform.deepseek.com. On first run the TUI will prompt you to enter and save it, or create the config manually:

# ~/.deepseek/config.toml
api_key = "YOUR_DEEPSEEK_API_KEY"

3. Run

deepseek

Press Tab to switch modes, F1 for help, and Esc to cancel a running request.

Modes

Mode	Description	Approvals
Plan	Design-first prompting; produces a plan before implementing	Manual for writes and shell
Agent	Multi-step autonomous tool use	Auto-approve file writes, manual for shell
YOLO	Full auto-approve (use with caution)	All tools auto-approved

Press Tab to cycle modes. Normal mode (manual approval for everything) is also available via /set mode normal.

What It Can Do

The assistant has access to 35+ tools:

• File operations — read, write, edit, patch, search, and grep across your workspace
• Shell execution — run commands with timeout, background execution, and interactive I/O
• Web browsing — search the web, open pages, screenshot, and extract content with citations
• Git — inspect repo status, diffs, and staged changes
• Code review — structured review for files, diffs, or GitHub PRs
• Sub-agents — spawn background agents or coordinate agent swarms for parallel work
• Task management — to-do lists, implementation plans, persistent notes, and a background task queue
• Structured data — weather, finance, sports scores, time zones, and a calculator
• Parallel execution — run multiple tool calls simultaneously for efficiency
• Project mapping — explore codebase structure and identify key files
• Code execution — run Python code in a sandboxed environment
• Test runner — execute cargo test and other test suites
• Diagnostics — inspect workspace, git, and toolchain status
• Note-taking — record persistent notes for future reference
• Tool discovery — search for tools by name or natural language
• MCP integration — connect external tool servers via the Model Context Protocol

All file tools respect the --workspace boundary unless /trust is enabled.

Examples

# Interactive chat
deepseek

# One-shot prompt
deepseek -p "Explain the borrow checker in two sentences"

# Agentic execution with auto-approve
deepseek exec --auto "Fix all clippy warnings in this project"

# Resume latest session
deepseek --continue

# Work on a specific project
deepseek --workspace /path/to/project

# Review staged git changes
deepseek review --staged

# Start the runtime API server
deepseek serve --http

# List available models
deepseek models

# Verify your environment
deepseek doctor

Configuration

Config lives at ~/.deepseek/config.toml:

api_key = "sk-..."
default_text_model = "deepseek-reasoner" # optional (or "deepseek-chat")
allow_shell = true                     # optional (sandboxed by default)
max_subagents = 3                      # optional (1-20)

Key environment variables:

Variable	Purpose
DEEPSEEK_API_KEY	API key (overrides config file)
DEEPSEEK_BASE_URL	API endpoint (default: https://api.deepseek.com)

See config.example.toml and docs/CONFIGURATION.md for the full reference.

Runtime API

deepseek serve --http starts a local HTTP/SSE API on 127.0.0.1:7878 for external clients. Supports threads, multi-turn conversations, task queues, and live event streaming.

See docs/RUNTIME_API.md for endpoints and usage.

Keyboard Shortcuts

Key	Action
Enter	Send message
Alt+Enter / Ctrl+J	Insert newline
Tab	Autocomplete or cycle modes
Esc	Cancel request / clear input
Ctrl+C	Cancel or exit
Ctrl+K	Command palette
Ctrl+R	Search past sessions
F1	Help overlay
PageUp / PageDown	Scroll transcript

Troubleshooting

Problem	Fix
No API key	Set DEEPSEEK_API_KEY or run deepseek to complete onboarding
Config not found	Check ~/.deepseek/config.toml (or set DEEPSEEK_CONFIG_PATH)
Wrong region	Set DEEPSEEK_BASE_URL to https://api.deepseeki.com (China)
Finance tool unavailable	Use web.run to fetch financial data instead
Token/cost tracking inaccuracies	Use /compact to manage context; treat cost estimates as approximate
web.run tool name	Tool is named web.run (single dot), not web..run
Sandbox errors (macOS)	Run deepseek doctor

Documentation

• Configuration Reference
• Architecture
• Mode Comparison
• MCP Integration
• Runtime API
• Operations Runbook
• Contributing

Development

cargo build
cargo test
cargo clippy
cargo fmt

See CONTRIBUTING.md for guidelines.

Standalone DeepSeek App (Web + Desktop)

This repo now includes a separate Codex-style app at apps/deepseek-app built with Next.js + Tauri.

# Install frontend deps once
pnpm install

# Web app
pnpm deepseek-app:web:dev

# Desktop app (Tauri)
pnpm deepseek-app:desktop:dev

The app talks to the runtime API (deepseek serve --http) and desktop mode auto-starts it when unavailable.

License

MIT

---

DeepSeek is a trademark of DeepSeek Inc. This is an unofficial, community-driven project.