Manual de uso de CAWRA IDE

Guía práctica para instalar CAWRA IDE, conectar Grok (xAI), configurar modelos y usar Chat, Encargo, Repair y el resto de herramientas de inteligencia artificial integradas.

1. ¿Qué es CAWRA IDE?

CAWRA IDE es un entorno de desarrollo para Windows basado en VSCodium (fork de Visual Studio Code) con la extensión nativa CAWRA AI preinstalada. A diferencia de un editor con un simple chat lateral, CAWRA incluye:

• Orquestador de Encargos — descompone objetivos complejos en subtareas con planificación DAG, ejecución paralela y verificación automática.
• Multi-modelo Grok — enruta automáticamente cada fase al modelo xAI más adecuado (planificar, codificar, verificar, visión…).
• Chat ejecutable — modos Ask, Edit y Agent con acceso real a archivos y terminal.
• Index semántico — búsqueda inteligente del codebase con menciones @codebase.
• Compatibilidad VS Code — extensiones, temas y flujos habituales de VS Code/Codium.

El IDE es gratuito; solo necesitas registrarte en la web para descargar el instalador. El consumo de IA se factura directamente en tu cuenta de xAI con tu propia API Key.

2. Instalación (Windows)

1. Regístrate y descarga
   Visita la página principal, regístrate con tu email y descarga el instalador .exe desde la sección de registro.
2. Ejecuta el instalador
   Sigue el asistente de instalación. CAWRA IDE se instala como aplicación independiente; no sustituye a VS Code si ya lo tienes.
3. Abre un proyecto
   Usa Archivo → Abrir carpeta para abrir tu repositorio. Muchas funciones (referencias @ruta, terminal, indexación) requieren un workspace abierto.
4. Configura Grok
   Al primer arranque, CAWRA te pedirá configurar la API Key. Sigue la sección siguiente antes de usar Chat o Encargo.

3. Primeros pasos: API Key de Grok (xAI)

CAWRA IDE usa la API de Grok de xAI. Necesitas una clave propia (GROK_API_KEY) para activar Chat, Encargo, autocompletado inline y el resto de funciones IA.

3.1 Obtener la clave en xAI

1. Entra en la consola de desarrolladores de xAI: console.x.ai.
2. Crea una cuenta o inicia sesión con tu cuenta de X/Twitter si ya la tienes vinculada.
3. Ve a la sección API Keys y pulsa Create API Key.
4. Copia la clave generada. Guárdala en un lugar seguro; xAI solo la muestra una vez.
5. (Opcional) Añade créditos o revisa tu plan en la consola de facturación de xAI. CAWRA no cobra por el uso de IA: los tokens se consumen en tu cuenta xAI.

3.2 Configurar la clave en CAWRA IDE

Tienes tres formas equivalentes. La clave se almacena de forma segura en el almacén secreto del IDE (no en texto plano en settings).

Pega la clave en el cuadro de diálogo (campo oculto). Debe tener al menos 8 caracteres. Verás el mensaje: «CAWRA: API Key de Grok configurada correctamente.»

3.3 Verificar la conexión

1. Abre el panel Chat (Ctrl+L abre Encargo; usa el panel lateral CAWRA AI → pestaña Chat).
2. Escribe un mensaje simple: «Hola, ¿funciona Grok?»
3. Si la clave es válida, recibirás respuesta en segundos. Si falta o es incorrecta, CAWRA te pedirá configurarla de nuevo.

4. Interfaz del IDE

CAWRA mantiene el layout familiar de VS Code con estos elementos propios:

• Barra lateral izquierda — Explorador de archivos, Git, extensiones, etc.
• Barra lateral secundaria (derecha) — Panel CAWRA AI con pestañas: Encargo, Chat, Repair y Auditoría.
• Barra de estado — Indicador ✦ CAWRA (idle) o ↻ CAWRA (trabajando). Clic abre el Hub.
• Terminal integrada — Los agentes ejecutan comandos en la terminal CAWRA AI.
• Menú CAWRA AI — Acceso rápido a settings, API Key, modelos e idioma desde el icono de engranaje global.

5. Hub CAWRA AI

El Hub es el centro de control de CAWRA. Ábrelo con un clic en ✦ CAWRA en la barra de estado o con el botón ⚙ CAWRA dentro de Chat/Encargo.

Opciones disponibles:

• CAWRA Settings — Todos los ajustes de la extensión.
• API Key Grok — Configurar o cambiar la clave.
• Modelos Grok — Selector rápido del modelo de Chat.
• Modelos avanzados (por rol) — Planner, Executor, inline, visión, enhancer.
• Grafo de agentes — Visualización en tiempo real del Encargo.
• Encargo / Chat / Auditoría — Saltar a cada panel.
• Reindexar proyecto — Reconstruir el índice semántico.

