GitHub - cynchro/deepseekCLI

deep

CLI/REPL para generar proyectos completos usando la API de DeepSeek. Le das una descripción en lenguaje natural y genera los archivos, los evalúa, y aprende de cada ejecución para mejorar las siguientes. Hecho con ❤ por Cynchro Labs Instalación PyPI pip install deepseek-builder Linux / macOS bash <(curl -fsSL https://raw.githubusercontent.com/cynchro/deepseekCLI/main/install.sh) O desde el repositorio clonado: git clone https://github.com/cynchro/deepseekCLI.git cd deepseekCLI bash install.sh Windows Desde PowerShell (requiere Python 3.9+ instalado): git clone https://github.com/cynchro/deepseekCLI.git cd deepseekCLI .\install.ps1 O de forma remota: irm https://raw.githubusercontent.com/cynchro/deepseekCLI/main/install.ps1 | iex

El instalador crea un entorno virtual en ~\.local\share\deepseekcli, agrega el comando deep al PATH de usuario, y guarda la API key como variable de entorno de Windows. Abrí una nueva terminal después de instalar.

Configuración de la API key La primera vez que ejecutes deep te pedirá la API key y la guardará automáticamente. Obtené la tuya en platform.deepseek.com. Para cambiarla más adelante: deep config set-key O con una variable de entorno (tiene prioridad sobre el archivo de config): # Linux/macOS export DEEPSEEK_API_KEY=tu_key_aqui

# Windows PowerShell $env:DEEPSEEK_API_KEY = "tu_key_aqui"

# Windows (permanente) setx DEEPSEEK_API_KEY "tu_key_aqui"

Uso REPL interactivo deep Abre un REPL con autocompletado e historial. Desde ahí podés usar todos los comandos. Modo directo (scripting) Todos los comandos también funcionan directamente desde la terminal: deep build "API REST en FastAPI con autenticación JWT" deep ask "cómo funciona Redis?"

deep doctor

Comandos build — Genera un proyecto deep build "descripción del proyecto" deep build -t tarea.txt # carga la descripción desde un archivo deep build "app Flask con SQLite" -f # corrige automáticamente si falla deep build "landing page en HTML/CSS" -o ~/dir # especifica directorio de salida deep build "compilador de expresiones" --model deepseek-reasoner También podés combinar -t con otras opciones: deep build -t tarea.txt -f --model deepseek-reasoner -o ~/proyectos El archivo puede ser cualquier .txt con la descripción en lenguaje natural. En el REPL: deep ❯ build -t /ruta/mi_tarea.txt deep ❯ build -t tarea.txt -f

Cada build ejecuta 5 fases:

Planificación — diseña la arquitectura usando experiencias previas similares Generación — escribe el código completo Escritura — guarda los archivos en disco Evaluación — revisa si el resultado cumple con la tarea Aprendizaje — guarda la experiencia para informar builds futuros

Si la evaluación falla, deep te pregunta si querés corregirlo (o usá -f para que lo haga sin preguntar).

ask — Conversación con el modelo deep ask "cómo funciona Redis?" Dentro del REPL, ask inicia una conversación. El prompt cambia a chat ❯ y podés seguir preguntando sin repetir el comando: deep ❯ ask qué es Redis? ...respuesta...

chat ❯ es necesario dockerizarlo? ← continúa el hilo automáticamente ...respuesta contextual...

chat ❯ ask qué es Kafka? ← ask resetea e inicia nueva conversación

Cuando la conversación se acerca al límite de contexto del modelo, deep la compacta automáticamente: ⚡ Compactando conversación…

Esto resume los mensajes anteriores para que la conversación pueda continuar indefinidamente sin perder el hilo. Para reiniciar la conversación manualmente: chat ❯ reset

update — Modifica un proyecto existente deep update "agregá autenticación JWT" deep update "agregá tests unitarios" --model deepseek-reasoner Modifica los archivos del proyecto en el directorio actual sin tener que regenerarlo desde cero.

fix — Corrige errores del proyecto actual deep fix Usa el contexto guardado en .deep/ para corregir el proyecto sin necesidad de volver a describir la tarea.

show — Muestra el contexto del proyecto actual deep show Muestra la tarea original, el modelo usado, el plan, los archivos generados y el resultado de la evaluación.

serve — Servidor web para usar deep desde el celular deep serve # HTTP básico deep serve --https # HTTPS + instalable como app deep serve --port 9000 --https # puerto personalizado con HTTPS Levanta una interfaz web accesible desde cualquier dispositivo en la red.

Recomendación: usá Tailscale para conectar el celular Tailscale es la forma más cómoda y segura de acceder a deep serve desde el celular, incluso si estás en redes distintas (datos móviles, otra WiFi, etc.). Por qué Tailscale:

Te asigna una IP fija (100.x.x.x) que no cambia aunque cambies de red Funciona sin abrir puertos en el router La URL es siempre la misma, sin tener que buscar la IP local cada vez Sin Tailscale, el celular y la computadora tienen que estar en la misma WiFi

Setup (una sola vez):

Instalá Tailscale en la compu: tailscale.com/download Instalá Tailscale en el celular (App Store / Play Store) Logueate con la misma cuenta en ambos Listo — la compu aparece en la red Tailscale con una IP 100.x.x.x

Con Tailscale activo, deep serve --https muestra directamente la URL 100.x.x.x para usar desde el celular.

Instalar como app en el celular (PWA) Para que el celular pueda instalar deep como app nativa, la conexión tiene que ser HTTPS. deep serve --https genera el certificado automáticamente.

Requiere trustme: pip install trustme o pip install "deepseek-builder[https]"

Primera vez — instalación del certificado (una sola vez por dispositivo): $ deep serve --https

🔐 HTTPS activado

Paso 1 — Instalá el certificado CA en tu celular (una sola vez): http://100.x.x.x:8001 ← abrí esta URL en el celular

Android : Ajustes → Seguridad → Instalar certificado → CA certificate iOS : Abrir archivo descargado → Ajustes → General → VPN y administración del dispositivo → Instalar → Confiar

Paso 2 — Abrí la app e instalala: https://100.x.x.x:8000 ← abrí esta URL en el celular

Pasos:

Abrí la URL del Paso 1 en el navegador del celular Descargá el archivo .pem y seguí las instrucciones según tu sistema:

Android: Ajustes → Seguridad → Cifrado y credenciales → Instalar un certificado → Certificado de CA iOS: Al abrir el archivo, aparece "Perfil descargado" → Ajustes → General → VPN y administración → Instalar → Confiar en el certificado raíz

Abrí la URL del Paso 2 en el navegador — aparece el botón ⬇ en la cabecera Tap en ⬇ → la app se instala como si fuera nativa

A partir de ese momento no necesitás repetir el proceso. Solo deep serve --https y abrís la app instalada directamente desde el home del celular.

Nota: El certificado autofirmado es local y temporal — es solo para que el navegador acepte HTTPS en tu red privada. No sale a internet.

doctor — Diagnóstico del entorno deep doctor Verifica Python, API key, conexión con DeepSeek, dependencias y configuración del PATH. Funciona correctamente en Linux, macOS y Windows.

upgrade — Actualiza el CLI deep upgrade Descarga e instala la última versión desde GitHub sin necesidad de reinstalar manualmente.

balance / history / config deep balance # muestra el crédito disponible en DeepSeek deep history # muestra las experiencias acumuladas de builds anteriores deep config # muestra la API key guardada deep config set-key # guarda una nueva API key

Debug El flag --debug activa un log detallado de todo lo que hace deep durante una ejecución: prompts enviados, respuestas del modelo, tokens usados, latencias, archivos escritos y cada fase del pipeline. Se guarda en debug.log en el directorio donde corras el comando. Activación --debug va siempre antes del subcomando: deep --debug build "mi tarea" deep --debug build -t tarea.txt deep --debug build -t tarea.txt -f --model deepseek-reasoner deep --debug ask "cómo funciona Redis?" deep --debug update "agregá tests" deep --debug fix También podés activarlo con una variable de entorno (útil para scripts): DEEP_DEBUG=1 deep build -t tarea.txt Debug con archivo de tarea La combinación más común para analizar un build completo: # 1. Escribís la tarea en un .txt (sin límite de largo) cat tarea.txt

# 2. Corrés con debug deep --debug build -t tarea.txt

# 3. Analizás el log mientras corre o al terminar tail -f debug.log # seguir en tiempo real cat debug.log # ver todo al terminar grep '\[API_OK\]' debug.log # solo latencias y tokens grep '\[PHASE\]' debug.log # solo transiciones de fase grep '\[WRITER\]' debug.log # solo archivos escritos grep '\[EVAL\]' debug.log # solo el resultado de evaluación Podés combinar todos los flags normales con --debug: deep --debug build -t tarea.txt -f -o ~/proyectos --model deepseek-reasoner Estructura del log Cada línea

tiene el formato: [HH:MM:SS.mmm + elapsed] [TAG ] mensaje

HH:MM:SS.mmm — hora del evento con milisegundos +elapsed — segundos desde que arrancó la sesión (para medir duración de cada paso) TAG — identificador de la sección (ver tabla abajo)

Los bloques de texto largo (prompts, respuestas) se muestran indentados: [07:32:11.450 + 0.00s] [API_CALL ] model=deepseek-chat temp=0.5 max_tokens=1000 [07:32:11.451 + 0.01s] [API_SYS ] ── system_prompt ────────────────────────────── Eres un arquitecto de software senior. Creas planes claros y accionables. ──────────────────────────────────────────────────────────── [07:32:11.452 + 0.02s] [API_USER ] ── user_prompt ────────────────────────────── Crea un plan detallado para: API REST en FastAPI con JWT y PostgreSQL ... ──────────────────────────────────────────────────────────── [07:32:13.210 + 1.76s] [API_OK ] attempt=1 latency=1.76s tokens_in=320 tokens_out=580 total=900 [07:32:13.211 + 1.77s] [API_RESP ] ── response_content ────────────────────────────── ## Plan 1.

Estructura de carpetas: app/, tests/, ... ... ────────────────────────────────────────────────────────────

Tags del log

Tag Qué registra

INIT Comando completo con el que arrancó deep

PHASE Transición de fase (1 planificación → 5 aprendizaje)

API_CALL Antes de cada llamada: modelo, temperatura, max_tokens

API_SYS System prompt completo enviado al modelo

API_USER User prompt completo enviado al modelo

API_OK Resultado: intento, latencia, tokens in/out/total

API_RESP Respuesta completa del modelo

API_ERR Error en un intento (incluye reintentos automáticos)

PLAN Experiencias similares encontradas antes de planificar

PHASE_1 Plan generado por el modelo

PHASE_2 Tokens usados en la generación de código

PHASE_3 Archivos escritos en disco

PHASE_4 Resultado de la evaluación

PHASE_5 Análisis de experiencia guardado en memoria

PHASE_6 Reflexión profunda (si reflect=True)

EVAL JSON de evaluación parseado (score, issues, positives)

WRITER Directorio del proyecto, bloques detectados, cada archivo

EXEC Tokens usados en la fase de ejecución

FIX Flujo de corrección automática (fix, build -f)

UPDATE Flujo de modificación de proyecto existente

SYSTEM Resumen final del ciclo completo

Queries útiles para analizar el log # Cuántas llamadas a la API y tokens totales grep 'API_OK' debug.log

# Ver solo los archivos que se