GO — Healthy across the board

• Last commit today
• 19 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 72% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

DeepSeek TUI is a terminal-based coding agent that integrates with DeepSeek V4 models to read, edit, and execute code in your local workspace with streaming reasoning blocks and approval gates. It's a keyboard-driven TUI that leverages 1M-token context windows, prefix caching, and an 'auto mode' that selects both model tier and thinking level per request—turning the DeepSeek API into an interactive code assistant in the shell. 14-crate Rust monorepo under crates/: crates/cli (main entry point deepseek command), crates/tui (terminal UI runtime), crates/agent (reasoning and tool orchestration), crates/core (shared utilities), crates/tools (file ops, git, shell, web search), crates/mcp (Model Context Protocol servers), crates/protocol (DeepSeek API bindings), and config/secrets/state management crates. The CLI dispatcher spawns the TUI runtime (deepseek-tui binary) as the interactive session manager.

Developers and engineers who want to use DeepSeek as an AI coding copilot without leaving the terminal; people building automation pipelines or CI/CD workflows that need programmatic access to reasoning-capable LLMs; teams in China and globally who prefer DeepSeek over OpenAI and want cost-efficient reasoning with a 1M context window.

Actively developed and production-ready. The project is at v0.8.17 with a comprehensive CI/CD pipeline (GitHub Actions for CI, release, nightly builds), release binaries for Linux/macOS/Windows across multiple architectures, and distribution via npm, Cargo, and Homebrew. However, it is maintained by a small core team (single primary maintainer visible), so durability depends on continued funding and interest.

Low-to-medium risk for a terminal tool. The codebase is large (6.6 MB Rust alone) with a 14-crate monorepo structure that increases surface area. External dependencies include reqwest, tokio, and rusqlite; breaking changes occurred in v0.8.x (see V086_BRIEF.md). The most significant risk is maintainer concentration: if the primary author steps back, community contribution velocity becomes critical. DeepSeek API dependency also means service outages directly block the tool.

Recent work centers on v0.8.17 stability and feature polish (see CHANGELOG.md and V086_BRIEF.md). There's active investment in reasoning-effort tier cycling (Shift+Tab to rotate through off → high → max), session checkpointing/resume, workspace rollback via side-git snapshots, and MCP server integration. Nightly builds and auto-tag workflows indicate rapid iteration. The .claude/v0.8.10-handoff-2.md suggests recent architectural refinements.

Clone, install, and run:

git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI

# Install via Cargo (requires Rust 1.88+)
cargo install deepseek-tui-cli --locked
cargo install deepseek-tui --locked

# Or via npm
npm install -g deepseek-tui

# Set your DeepSeek API key
export DEEPSEEK_API_KEY="your-key-here"

# Run
deepseek --help
deepseek "your coding task here"

Daily commands:

# Development: build all crates
cargo build --workspace

# Run CLI entry point
cargo run -p deepseek-tui-cli -- --help

# Run TUI runtime (usually spawned by CLI)
cargo run -p deepseek-tui

# Run app-server (HTTP API backend)
cargo run -p deepseek-app-server

# Test
cargo test --workspace

# Release build
cargo build --release --workspace

• crates/cli/src/main.rs — Entry point for the deepseek dispatcher command; routes user input to TUI or agent modes
• crates/tui/src/lib.rs — Core TUI runtime orchestrator; manages terminal UI lifecycle, event handling, and approval gates for workspace edits
• crates/core/src/lib.rs — Agent logic and reasoning loop; coordinates LLM calls to DeepSeek V4, tool invocations, and state management
• crates/protocol/src/lib.rs — Message protocol definitions between CLI and TUI; serialization/deserialization for streaming reasoning blocks
• crates/config/src/lib.rs — Configuration loading and validation; handles API keys, model selection, and thinking level defaults
• crates/tools/src/lib.rs — Tool execution sandbox and file editor interface; enforces execution policy and workspace boundaries
• Cargo.toml — Workspace root; defines all 14 member crates, shared versions, and Rust 1.88+ requirement

