DeepSeek-TUI: 터미널에서 동작하는 DeepSeek V4 코딩 에이전트(Coding Agent)

9bow · 5월 22, 2026, 9:30오전

DeepSeek-TUI 소개

DeepSeek-TUI는 DeepSeek의 최신 V4 계열 모델(deepseek-v4-pro, deepseek-v4-flash)을 터미널에서 직접 활용할 수 있도록 만든 코딩 에이전트(Coding Agent)입니다. 단순히 채팅창을 띄워주는 래퍼(wrapper)가 아니라, 파일 읽기와 편집, 셸 명령 실행, git 조작, 웹 검색, 서브 에이전트(Sub-agent) 호출, MCP(Model Context Protocol) 서버 연동까지 폭넓은 도구를 갖춘 자율 에이전트(Autonomous Agent)에 가깝습니다. 사용자는 키보드만으로 작업 흐름을 제어하면서, 모델이 워크스페이스를 어떻게 탐색하고 수정하는지를 실시간으로 확인할 수 있습니다.

이 프로젝트는 Rust로 작성된 두 개의 바이너리(deepseek 디스패처와 deepseek-tui 런타임)로 배포되며, npm, Cargo, Homebrew, Scoop, Docker, 직접 다운로드 등 다양한 설치 경로를 제공합니다. 1M 토큰 컨텍스트 윈도우(1M-token context)와 추론 블록 스트리밍(thinking-mode streaming), 프리픽스 캐시(Prefix Cache) 인지 비용 추적(cost tracking)이 핵심 특징이며, DeepSeek 플랫폼뿐 아니라 NVIDIA NIM, Fireworks, OpenRouter, SGLang, vLLM, Ollama 같은 외부 추론 백엔드도 함께 지원합니다. 덕분에 모델 추론을 자체 서버에서 운영하는 환경에서도 동일한 에이전트 워크플로(Workflow)를 그대로 활용할 수 있습니다.

DeepSeek-TUI는 단순한 보조 도구가 아니라, 장시간 작업을 안전하게 이어갈 수 있는 운영 환경을 함께 제공한다는 점이 두드러집니다. 세션 저장과 재개(Session save/resume), 워크스페이스 롤백(Workspace rollback), 영속 작업 큐(Durable task queue), HTTP/SSE 런타임 API(deepseek serve --http) 등을 통해 헤드리스(headless) 환경이나 IDE 통합(Zed의 ACP 어댑터)에서도 동일한 코드를 활용할 수 있도록 설계되어 있습니다. 또한 LSP 진단(rust-analyzer, pyright, typescript-language-server, gopls, clangd) 통합으로 매 편집 직후 컴파일러 오류와 경고를 모델 컨텍스트로 다시 흘려보내, 다음 추론 단계가 진단을 반영하도록 합니다.

DeepSeek-TUI의 주요 기능

DeepSeek-TUI는 단순한 채팅 인터페이스를 넘어선 풀스택(full-stack) 에이전트 도구를 한 곳에 모아두었습니다. 자율 모드 선택과 도구 사용 권한, 비용·진단(diagnostics) 추적 등이 모두 하나의 키보드 워크플로 안에서 자연스럽게 연결됩니다. 다음은 README에 정리된 핵심 기능을 한국어 관점에서 재구성한 것입니다.