6. Modelos Grok y enrutamiento

CAWRA no usa un único modelo para todo. El ModelRouter asigna el modelo Grok adecuado según el rol de cada tarea:

Cambiar el modelo de Chat

Dos formas:

• Selector desplegable en la cabecera del panel Chat.
• Hub → Modelos Grok o paleta CAWRA: Modelos Grok.

Modelos disponibles en el selector: grok-4-1-fast-reasoning, grok-4-1-fast-non-reasoning, grok-4-fast-reasoning, grok-4-fast-non-reasoning, grok-code-fast-1, grok-3, grok-3-mini, grok-2-1212, grok-2-latest.

Modelos por rol (Encargo y agentes)

Configúralos en Hub → Modelos avanzados o en Ajustes buscando cawra.models:

• cawra.models.planner — Planificador del Encargo.
• cawra.models.executor — Agente que escribe código y ejecuta herramientas.
• cawra.models.inline — Ghost text del editor.
• cawra.models.vision — Análisis de imágenes adjuntas.
• cawra.models.enhancer — Mejora de prompts.
• cawra.models.maxParallelExecutors — Cuántos executors Build corren en paralelo (1–8, default 3).

7. Ajustes avanzados

Abre Archivo → Preferencias → Configuración y busca CAWRA AI, o usa Hub → CAWRA Settings.

Parámetros LLM

• cawra.temperature — Creatividad (default 0.2).
• cawra.maxTokens — Máximo de tokens por respuesta (256–131072).
• cawra.topP — Muestreo nucleus.

Contexto e indexación

• cawra.contextMaxFiles / cawra.contextMaxChars — Límites de contexto inyectado.
• cawra.codebaseIndex.enabled — Index semántico activo.
• cawra.codebaseIndex.autoIndexOnOpen — Indexar al abrir proyecto.
• cawra.codebaseIndex.topKChunks — Fragmentos recuperados con @codebase.

Calidad del Encargo

• cawra.quality.enforceQaVerdict — Bloquear entrega si QA rechaza.
• cawra.quality.visualVerification — Verificación visual en proyectos web.
• cawra.quality.clarifyDesign — Pausar encargos UI ambiguos para elegir estilo.
• cawra.quality.deepOnlineResearch — Research online con agentes paralelos.
• cawra.testGate.enabled — Ejecutar tests antes de dar por cerrada una subtarea.

Chat e imágenes

• cawra.chat.maxImages — Máximo de imágenes por mensaje (default 4).
• cawra.chat.maxImageSizeMb — Tamaño máximo por imagen (default 5 MB).
• cawra.promptEnhancer.enabled — Mejora global de prompts.

Archivo de proyecto cawra.config.json

Puedes colocar un archivo cawra.config.json en la raíz del workspace o del IDE para valores por defecto de LLM, inline, chat y contexto. Los ajustes del usuario en Configuración tienen prioridad sobre el archivo.

8. Cambio de idioma de la interfaz

CAWRA IDE soporta tres idiomas de interfaz:

• English (predeterminado)
• Español
• 中文 (简体) — Chino simplificado

Cómo cambiar el idioma

1. Abre el menú global CAWRA AI (icono engranaje, barra inferior izquierda).
2. Elige Idioma / Language / 语言 o directamente English, Español o 中文.
3. También puedes usar la paleta: Ctrl+Shift+P → CAWRA: Idioma / Language / 语言.
4. CAWRA guarda la preferencia en locale.json del perfil de usuario y te pedirá Reiniciar ahora para aplicar el cambio. Acepta el reinicio de ventana.

9. Panel Chat

El Chat es tu asistente interactivo en el panel lateral CAWRA AI → Chat. Soporta contexto del proyecto, imágenes, referencias a archivos y —en modos avanzados— ejecución real en terminal.

Modos de trabajo

Elementos del Chat

• Selector de modo — Ask / Edit / Agent en la cabecera.
• Selector de modelo — Modelo Grok para conversación Ask.
• Mejorar prompt — Checkbox que usa el modelo Enhancer antes de enviar.
• Adjuntar imagen — Botón 📎, pegar con Ctrl+V o arrastrar imágenes al área de input.
• Progreso de herramientas — En modos Edit/Agent verás mensajes como «Ejecutando: ./gradlew.bat assembleDebug».
• Limpiar historial — Botón 🗑 en la cabecera.

Envía mensajes con el botón Enviar o Ctrl+Enter.