Add a new tool for the agent

1. Define the tool struct and execution logic in the tool registry (crates/tools/src/lib.rs)
2. Add execution policy rules if the tool runs shell commands (crates/execpolicy/src/lib.rs)
3. Register the tool in the agent's tool_registry so DeepSeek can call it (crates/agent/src/lib.rs)
4. Add MCP resource definitions if exposing via Model Context Protocol (crates/mcp/src/lib.rs)

Add a new reasoning mode or thinking level

1. Define the thinking level enum and selection logic in core agent loop (crates/core/src/lib.rs)
2. Map the thinking level to DeepSeek API parameters in the API client (crates/agent/src/lib.rs)
3. Add configuration defaults and schema validation (crates/config/src/lib.rs)
4. Update protocol message types to include the new thinking level (crates/protocol/src/lib.rs)
5. Wire the UI controls in the TUI to select and display the mode (crates/tui/src/lib.rs)

Add a new CLI command or mode

1. Add the command variant to the CLI argument parser and dispatch logic (crates/cli/src/main.rs)
2. Implement the command handler in the CLI library, using core or agent modules (crates/cli/src/lib.rs)
3. Add metrics or tracing for the new command if needed (crates/cli/src/metrics.rs)
4. Update the protocol if the new command requires TUI communication (crates/protocol/src/lib.rs)

Customize approval gates for workspace edits

1. Define the approval policy rules and thresholds (file size, sensitive paths, etc.) (crates/tools/src/lib.rs)
2. Implement or extend the approval UI panel to display pending edits (crates/tui/src/acp_server.rs)
3. Wire the approval decision back to the tool executor with an allow/deny response (crates/hooks/src/lib.rs)

• Rust 1.88+ — Memory safety without GC; fast terminal rendering; let_chains for complex reasoning logic
• DeepSeek V4 API — Primary reasoning model; native streaming for real-time token output; thinking blocks for agent transparency
• Ratatui (TUI framework) — Cross-platform terminal UI; supports Sixel/iTerm2 images; event-driven architecture for async rendering
• Tokio async runtime — Non-blocking I/O for API calls, file operations, and terminal events; enables streaming without buffering
• Serde for serialization — Protocol messages between CLI and TUI; config file parsing (TOML); state snapshots
• Model Context Protocol (MCP) — Standardized tool and resource discovery; allows third-party LLM clients to invoke agent tools

• Separate CLI dispatcher and TUI runtime as distinct binaries

  • Why: Allows non-TUI modes (scripts, servers) and prevents terminal initialization overhead for headless calls
  • Consequence: Added IPC protocol complexity; requires CLI↔TUI message serialization

• Approval gates for all file edits (not auto-write)

  • Why: Safety: prevents accidental code generation disasters; builds user trust
  • Consequence: Slower iteration in agentic loops; UX burden when user must approve each edit

• Native Rust TUI instead of web-based UI

  • Why: Works offline; no browser/Node.js dependency; zero latency rendering of streaming tokens
  • Consequence: Limited to terminal capabilities (no rich HTML/CSS); harder to embed in IDEs

• Auto-mode that selects thinking level per turn

  • Why: Optimizes cost and speed; complex questions get deep thinking, simple ones are instant
  • Consequence: Adds decision logic complexity; users must trust heuristics

• Execution policy validation (bash arity, path whitelisting)

  • Why: Prevent shell injection and dangerous commands in generated code
  • Consequence: May block legitimate edge-case commands; requires policy configuration

• Does not handle

