CodeWhale (DeepSeek-TUI): El Agente de Terminal Open Source Impulsado por DeepSeek V4 — Guía Completa 2026

Si eres desarrollador y buscas un agente de codificación en terminal potente, open source y optimizado para DeepSeek V4, entonces CodeWhale (anteriormente DeepSeek-TUI) es exactamente lo que necesitas. Con más de 34.000 estrellas en GitHub, se ha convertido en una de las herramientas más populares para trabajar con modelos de IA desde la terminal.

En esta guía completa te mostraré cómo instalar y usar CodeWhale, desde cero hasta nivel avanzado.

¿Qué es CodeWhale?

CodeWhale (originalmente DeepSeek-TUI) es un agente de codificación con IA construido en Rust que funciona directamente desde tu terminal. Está diseñado específicamente para DeepSeek V4 (deepseek-v4-pro y deepseek-v4-flash), pero soporta más de 12 proveedores diferentes.

Es un proyecto de código abierto con licencia MIT, creado por Hmbown y alojado en github.com/Hmbown/CodeWhale.

Características Principales

• 🐳 DeepSeek-first — Optimizado para DeepSeek V4 con ventanas de 1M de tokens
• 🔄 Auto-routing de modelos — Elige automáticamente el modelo y nivel de razonamiento
• 💭 Thinking-mode streaming — Ve los bloques de razonamiento de DeepSeek en tiempo real
• 🔧 Suite completa de herramientas — Archivos, shell, git, web, navegador, MCP, sub-agentes
• 📋 Tres modos de trabajo — Plan (solo lectura), Agent (interactivo), YOLO (auto-aprobado)
• 💾 Guardar/Reanudar/Fork — Sesiones persistentes y bifurcables
• 🔄 Rollback de workspace — Snapshots pre/post turno con side-git
• 🌐 API HTTP/SSE — Servidor headless para flujos automatizados
• 🎨 Temas integrados — Catppuccin, Tokyo Night, Dracula, Gruvbox y más
• 🌍 UI localizada — Inglés, japonés, chino simplificado, portugués (BR)
• 📊 Seguimiento de costos — Por turno y por sesión, con breakdown de caché
• 🧩 Sistema de skills — Paquetes de instrucciones instalables desde GitHub
• 🖥️ Diagnóstico LSP — Errores/advertencias inline tras cada edición

CodeWhale vs OpenCode vs Claude Code

Paso 1: Instalar CodeWhale

CodeWhale se distribuye en dos binarios de Rust: el comando principal codewhale y el runtime TUI codewhale-tui. Elige el método que más te convenga:

1.1 Instalación vía npm (recomendada)

npm install -g codewhale

El paquete npm descarga ambos binarios precompilados desde GitHub Releases. Es la forma más fácil si ya usas Node.

1.2 Instalación vía Cargo (Rust)

Requiere Rust 1.88+ (edición 2024):

cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

1.3 Instalación vía Homebrew (macOS/Linux)

brew tap Hmbown/deepseek-tui
brew install deepseek-tui

1.4 Instalación vía Docker

docker volume create codewhale-home

docker run --rm -it   -e DEEPSEEK_API_KEY="tu-api-key"   -v codewhale-home:/home/codewhale/.deepseek   -v "$PWD:/workspace"   -w /workspace   ghcr.io/hmbown/codewhale:latest

1.5 Descarga directa

Descarga los binarios precompilados desde GitHub Releases. Disponible para Linux x64/ARM64, macOS x64/ARM64 y Windows x64.

1.6 Verificar la instalación

codewhale --version

Paso 2: Configurar tu API Key

2.1 Obtener una API Key de DeepSeek

Ve a platform.deepseek.com/api_keys y crea una nueva clave.

2.2 Configurar la API Key en CodeWhale

codewhale auth set --provider deepseek   # Guarda la key en ~/.deepseek/config.toml
codewhale auth status                    # Verifica la configuración
codewhale doctor                         # Diagnóstico completo

También puedes usar la variable de entorno:

export DEEPSEEK_API_KEY="tu-api-key"
codewhale

2.3 Soportes para múltiples proveedores

CodeWhale soporta 12 proveedores. Aquí algunos ejemplos:

# NVIDIA NIM
codewhale auth set --provider nvidia-nim --api-key "TU_API_KEY"
codewhale --provider nvidia-nim

# OpenRouter (acceso a Claude, GPT, Gemini, etc.)
codewhale auth set --provider openrouter --api-key "TU_API_KEY"
codewhale --provider openrouter --model deepseek/deepseek-v4-pro

# OpenAI
codewhale auth set --provider openai --api-key "TU_API_KEY"
OPENAI_BASE_URL="https://openai-compatible.example/v4" codewhale --provider openai --model deepseek-v4-pro

Paso 3: Primeros Pasos

3.1 Iniciar CodeWhale

cd /ruta/de/tu/proyecto
codewhale

O usa el alias corto codew (funciona en todas partes):

codew

3.2 Modo interactivo TUI

Una vez dentro, verás una interfaz de terminal con:

• Composer — donde escribes tus prompts
• Transcript — historial de la conversación
• Status line — modo activo, modelo, costo, estabilidad de caché

Escribe tu primer prompt:

Explícame cómo funciona este proyecto

3.3 Modos de trabajo

Presiona Tab para ciclar entre los tres modos:

• Plan 🔍 — Solo lectura. Explora el código y crea planes sin hacer cambios.
• Agent 🤖 — Modo interactivo por defecto. Herramientas multi-paso con aprobación.
• YOLO ⚡ — Auto-aprobación de herramientas. Máxima velocidad en entornos de confianza.

3.4 Modelo Auto-Routing

Una de las características más potentes de CodeWhale. Usa:

codewhale --model auto

O dentro del TUI, usa /model auto. El sistema usa un pequeño modelo "Fin" (deepseek-v4-flash con thinking off) para decidir:

• Qué modelo usar (Flash o Pro)
• Qué nivel de razonamiento aplicar (off, high, max)

Las tareas simples se quedan en Flash/off (rápido y barato). Las tareas complejas escalan a Pro/max (máxima calidad). El routing es transparente: ves qué ruta se eligió en cada turno.

5 Niveles de Razonamiento

Usa Shift+Tab para ciclar: off → high → max.

Paso 4: Funcionalidades Avanzadas

4.1 Sub-agentes Concurrentes

CodeWhale puede lanzar hasta 20 sub-agentes en paralelo. Cada uno tiene su propio contexto y herramientas:

• agent_open — Lanza un sub-agente y continúa trabajando
• Notificación automática — Cuando termina, llega un evento structured
• Resultados acotados — Transcripts grandes se almacenan como referencias

4.2 Sesiones y Forking

codewhale sessions                    # Listar sesiones guardadas
codewhale resume --last               # Reanudar última sesión
codewhale resume <SESSION_ID>        # Reanudar sesión específica
codewhale fork <SESSION_ID>          # Bifurcar una sesión guardada

Dentro del TUI, Ctrl+R abre el selector de sesiones. Las sesiones bifurcadas mantienen un registro del padre.

4.3 Rollback de Workspace

CodeWhale toma snapshots pre/post turno usando un sistema side-git (no toca tu repositorio principal):

/restore              # Restaurar archivos desde el snapshot
revert_turn           # Revertir el turno completo

4.4 Atajos de teclado

4.5 Sistema de Skills

CodeWhale trae skills integrados desde el primer inicio:

/skills                   # Listar skills disponibles
/skill <nombre>           # Activar un skill
/skill new                # Crear un nuevo skill
/skill install github:<owner>/<repo>  # Instalar skill comunitario

Skills incluidos: skill-creator, mcp-builder, plugin-creator, v4-best-practices, documents, presentations, spreadsheets, pdf, feishu, skill-installer, delegate.

4.6 API HTTP (Headless)

Para flujos automatizados:

codewhale serve --http        # Servidor HTTP/SSE
codewhale serve --acp         # Protocolo ACP para Zed/IDEs

4.7 Temas

Cambia el tema con /theme dentro del TUI. Temas disponibles:

• Catppuccin (Mocha, Latte, Frappé, Macchiato)
• Tokyo Night
• Dracula
• Gruvbox
• Claro y oscuro originales

Uso desde Línea de Comandos

# One-shot prompt
codewhale "explica esta función"

# Modo agente con auto-aprobación
codewhale exec --auto "arregla este bug"

# Forzar modelo específico
codewhale --model deepseek-v4-flash "resume este código"

# Auto-routing de modelo
codewhale --model auto "debuggea este error"

# Modo YOLO (todo auto-aprobado)
codewhale --yolo

Gestión de Costos

CodeWhale muestra el costo estimado por turno y por sesión, con desglose de cache hit/miss. Si usas locale zh-Hans, los costos se muestran en CNY.

CodeWhale para SWE-bench

CodeWhale puede ejecutar evaluaciones SWE-bench:

codewhale swebench run   --instance-id django__django-12345   --issue-file issue.md   --predictions-path all_preds.jsonl

Integración con Editores (ACP/Zed)

Puedes usar CodeWhale como motor de IA en Zed:

{
  "agent_servers": {
    "DeepSeek": {
      "type": "custom",
      "command": "codewhale",
      "args": ["serve", "--acp"],
      "env": {}
    }
  }
}

Solución de Problemas

Conclusión

CodeWhale es una herramienta excepcional para desarrolladores que trabajan con DeepSeek V4. Sus puntos fuertes:

• 🐳 Optimizado para DeepSeek — Aprovecha al máximo deepseek-v4-pro y flash
• 🔄 Auto-routing inteligente — El modelo y razonamiento se ajustan solos
• ⚡ Rápido en Rust — Rendimiento nativo, sin Node.js runtime pesado
• 🔧 12 proveedores — DeepSeek, OpenAI, OpenRouter, NVIDIA, y más
• 📋 Sub-agentes concurrentes — Hasta 20 tareas en paralelo
• 🔄 Rollback de workspace — Recuperación sin tocar tu git
• 🌐 API HTTP headless — Ideal para CI/CD y automatizaciones
• 🎨 Temas personalizables — Catppuccin, Tokyo Night, Dracula...

Es la herramienta perfecta si ya usas DeepSeek V4 y quieres un agente de terminal que exprima al máximo sus capacidades. Con 34.800+ estrellas en GitHub, cuenta con una comunidad activa y contribuciones de cientos de desarrolladores.

¡Pruébalo hoy mismo!

npm install -g codewhale
codewhale --version
codewhale auth set --provider deepseek
codewhale doctor
codewhale

Enlaces Útiles

• Sitio oficial de CodeWhale
• GitHub: Hmbown/CodeWhale
• DeepSeek API Keys
• Documentación de DeepSeek API
• GitHub Releases — Descargas directas