10. Encargo (Orchestrator)

El Encargo es el diferenciador de CAWRA: describes un objetivo de alto nivel y el orquestador lo descompone, planifica un DAG de subtareas, asigna modelos Grok por fase y ejecuta en paralelo cuando es posible.

Flujo típico

1. Análisis — Entiende el proyecto abierto, dependencias y el objetivo (con imágenes si las adjuntas).
2. Planificación — El Planner (Grok 4 reasoning) genera subtareas con dependencias.
3. Ejecución — Uno o varios Executors (Grok Build) implementan cada subtarea con herramientas de código y terminal.
4. Verificación — QA, tests opcionales y verificación visual en proyectos web.
5. Entrega — Resumen final con archivos modificados y resultado.

Cómo lanzar un Encargo

• Panel CAWRA AI → pestaña Encargo.
• Atajo Ctrl+L (enfoca el orquestador).
• Hub → Encargo (Orchestrator).

Escribe el objetivo en lenguaje natural. Ejemplos:

• «Añade autenticación JWT al backend Express existente»
• «Refactoriza el módulo de pagos y añade tests unitarios»
• «Crea una landing page responsive según el mockup adjunto» (adjunta imagen)

Los encargos se encolan si ya hay uno en curso (cawra.queue.maxConcurrent controla concurrencia). Puedes abrir el Grafo de agentes (Ctrl+Shift+G) para ver el progreso en vivo.

11. Repair

El panel Repair está orientado a corregir errores: compila fallida, tests rotos, excepciones en runtime. CAWRA analiza el contexto del error y propone un plan de reparación automática similar al Encargo pero enfocado en resolver el fallo concreto.

Ábrelo desde CAWRA AI → pestaña Repair o con el comando CAWRA: Abrir Repair.

12. Auditoría

Auditoría registra el historial de acciones de agentes: subtareas, herramientas usadas, tokens consumidos y resultados. Útil para revisar qué hizo el orquestador, exportar logs o depurar encargos complejos.

Acceso: panel CAWRA AI → Auditoría, o Hub → Auditoría.

13. Grafo de agentes

Visualización interactiva del Encargo en curso o completado. Muestra nodos de fases, subtareas, agentes y herramientas conectados en un grafo animado.

• Atajo: Ctrl+Shift+G
• Hub → Grafo de agentes
• Comando: CAWRA: Grafo de agentes

14. Referencias @archivo y contexto

CAWRA inyecta contexto del proyecto automáticamente cuando usas menciones:

• @codebase — Búsqueda semántica en el índice del proyecto.
• @src/app/main.ts — Contenido de un archivo concreto.
• @app/ — Hasta 20 archivos de una carpeta.
• @"mi carpeta/archivo con espacios" — Rutas con espacios entre comillas.

Añadir referencias sin escribir

• Clic derecho en archivo o carpeta del explorador → CAWRA: Referenciar en Chat o Referenciar en Encargo.
• Arrastrar archivos o carpetas al área de input del Chat o Encargo (aparecen chips visuales).
• Menú contextual del editor — Mismas opciones de referencia.

15. Imágenes y visión

Tanto Chat como Encargo aceptan imágenes de referencia:

• Botón 📎 Imagen en el pie del input.
• Pegar capturas con Ctrl+V.
• Arrastrar archivos de imagen al área de input.

Las imágenes se procesan con el modelo Vision (grok-2-vision-1212 por defecto). Útil para mockups de UI, capturas de errores, diagramas o diseños que el planner debe respetar.

Límites configurables: máximo 4 imágenes y 5 MB cada una (por defecto).

16. Autocompletado inline y Composer

Ghost text (inline completion)

Mientras escribes, CAWRA sugiere código en gris (ghost text) usando grok-3-mini.

• Tab — Aceptar sugerencia.
• Escape — Descartar.
• Alt+\ — Forzar autocompletado.

Activa/desactiva con cawra.inlineEnabled. Modo rápido: cawra.inline.fastMode.

Edición inline (Ctrl+K)

Selecciona código en el editor y pulsa Ctrl+K. Escribe la instrucción (ej. «convierte a async/await») y CAWRA reemplaza la selección.

Composer / Agent Mode (Ctrl+I)

Ctrl+I abre el Composer para cambios multi-archivo con planificación de agente, similar al flujo de Cursor Agent.

Acciones en selección (clic derecho)

• Explicar código — Ctrl+Shift+E
• Refactorizar selección
• Generar tests

17. Index semántico del codebase

CAWRA indexa tu proyecto para que @codebase y el orquestador encuentren código relevante sin leer todo el repo.

