CAWRA IDE user manual

Practical guide to install CAWRA IDE, connect Grok (xAI), configure models, and use Chat, Task orchestrator, Repair and all integrated AI tools.

1. What is CAWRA IDE?

CAWRA IDE is a Windows development environment based on VSCodium (a fork of Visual Studio Code) with the native CAWRA AI extension preinstalled. Unlike an editor with a simple side chat, CAWRA includes:

• Task Orchestrator — breaks down complex goals into subtasks with DAG planning, parallel execution, and automatic verification.
• Multi-model Grok — automatically routes each phase to the most suitable xAI model (planning, coding, verification, vision…).
• Executable Chat — Ask, Edit, and Agent modes with real access to files and the terminal.
• Semantic index — intelligent codebase search with @codebase mentions.
• VS Code compatibility — extensions, themes, and familiar VS Code/Codium workflows.

The IDE is free; you only need to register on the website to download the installer. AI usage is billed directly to your xAI account with your own API Key.

2. Installation (Windows)

1. Register and download
   Visit the main page, register with your email, and download the .exe installer from the registration section.
2. Run the installer
   Follow the installation wizard. CAWRA IDE installs as a standalone application; it does not replace VS Code if you already have it.
3. Open a project
   Use File → Open Folder to open your repository. Many features (@path references, terminal, indexing) require an open workspace.
4. Configure Grok
   On first launch, CAWRA will prompt you to configure the API Key. Follow the next section before using Chat or Task.

3. Getting started: Grok API Key (xAI)

CAWRA IDE uses the Grok API from xAI. You need your own key (GROK_API_KEY) to enable Chat, Task, inline autocomplete, and the rest of the AI features.

3.1 Obtaining the key from xAI

1. Go to the xAI developer console: console.x.ai.
2. Create an account or sign in with your X/Twitter account if you already have one linked.
3. Go to the API Keys section and click Create API Key.
4. Copy the generated key. Store it in a safe place; xAI only shows it once.
5. (Optional) Add credits or review your plan in the xAI billing console. CAWRA does not charge for AI usage: tokens are consumed on your xAI account.

3.2 Configuring the key in CAWRA IDE

You have three equivalent methods. The key is stored securely in the IDE's secret store (not in plain text in settings).

Paste the key in the dialog (hidden field). It must be at least 8 characters. You will see the message: «CAWRA: Grok API Key configured successfully.»

3.3 Verifying the connection

1. Open the Chat panel (Ctrl+L opens Task; use the CAWRA AI side panel → Chat tab).
2. Write a simple message: «Hello, is Grok working?»
3. If the key is valid, you will receive a response within seconds. If it is missing or incorrect, CAWRA will prompt you to configure it again.

4. IDE interface

CAWRA keeps the familiar VS Code layout with these proprietary elements:

• Left sidebar — File explorer, Git, extensions, etc.
• Secondary sidebar (right) — CAWRA AI panel with tabs: Task, Chat, Repair, and Audit.
• Status bar — Indicator ✦ CAWRA (idle) or ↻ CAWRA (working). Click to open the Hub.
• Integrated terminal — Agents run commands in the CAWRA AI terminal.
• CAWRA AI menu — Quick access to settings, API Key, models, and language from the global gear icon.

5. CAWRA AI Hub

The Hub is CAWRA's control center. Open it with a click on ✦ CAWRA in the status bar or with the ⚙ CAWRA button inside Chat/Task.

Available options:

• CAWRA Settings — All extension settings.
• Grok API Key — Configure or change the key.
• Grok Models — Quick selector for the Chat model.
• Advanced models (by role) — Planner, Executor, inline, vision, enhancer.
• Agent Graph — Real-time visualization of the Task.
• Task / Chat / Audit — Jump to each panel.
• Reindex project — Rebuild the semantic index.

6. Grok models and routing

CAWRA does not use a single model for everything. The ModelRouter assigns the appropriate Grok model based on the role of each task:

Changing the Chat model

Two ways:

• Dropdown selector in the Chat panel header.
• Hub → Grok Models or palette CAWRA: Modelos Grok.

Models available in the 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.

Models by role (Task and agents)

Configure them in Hub → Advanced models or in Settings by searching for cawra.models:

• cawra.models.planner — Task planner.
• cawra.models.executor — Agent that writes code and runs tools.
• cawra.models.inline — Editor ghost text.
• cawra.models.vision — Attached image analysis.
• cawra.models.enhancer — Prompt enhancement.
• cawra.models.maxParallelExecutors — How many Build executors run in parallel (1–8, default 3).

7. Advanced settings

Open File → Preferences → Settings and search for CAWRA AI, or use Hub → CAWRA Settings.

LLM parameters

• cawra.temperature — Creativity (default 0.2).
• cawra.maxTokens — Maximum tokens per response (256–131072).
• cawra.topP — Nucleus sampling.

Context and indexing