1. Rust 1.88+ required: The workspace enforces this via rust-version = 1.88 in Cargo.toml due to let_chains stabilization; older Rust toolchains will fail with a version error, not a clear compilation error. 2. DeepSeek API key mandatory: DEEPSEEK_API_KEY env var must be set; if missing, the agent cannot function and will error at runtime. 3. Prefix-cache awareness in billing: The codebase tracks prefix-cache telemetry per turn; cost calculations assume this is enabled in your DeepSeek API account or will report misleading totals. 4. Breaking changes in v0.8.x: See V086_BRIEF.md—session format and config structure changed; old sessions may not load in new versions. 5. TUI runs as separate binary: The dispatcher (deepseek-cli) spawns deepseek-tui as a child process; if the TUI binary is not in PATH, the command fails silently. 6. Git snapshots require .git: Workspace rollback via side-git snapshots assumes a git repo exists; non-git directories will fail rollback. 7. Single-threaded TUI event loop: Crossterm/Ratatui TUI is single-threaded; long-running operations block screen updates—this is intentional (see streaming reasoning) but can feel unresponsive if a tool hangs.

• Prefix Caching — DeepSeek V4 supports prefix caching to reduce latency and cost on repeated context; the codebase explicitly tracks and reports prefix-cache hits in telemetry and cost calculations, so understanding how it works is essential for interpreting billing and performance.
• Streaming Reasoning Blocks — DeepSeek's 'thinking mode' allows you to stream the model's internal reasoning in real time; DeepSeek TUI renders these blocks in the TUI, so you need to understand how streaming SSE/chunked responses work to debug or extend the feature.
• Tool Use / Function Calling — The agent orchestrates tool calls (file ops, shell, git) by the LLM selecting and invoking tools; understanding OpenAI-style function schemas and the request-response loop is critical to adding new tools or modifying tool signatures.
• Model Context Protocol (MCP) — DeepSeek TUI integrates MCP servers for extensibility; understanding MCP's request/response model and tool advertisement is needed to add custom integrations beyond built-in tools.
• 1M-Token Context Windows — DeepSeek V4 models support 1 million tokens of context; the codebase implements context tracking and compaction strategies to stay within limits while maximizing history—critical for long-running agent sessions.
• Approval Gates (RBAC-lite) — Three modes (Plan, Agent, YOLO) control whether the LLM's tool calls need human approval before execution; this is a safety pattern to prevent unintended file/command execution and is core to the agent's design.
• Side-Git Snapshots — The agent maintains git snapshots before and after each turn to enable workspace rollback; understanding this pattern (creating parallel commits for undo) helps you modify or debug state recovery.
• Async Rust / Tokio — The entire codebase is async-first using Tokio for concurrency (streaming API responses, parallel tool calls, TUI event loop); you must understand async/await patterns and channels to modify control flow or add features.

• huggingface/transformers — De facto standard for local LLM serving; DeepSeek TUI complements transformers by providing a terminal UI around DeepSeek API calls rather than local inference
• continuedev/continue — IDE-based coding agent (VS Code, JetBrains); solves the same problem (AI-assisted code editing) but for editors instead of terminals
• openai/openai-python — OpenAI's Python SDK; DeepSeek TUI is the spiritual Rust equivalent for DeepSeek, with added terminal UI and reasoning-streaming
• aider-ai/aider — Python-based terminal coding agent for local LLMs and APIs; direct competitor with similar feature set (file editing, tool calling, approval gates) but different implementation
• deepseek-ai/DeepSeek-API — Official DeepSeek API documentation and examples; DeepSeek TUI is a consumer of the DeepSeek API and tracks breaking changes there

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for MCP (Model Context Protocol) crate

The crates/mcp directory exists but has no visible test files. Given that MCP is a critical integration point for the DeepSeek agent to communicate with external tools and context sources, comprehensive integration tests would validate the protocol implementation and prevent regressions. This is especially important for a coding agent that relies on tool execution.

• [ ] Create crates/mcp/tests/ directory with integration test modules
• [ ] Add tests for MCP protocol message serialization/deserialization in crates/mcp/tests/protocol.rs
• [ ] Add tests for MCP client/server lifecycle in crates/mcp/tests/integration.rs
• [ ] Update crates/mcp/Cargo.toml with dev-dependencies (tokio, serde_json for testing)
• [ ] Document test setup in CONTRIBUTING.md section on running MCP tests