• Se indexa automáticamente al abrir el proyecto si cawra.codebaseIndex.autoIndexOnOpen está activo.
• Reindexar manualmente: Hub → Reindexar proyecto o CAWRA: Reindexar proyecto.
• cawra.indexMaxFiles limita archivos indexados (default 2000).

18. Terminal y seguridad

En modos Agent del Chat y durante Encargos, CAWRA ejecuta comandos en la terminal integrada CAWRA AI.

Controles de seguridad

• cawra.shell.enabled — Activa/desactiva ejecución shell (default: activo).
• cawra.shellBlockDestructive — Bloquea comandos destructivos como rm -rf (default: activo).
• cawra.agent.requireDiffApproval — Exigir aprobación antes de aplicar diffs grandes.

Comandos habituales como gradlew, npm, git status están en la allowlist del motor de políticas.

19. Trabajo remoto (SSH)

CAWRA incluye soporte Remote SSH (basado en Open Remote SSH):

• CAWRA: Abrir ventana remota (Open Remote Window) — Nueva ventana conectada al host.
• CAWRA: Connect to Host... — Elegir host SSH.
• CAWRA: Configure SSH Hosts... — Editar ~/.ssh/config.

El orquestador y los agentes ejecutan en el servidor remoto como si fuera local. La extensión CAWRA AI se instala automáticamente en el host remoto.

19.1 Servicio ssh-agent en Windows

Si ssh-agent no arranca (requiere permisos de administrador), ejecuta una vez en PowerShell como administrador:

Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent

Tras esto, el agente SSH quedará activo al iniciar Windows y podrá gestionar tus claves privadas para conexiones por clave pública.

19.2 Configurar hosts en ~/.ssh/config

Usa CAWRA: Configure SSH Hosts... o edita manualmente el archivo ~/.ssh/config en tu equipo local. Cada bloque Host define un servidor al que CAWRA puede conectarse con Abrir ventana remota o Connect to Host....

Conexión por clave pública/privada

Formato recomendado cuando el servidor acepta autenticación por clave SSH (sin contraseña en cada conexión):

Host NOMBRE_SERVER
  HostName IP_o_NOMBRE_HOST
  User root
  IdentityFile ~/.ssh/nombre
  IdentitiesOnly yes

• NOMBRE_SERVER — Alias que verás en CAWRA al elegir el host.
• HostName — IP pública o nombre de dominio del servidor.
• User — Usuario SSH (habitualmente root en VPS).
• IdentityFile — Ruta a tu clave privada (ej. ~/.ssh/id_ed25519).
• IdentitiesOnly yes — Usa solo la clave indicada, sin probar otras del agente.

Conexión por usuario y contraseña

Formato para conexión SSH con contraseña (normalmente usuario root). CAWRA te pedirá la contraseña al conectar:

Host NOMBRE_HOST
  HostName IP_o_NOMBRE_HOST
  User root
  LocalForward 8080 /var/www/vhosts/

• NOMBRE_HOST — Alias del servidor en el selector de hosts.
• HostName — IP o nombre de dominio del servidor.
• User root — Usuario con el que autenticarte (suele ser root).
• LocalForward — (Opcional) Redirige un puerto local al servidor remoto; útil para acceder a servicios web del host (ej. sitios en /var/www/vhosts/).

20. Atajos de teclado

21. Preguntas frecuentes

¿CAWRA IDE es gratis?

Sí. El IDE y el orquestador son gratuitos. Pagas solo el uso de la API Grok en tu cuenta xAI según sus tarifas.

¿Puedo usar otra API que no sea Grok?

CAWRA está optimizado para el endpoint OpenAI-compatible de xAI (https://api.x.ai/v1). Cambiar de proveedor requeriría modificar la extensión; no está soportado oficialmente.

El Chat no ejecuta comandos en terminal

Comprueba que estás en modo Agent, o usa verbos de ejecución («compila», «ejecuta»…) para activar el auto-escalado. Verifica también que cawra.shell.enabled esté activo.

¿Dónde se guarda mi API Key?

En el almacén seguro de secretos de VS Code/Codium (SecretStorage), clave interna cawra.grok.apiKey. Alternativamente, la variable de entorno GROK_API_KEY tiene prioridad si no hay clave guardada.

¿Funciona sin conexión?

El editor sí; las funciones IA requieren conexión a la API de xAI. El index semántico y edición local funcionan offline.

¿Es compatible con extensiones de VS Code?

Sí. CAWRA usa Open VSX por defecto (https://open-vsx.org) y es compatible con la mayoría de extensiones de VS Code.