자동 모드(Auto Mode): --model auto 또는 /model auto 옵션을 사용하면 짧은 deepseek-v4-flash 라우팅 호출이 먼저 실행되어 모델(Flash/Pro)과 추론 강도(off/high/max)를 자동으로 선택합니다. 가벼운 질문은 Flash를 그대로 유지하고, 코드 디버깅이나 아키텍처 검토처럼 복잡한 작업은 Pro와 더 높은 thinking level로 자연스럽게 승급됩니다.
추론 블록 스트리밍(Thinking-mode streaming): DeepSeek V4의 사고 과정(reasoning blocks)이 그대로 화면에 표시되어 모델이 어떤 가설을 검토하고 어떤 도구를 호출했는지 추적할 수 있습니다.
세 가지 실행 모드: Plan(읽기 전용 탐색), Agent(승인 게이트가 있는 일반 모드), YOLO(신뢰된 워크스페이스에서 도구를 자동 승인) 세 가지 모드를 Tab으로 전환할 수 있어, 위험도와 자동화 수준을 상황에 맞게 조절할 수 있습니다.
서브 에이전트(Sub-agents): agent_open 호출로 자식 에이전트(child agent)를 비동기 실행할 수 있으며 기본 10개, 최대 20개까지 동시 실행 가능합니다. 큰 결과물은 var_handle로 참조되고 handle_read로 슬라이스(slice), 범위(range), JSONPath 투영(projection)을 통해 부모 컨텍스트(parent context)를 가볍게 유지합니다.
워크스페이스 롤백 및 스냅샷: 사용자의 .git 디렉토리에 손대지 않고 사이드(git) 스냅샷을 만들어 /restore, revert_turn으로 변경 사항을 되돌릴 수 있습니다.
LSP 진단 통합: 코드 편집이 일어날 때마다 LSP가 보고한 오류·경고를 모델 컨텍스트에 주입하여 다음 추론에서 자연스럽게 수정이 이어집니다.
MCP 프로토콜 연동: Model Context Protocol 서버를 그대로 붙여 외부 도구·데이터를 사용하는 확장 가능한 에이전트 환경을 구성할 수 있습니다.
세션과 비용 추적: 세션별 토큰 사용량과 캐시 적중률(prefix cache hit/miss), 모델별 비용 추정치가 실시간으로 표시되어 장시간 작업의 비용 통제(cost control)가 쉬워집니다.

DeepSeek-TUI의 아키텍처와 동작 방식

내부적으로 deepseek(디스패처 CLI)는 사용자가 입력한 명령을 받아 deepseek-tui 런타임을 구동하고, ratatui 기반 TUI 인터페이스가 비동기 엔진과 OpenAI 호환 스트리밍 클라이언트를 중개합니다. 도구 호출은 셸, 파일 작업, git, 웹, 서브 에이전트, MCP, RLM(Recursive Language Model)을 망라하는 타입드(Typed) 레지스트리(registry)를 거치며, 호출 결과는 다시 스트리밍 형태로 트랜스크립트(transcript)에 누적됩니다. 엔진은 세션 상태, 턴 트래킹(turn tracking), 영속 작업 큐, 그리고 LSP 진단을 다음 추론 컨텍스트로 주입하는 역할까지 함께 담당합니다.

특히 0.8.33 릴리스에서 도입된 영속 RLM 세션(rlm_open, rlm_eval, rlm_close)과 분기 인지 서브 에이전트(agent_open의 fork_context)는 대규모 결과를 다루는 워크플로에 적합합니다. RLM 작업은 peek, search, chunk, sub_query, sub_query_batch, finalize 같은 유한(bounded) REPL 헬퍼를 모델이 직접 호출하면서 진행되며, 부모 모델은 foreground 루프 없이 도구 호출만으로 작업을 지휘합니다. 큰 트랜스크립트나 결과 객체는 var_handle 참조로 보관되고, 필요한 슬라이스만 handle_read로 가져와 컨텍스트 사용량을 통제합니다.

DeepSeek-TUI의 설치 및 사용법

DeepSeek-TUI는 다양한 패키지 매니저와 사전 빌드된 바이너리를 함께 제공합니다. 가장 손쉬운 경로는 npm이며, Node가 설치되어 있다면 npm install -g deepseek-tui 한 줄로 매칭되는 Rust 바이너리가 GitHub Releases에서 자동으로 다운로드됩니다. 이후 첫 실행 시 DeepSeek API 키를 입력하라는 안내가 표시되며, 키는 ~/.deepseek/config.toml에 저장되어 어느 디렉토리에서도 동일하게 사용됩니다.