Add execution policy validation tests for execpolicy crate

The crates/execpolicy crate contains bash_arity.rs and lib.rs but lacks visible test coverage. Since this crate controls whether the agent can execute commands (a security-critical function), comprehensive unit tests for various command validation scenarios would improve safety and allow contributors to refactor with confidence.

• [ ] Create crates/execpolicy/tests/ directory with test modules
• [ ] Add unit tests in crates/execpolicy/src/lib.rs for policy validation logic (test cases for safe/unsafe commands)
• [ ] Add integration tests in crates/execpolicy/tests/bash_commands.rs testing bash_arity parsing against real bash command patterns
• [ ] Test edge cases: complex piping, subshells, command substitution, permission levels
• [ ] Update crates/execpolicy/Cargo.toml with dev-dependencies if needed

Document config validation and migration path in CONTRIBUTING.md

The repo has config.example.toml and .env.example but no documented validation rules or migration guide for config changes between versions. As the version is 0.8.17, contributors need clear guidance on how to modify config schema, validate user configs, and provide upgrade paths. This prevents breaking user setups.

• [ ] Create a new section 'Config Development' in CONTRIBUTING.md
• [ ] Document the config validation pipeline: crates/config/src/lib.rs parsing and validation flow
• [ ] Add a checklist for adding new config fields: update config.example.toml, add validation tests in crates/config/src/lib.rs, document migration in CHANGELOG.md
• [ ] Reference crates/config/Cargo.toml dependencies (serde, toml) used for validation
• [ ] Add example: show how a recent config change was validated and communicated (check git history for version bumps)

• Add unit tests for crates/tools/src/lib.rs file operations (read, write, patch apply). Currently no tests visible in the file list; start with parameterized tests for edge cases like symlinks, large files, and permission errors.
• Write integration tests for session save/resume in crates/state/src/ using rusqlite. Create fixtures for sample sessions, verify checkpoint schema round-tripping, and test rollback on corrupt state files.
• Improve error messages in crates/protocol/src/ for DeepSeek API failures. Currently generic HTTP errors; add structured error types for rate limits, auth, model-not-found, and context-overflow so users understand what went wrong.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Hmbown/DeepSeek-TUI shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Hmbown/DeepSeek-TUI repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Hmbown/DeepSeek-TUI.

What it runs against: a local clone of Hmbown/DeepSeek-TUI — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Hmbown/DeepSeek-TUI | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Hmbown/DeepSeek-TUI. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Hmbown/DeepSeek-TUI.git
#   cd DeepSeek-TUI
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Hmbown/DeepSeek-TUI and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Hmbown/DeepSeek-TUI(\\.git)?\\b" \\
  && ok "origin remote is Hmbown/DeepSeek-TUI" \\
  || miss "origin remote is not Hmbown/DeepSeek-TUI (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "crates/cli/src/main.rs" \\
  && ok "crates/cli/src/main.rs" \\
  || miss "missing critical file: crates/cli/src/main.rs"
test -f "crates/tui/src/lib.rs" \\
  && ok "crates/tui/src/lib.rs" \\
  || miss "missing critical file: crates/tui/src/lib.rs"
test -f "crates/core/src/lib.rs" \\
  && ok "crates/core/src/lib.rs" \\
  || miss "missing critical file: crates/core/src/lib.rs"
test -f "crates/protocol/src/lib.rs" \\
  && ok "crates/protocol/src/lib.rs" \\
  || miss "missing critical file: crates/protocol/src/lib.rs"
test -f "crates/config/src/lib.rs" \\
  && ok "crates/config/src/lib.rs" \\
  || miss "missing critical file: crates/config/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Hmbown/DeepSeek-TUI"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.