Manual de uso de CAWRA IDE

Guía práctica para instalar CAWRA IDE, configurar proveedores de IA (Grok, OpenAI, Anthropic, Gemini u Ollama), enrutamiento por rol y usar Chat, Encargo, Repair y el resto de herramientas 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.
• IA multiproveedor — Grok, OpenAI, Anthropic, Gemini y Ollama; enrutamiento automático por rol (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 en la cuenta del proveedor que elijas (xAI, OpenAI, Anthropic, Google, etc.) 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 tu proveedor de IA
   Al primer arranque, CAWRA te pedirá configurar al menos una API key. Sigue la sección siguiente antes de usar Chat o Encargo.

3. Primeros pasos: proveedores y API keys

CAWRA IDE 1.5 soporta múltiples proveedores de IA. Configura las API keys de los que quieras usar; se almacenan de forma segura en SecretStorage del IDE (no en settings.json).

3.1 Proveedores soportados

3.2 Configurar claves en CAWRA IDE

Accede al panel CAWRA: Proveedores y modelos o al Hub CAWRA:

Pega cada clave en el campo correspondiente (oculto). Verás confirmación al guardar correctamente.

3.3 Enrutamiento por rol y fallback

En el mismo panel puedes asignar qué modelo usa cada rol (planner, executor, chat, vision, inline…) y configurar un proveedor de fallback si el principal falla.

3.4 Verificar la conexión

1. Abre el panel Chat (pestaña Chat en CAWRA AI).
2. Escribe un mensaje simple: «Hola, ¿funciona la IA?»
3. Si la clave es válida, recibirás respuesta en segundos. Si falta o es incorrecta, CAWRA te pedirá configurarla.

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: al arrancar solo Encargo visible; Chat, Repair y Auditoría se abren bajo demanda.
• 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 keys / Proveedores — Configurar claves y modelos por proveedor.
• Proveedores y modelos — Panel completo de routing por rol y fallback.
• 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. Proveedores, modelos y enrutamiento

CAWRA 1.5 es multiproveedor. El ModelRouter asigna el modelo adecuado según el rol de cada tarea, independientemente del proveedor configurado:

Panel Proveedores y modelos

Abre CAWRA: Proveedores y modelos desde la paleta o el Hub para:

• Configurar API keys por proveedor (SecretStorage).
• Asignar modelos a cada rol del orquestador.
• Definir fallback si falla el proveedor principal.
• Seleccionar el modelo de Chat por conversación.

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 del proveedor que elijas según sus tarifas.

¿Puedo usar varios proveedores a la vez?

Sí. CAWRA 1.5 es multiproveedor: configura las API keys que necesites y el sistema enrutará automáticamente el mejor modelo por rol. También puedes usar Ollama en local sin coste de API en la nube.

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 guardan mis API keys?

En el almacén seguro de secretos de VS Code/Codium (SecretStorage), una clave por proveedor. No se guardan en settings.json en texto plano.

¿Funciona sin conexión?

El editor sí; las funciones IA en la nube requieren conexión (salvo Ollama local). 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.