# 1. npm 설치 경로 (Rust 바이너리를 자동 다운로드)
npm install -g deepseek-tui

# 2. Cargo 설치 경로 (Rust 1.88+ 필요)
cargo install deepseek-tui-cli --locked   # `deepseek` 디스패처
cargo install deepseek-tui     --locked   # `deepseek-tui` 런타임

# 3. Homebrew (macOS)
brew tap Hmbown/deepseek-tui
brew install deepseek-tui

# 4. Docker (사전 빌드된 릴리스 이미지)
docker run --rm -it \
  -e DEEPSEEK_API_KEY \
  -v "$PWD:/workspace" \
  ghcr.io/hmbown/deepseek-tui:latest

자주 사용하는 기본 명령들은 다음과 같습니다. 자동 모드와 YOLO 모드, 세션 재개 등을 조합하면 짧은 한 줄 프롬프트(One-shot)부터 장기 백엔드 작업까지 동일한 도구로 처리할 수 있습니다.

deepseek                                          # 대화형 TUI
deepseek "explain this function"                  # 1회성 프롬프트
deepseek --model auto "fix this bug"              # 자동 모델/추론 선택
deepseek --model deepseek-v4-flash "summarize"    # 모델 고정
deepseek --yolo                                   # 도구 자동 승인 모드
deepseek exec --auto --output-format stream-json "fix this bug"
deepseek resume --last                            # 마지막 세션 이어가기
deepseek serve --http                             # 헤드리스 HTTP/SSE 서버
deepseek mcp list                                 # MCP 서버 목록 확인
deepseek doctor                                   # 설정/연결 점검

DeepSeek-TUI는 NVIDIA NIM, Fireworks, OpenAI 호환 엔드포인트, 자체 호스팅 SGLang·vLLM·Ollama 같은 다양한 백엔드도 그대로 지원합니다. 예를 들어 자체 호스팅 vLLM 환경에서는 VLLM_BASE_URL 환경 변수를 설정한 뒤 deepseek --provider vllm --model deepseek-v4-flash처럼 호출해 동일한 워크플로를 유지할 수 있습니다.

DeepSeek-TUI의 모델과 가격 정책

DeepSeek-TUI는 두 가지 V4 계열 모델을 기본으로 사용합니다. deepseek-v4-pro는 1M 토큰 컨텍스트와 가장 높은 추론 품질을 제공하고, deepseek-v4-flash는 더 저렴한 비용으로 가벼운 작업과 자동 라우팅을 담당합니다. 비용 정보는 TUI 안에서 실시간으로 표시되며, README에 정리된 표는 다음과 같습니다.

모델	컨텍스트	입력(캐시 적중)	입력(캐시 미스)	출력
`deepseek-v4-pro`	1M	$0.003625 / 1M*	$0.435 / 1M*	$0.87 / 1M*
`deepseek-v4-flash`	1M	$0.0028 / 1M	$0.14 / 1M	$0.28 / 1M

DeepSeek-V4-Pro에는 현재 75% 한시 할인이 적용되어 있으며, 이 할인은 README 기준으로 UTC 2026년 5월 31일 15:59까지 유효합니다. 정확한 최신 가격은 DeepSeek 공식 가격 페이지에서 확인하는 것이 안전합니다. 또한 deepseek-chat, deepseek-reasoner 같은 레거시 별칭(alias)은 deepseek-v4-flash로 매핑되며, 2026년 7월 24일 이후 폐기될 예정입니다.

라이선스

DeepSeek-TUI는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용하고 수정·재배포할 수 있습니다. 다만 DeepSeek Inc.와 공식적으로 제휴된 프로젝트가 아니라는 점이 README에 명시되어 있으므로, 모델 사용 정책은 별도로 DeepSeek 측 약관을 함께 확인하는 것이 좋습니다.

DeepSeek-TUI 공식 홈페이지

DeepSeek-TUI DeepWiki 문서

DeepSeek-TUI 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~