• cawra.contextMaxFiles / cawra.contextMaxChars — Injected context limits.
• cawra.codebaseIndex.enabled — Semantic index active.
• cawra.codebaseIndex.autoIndexOnOpen — Index when opening a project.
• cawra.codebaseIndex.topKChunks — Chunks retrieved with @codebase.

Task quality

• cawra.quality.enforceQaVerdict — Block delivery if QA rejects.
• cawra.quality.visualVerification — Visual verification on web projects.
• cawra.quality.clarifyDesign — Pause ambiguous UI tasks to choose a style.
• cawra.quality.deepOnlineResearch — Online research with parallel agents.
• cawra.testGate.enabled — Run tests before closing a subtask.

Chat and images

• cawra.chat.maxImages — Maximum images per message (default 4).
• cawra.chat.maxImageSizeMb — Maximum size per image (default 5 MB).
• cawra.promptEnhancer.enabled — Global prompt enhancement.

Project file cawra.config.json

You can place a cawra.config.json file in the workspace or IDE root for default LLM, inline, chat, and context values. User settings in Configuration take priority over the file.

8. Changing the interface language

CAWRA IDE supports three interface languages:

• English (default)
• Español
• 中文 (简体) — Simplified Chinese

How to change the language

1. Open the global CAWRA AI menu (gear icon, bottom-left bar).
2. Choose Idioma / Language / 语言 or directly English, Español, or 中文.
3. You can also use the palette: Ctrl+Shift+P → CAWRA: Idioma / Language / 语言.
4. CAWRA saves the preference in the user profile's locale.json and will prompt you to Restart now to apply the change. Accept the window restart.

9. Chat panel

Chat is your interactive assistant in the CAWRA AI side panel → Chat. It supports project context, images, file references, and — in advanced modes — real execution in the terminal.

Working modes

Chat elements

• Mode selector — Ask / Edit / Agent in the header.
• Model selector — Grok model for Ask conversation.
• Enhance prompt — Checkbox that uses the Enhancer model before sending.
• Attach image — 📎 button, paste with Ctrl+V, or drag images into the input area.
• Tool progress — In Edit/Agent modes you will see messages like «Running: ./gradlew.bat assembleDebug».
• Clear history — 🗑 button in the header.

Send messages with the Send button or Ctrl+Enter.

10. Task (Orchestrator)

Task is CAWRA's differentiator: you describe a high-level goal and the orchestrator breaks it down, plans a DAG of subtasks, assigns Grok models by phase, and executes in parallel when possible.

Typical flow

1. Analysis — Understands the open project, dependencies, and the goal (with images if you attach them).
2. Planning — The Planner (Grok 4 reasoning) generates subtasks with dependencies.
3. Execution — One or more Executors (Grok Build) implement each subtask with code and terminal tools.
4. Verification — QA, optional tests, and visual verification on web projects.
5. Delivery — Final summary with modified files and outcome.

How to launch a Task

• CAWRA AI panel → Task tab.
• Shortcut Ctrl+L (focuses the orchestrator).
• Hub → Task (Orchestrator).

Write the goal in natural language. Examples:

• «Add JWT authentication to the existing Express backend»
• «Refactor the payments module and add unit tests»
• «Create a responsive landing page based on the attached mockup» (attach image)

Tasks are queued if one is already running (cawra.queue.maxConcurrent controls concurrency). You can open the Agent Graph (Ctrl+Shift+G) to see live progress.

11. Repair

The Repair panel is focused on fixing errors: failed builds, broken tests, runtime exceptions. CAWRA analyzes the error context and proposes an automatic repair plan similar to Task but focused on resolving the specific failure.

Open it from CAWRA AI → Repair tab or with the command CAWRA: Abrir Repair.

12. Audit

Audit records the history of agent actions: subtasks, tools used, tokens consumed, and results. Useful for reviewing what the orchestrator did, exporting logs, or debugging complex tasks.

Access: CAWRA AI panel → Audit, or Hub → Audit.

13. Agent Graph

Interactive visualization of the current or completed Task. Shows phase nodes, subtasks, agents, and tools connected in an animated graph.

• Shortcut: Ctrl+Shift+G
• Hub → Agent Graph
• Command: CAWRA: Grafo de agentes

14. @file references and context

CAWRA injects project context automatically when you use mentions:

• @codebase — Semantic search in the project index.
• @src/app/main.ts — Content of a specific file.
• @app/ — Up to 20 files from a folder.
• @"my folder/file with spaces" — Paths with spaces in quotes.

Adding references without typing

• Right-click on a file or folder in the explorer → CAWRA: Referenciar en Chat or Referenciar en Encargo.
• Drag files or folders into the Chat or Task input area (visual chips appear).
• Editor context menu — Same reference options.

15. Images and vision

Both Chat and Task accept reference images:

