DeepSeek-TUI Configuration Guide

The first time I installed DeepSeek-TUI, I ran npm install -g deepseek-tui (with npmmirror for speed — finished in under a minute). The TUI interface appeared, and I got stuck on the first question: "Which mode should I pick?"

Plan mode, Agent mode, YOLO mode — three options, no explanations. I picked YOLO to see what would happen.

Then random files appeared in my project directory, code was modified in ways I didn't intend.

Lesson one: YOLO mode executes every operation without confirmation. Using YOLO on a production project is like giving an intern you just met root access to your system.

I switched to Agent mode afterward — it asks for confirmation before every action, which saved me from further damage.

Trap 1: Wrong model choice, burned money

DeepSeek-TUI supports two models: deepseek-v4-pro and deepseek-v4-flash. I didn't check carefully and used the default deepseek-v4-pro.

I used it for about two weeks of daily development work — code completion, bug fixes, technical design. When I checked the monthly bill, the token consumption was staggering — after one afternoon of development chat, the cost made me pause.

I then looked up the official pricing at platform.deepseek.com and cross-referenced with my actual API call logs:

• **deepseek-v4-flash**: approximately $0.27/M input tokens, $1.10/M output tokens (as of May 2026)
• **deepseek-v4-pro**: approximately $1.00/M input tokens, $2.00/M output tokens

For routine code completion and bug fixes, deepseek-v4-flash is sufficient. Only switch to pro when doing complex architectural design or tasks requiring deep reasoning.

Switch command:

/deepseek --model deepseek-v4-flash

Or press Shift+Tab in the TUI to cycle through reasoning effort levels (off → high → max).

My actual result: After switching to flash, my monthly bill dropped from approximately $47 to approximately $14 for the same workload. The difference was stark.

Trap 2: API key misconfiguration causes all requests to fail

DeepSeek-TUI requires a DeepSeek API key. The most common mistake is storing the key in an environment variable with the wrong name.

The correct approach: create a config file at ~/.config/deepseek-tui/config.json (if the directory doesn't exist, first run mkdir -p ~/.config/deepseek-tui):

{
  "api_key": "sk-your-key-here",
  "model": "deepseek-v4-flash",
  "base_url": "https://api.deepseek.com"
}

Specific mistakes I made:

• Environment variable `DEEPSEEK_API_KEY` written as `DEEPSEEK_KEY` → auth error
• Extra space before the key (carried over from copying from the web) → invalid key error
• Using an expired key (manually revoked in DeepSeek platform) → unauthorized error

Verify key correctness:

curl https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer sk-your-key-here"

If it returns JSON instead of a 401, the key is valid. I saved this as test-key.sh as a quick verification script.

Trap 3: MCP server configured but won't connect

DeepSeek-TUI has a built-in MCP client that connects to external MCP servers. This is a powerful feature, but the configuration is easy to get wrong.

My debugging journey: I needed a file-search MCP tool for a project. Following the docs, I configured ~/.config/deepseek-tui/mcp.json:

{
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"]
    }
  ]
}

Then I started DeepSeek-TUI, typed /mcp list, and got an error: MCP server connection timeout.

Debugging steps:

1. Confirm npx is available: npx -y @modelcontextprotocol/server-filesystem --help

2. Check port availability: lsof -i :3000 (this MCP server defaults to port 3000)

3. Check logs: deepseek-tui --debug — this debug log is what saved me

The actual problem: args order was wrong. The correct config separates executable from arguments:

{
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"],
      "env": {
        "PORT": "3000"
      }
    }
  ]
}

Once connected, you can say "search all .py files in the current directory" and DeepSeek-TUI automatically calls the MCP tool. I now use this filesystem MCP as a standard part of my daily development workflow.

Trap 4: Used session restore but lost context

DeepSeek-TUI has /save and /restore commands for saving and recovering sessions. This should be useful, but I hit a pitfall:

I saved a complex refactoring session with 50+ files, path: ~/.config/deepseek-tui/sessions/my重构会话.json.

Then one day I typed /restore my重构会话 and got: Session not found: my重构会话.

The problem: the session name contains Chinese characters and wasn't quoted. Also, Chinese filenames cause cross-platform compatibility issues (I use both macOS and Linux).

The correct command:

/restore "my重构会话"

Or better — use the session ID:

/restore session-abc123xyz

Every session save generates a session ID shown in the logs. Now I use English + timestamp naming only, like refactor-20260503 or bugfix-session-0512.

Trap 5: Thinking mode on but didn't know how to see output

DeepSeek-TUI's Thinking Mode streams the model's chain-of-thought in real time. But I didn't know how to read it — I thought the interface was frozen.

The thinking output is in a collapsible panel labeled 🤔 Thinking.... It's collapsed by default; you need to manually expand it.

Trigger: during thinking, press Ctrl+Space to toggle the thinking output panel.

Also, reasoning effort (via Shift+Tab) affects depth:

• **off**: no thinking chain, fastest response, suitable for simple tasks
• **high**: moderate reasoning depth, suitable for most daily development tasks
• **max**: full thinking chain, suitable for complex debugging scenarios — when I need to debug a tricky bug, I switch to max to see the full reasoning process

Prevention checklist

Before starting a new DeepSeek-TUI session, run through this:

1. **Confirm model**: use deepseek-v4-flash for routine tasks, check /model to see current config

2. Confirm mode: use Plan or Agent mode on unfamiliar projects, don't start with YOLO

3. **Confirm API Key**: test with curl (I made this an alias for quick checks)

4. **Confirm MCP**: after startup, run /mcp list to confirm all servers connected

5. Confirm session names: English only, no Chinese filenames in session saves

My tool selection experience

DeepSeek-TUI fits developers who work directly in the terminal — it reads and edits files, runs shell commands, searches the web, manages git, all in one interface, no tool-switching required.

But in team collaboration environments, or where you need audit logs of AI tool operations, YOLO mode's auto-execution is a risk. Agent mode (confirm each operation) is the better choice.

For development on remote servers or running automation on VPS instances, DeepSeek-TUI's HTTP service mode (deepseek serve --http) lets you call it via API — great for integrating into CI/CD pipelines.

Disclosure: This article involves DeepSeek-related products. I have no commercial relationship with DeepSeek. Pricing information reflects publicly available data as of May 2026; please verify current pricing on the official platform before making decisions.

👉 Try MiniMax Token Plan: https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link