• 📎 Image button at the bottom of the input.
• Paste screenshots with Ctrl+V.
• Drag image files into the input area.

Images are processed with the Vision model (grok-2-vision-1212 by default). Useful for UI mockups, error screenshots, diagrams, or designs the planner must follow.

Configurable limits: maximum 4 images and 5 MB each (by default).

16. Inline autocomplete and Composer

Ghost text (inline completion)

As you type, CAWRA suggests code in gray (ghost text) using grok-3-mini.

• Tab — Accept suggestion.
• Escape — Dismiss.
• Alt+\ — Force autocomplete.

Enable/disable with cawra.inlineEnabled. Fast mode: cawra.inline.fastMode.

Inline editing (Ctrl+K)

Select code in the editor and press Ctrl+K. Write the instruction (e.g. «convert to async/await») and CAWRA replaces the selection.

Composer / Agent Mode (Ctrl+I)

Ctrl+I opens the Composer for multi-file changes with agent planning, similar to the Cursor Agent flow.

Selection actions (right-click)

• Explain code — Ctrl+Shift+E
• Refactor selection
• Generate tests

17. Codebase semantic index

CAWRA indexes your project so @codebase and the orchestrator can find relevant code without reading the entire repo.

• It indexes automatically when opening the project if cawra.codebaseIndex.autoIndexOnOpen is active.
• Reindex manually: Hub → Reindex project or CAWRA: Reindexar proyecto.
• cawra.indexMaxFiles limits indexed files (default 2000).

18. Terminal and security

In Agent modes of Chat and during Tasks, CAWRA runs commands in the integrated CAWRA AI terminal.

Security controls

• cawra.shell.enabled — Enable/disable shell execution (default: active).
• cawra.shellBlockDestructive — Block destructive commands like rm -rf (default: active).
• cawra.agent.requireDiffApproval — Require approval before applying large diffs.

Common commands like gradlew, npm, git status are on the policy engine allowlist.

19. Remote work (SSH)

CAWRA includes Remote SSH support (based on Open Remote SSH):

• CAWRA: Abrir ventana remota (Open Remote Window) — New window connected to the host.
• CAWRA: Connect to Host... — Choose SSH host.
• CAWRA: Configure SSH Hosts... — Edit ~/.ssh/config.

The orchestrator and agents run on the remote server as if it were local. The CAWRA AI extension is installed automatically on the remote host.

19.1 ssh-agent service on Windows

If ssh-agent does not start (requires admin permissions), run the following once in PowerShell as administrator:

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

After this, the SSH agent will start with Windows and can manage your private keys for public-key connections.

19.2 Configuring hosts in ~/.ssh/config

Use CAWRA: Configure SSH Hosts... or manually edit ~/.ssh/config on your local machine. Each Host block defines a server CAWRA can connect to via Open Remote Window or Connect to Host....

Public/private key connection

Recommended format when the server accepts SSH key authentication (no password on every connection):

Host SERVER_NAME
  HostName IP_OR_HOSTNAME
  User root
  IdentityFile ~/.ssh/name
  IdentitiesOnly yes

• SERVER_NAME — Alias shown in CAWRA when choosing the host.
• HostName — Public IP or domain name of the server.
• User — SSH user (usually root on VPS).
• IdentityFile — Path to your private key (e.g. ~/.ssh/id_ed25519).
• IdentitiesOnly yes — Use only the specified key, without trying others from the agent.

Username and password connection

Format for SSH password authentication (usually root user). CAWRA will prompt for the password when connecting:

Host HOST_NAME
  HostName IP_OR_HOSTNAME
  User root
  LocalForward 8080 /var/www/vhosts/

• HOST_NAME — Server alias in the host picker.
• HostName — Server IP or hostname.
• User root — User to authenticate with (typically root).
• LocalForward — (Optional) Forwards a local port to the remote server; useful for accessing web services on the host (e.g. sites under /var/www/vhosts/).

20. Keyboard shortcuts

21. Frequently asked questions

Is CAWRA IDE free?

Yes. The IDE and orchestrator are free. You only pay for Grok API usage on your xAI account according to their rates.

Can I use an API other than Grok?

CAWRA is optimized for xAI's OpenAI-compatible endpoint (https://api.x.ai/v1). Switching providers would require modifying the extension; it is not officially supported.

Chat does not run terminal commands

Check that you are in Agent mode, or use execution verbs («build», «run»…) to trigger auto-escalation. Also verify that cawra.shell.enabled is active.

Where is my API Key stored?

In the VS Code/Codium secure secret store (SecretStorage), internal key cawra.grok.apiKey. Alternatively, the GROK_API_KEY environment variable takes priority if no key is saved.

Does it work offline?

The editor yes; AI features require a connection to the xAI API. The semantic index and local editing work offline.

Is it compatible with VS Code extensions?

Yes. CAWRA uses Open VSX by default (https://open-vsx.org) and is compatible with most VS Code extensions.