CAWRA IDE user manual
Practical guide to install CAWRA IDE, configure AI providers (Grok, OpenAI, Anthropic, Gemini, or Ollama), role routing, and use Chat, Task orchestrator, Repair and all integrated 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-provider AI — Grok, OpenAI, Anthropic, Gemini, and Ollama; automatic role-based routing (plan, code, verify, vision…).
- Executable Chat — Ask, Edit, and Agent modes with real access to files and the terminal.
- Semantic index — intelligent codebase search with
@codebasementions. - 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 to the account of the provider you choose (xAI, OpenAI, Anthropic, Google, etc.) with your own API key. Local models with Ollama have no cloud cost.
2. Installation (Windows)
-
Register and download
Visit the main page, register with your name and email, and download the.exeinstaller from the registration section. -
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. -
Open a project
Use File → Open Folder to open your repository. Many features (@pathreferences, terminal, indexing) require an open workspace. -
Configure your AI provider
On first launch, CAWRA will ask you to configure at least one API key. Follow the next section before using Chat or Task.
3. Getting started: providers and API keys
CAWRA IDE 1.5 supports multiple AI providers. Configure the API keys for the ones you want to use; they are stored securely in the IDE's SecretStorage (not in settings.json).
3.1 Supported providers
| Provider | Featured models | Where to get the key |
|---|---|---|
| xAI / Grok | Grok 4.5, 4.3, 4.20, Grok Build | console.x.ai |
| OpenAI | GPT 5.6 Sol, Terra, Luna | platform.openai.com |
| Anthropic | Fable 5, Sonnet 5, Opus 4.8 | console.anthropic.com |
| Google Gemini | Gemini 3 Pro, 3.5 Pro, 3.5 Flash | aistudio.google.com |
| Ollama (local) | Llama 3.1, Qwen 2.5, Code Llama | Local installation — no cloud key |
3.2 Configuring keys in CAWRA IDE
Open the CAWRA: Providers & models panel or the CAWRA Hub:
| Method | How to access |
|---|---|
| Providers panel | Ctrl+Shift+P → CAWRA: Providers & models |
| CAWRA Hub | Click ⚙ CAWRA in the status bar → Providers & models |
| CAWRA AI menu | Gear icon → CAWRA AI submenu → Providers & models |
Paste each key in its (hidden) field. You will see a confirmation when it is saved correctly.
3.3 Role-based routing and fallback
In the same panel you can choose which model each role uses (planner, executor, chat, vision, inline…) and set a fallback provider in case the primary one fails.
3.4 Verifying the connection
- Open the Chat panel (Chat tab in CAWRA AI).
- Write a simple message: «Hi, is the AI working?»
- If the key is valid, you will get a reply within seconds. If it is missing or incorrect, CAWRA will ask you to configure it.
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: on startup only Task is visible; Chat, Repair, and Audit open on demand.
- 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, providers, 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.
- API keys / Providers — Configure keys and models per provider.
- Providers & models — Full role-routing and fallback panel.
- 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. Providers, models, and routing
CAWRA 1.5 is multi-provider. The ModelRouter assigns the right model to each task based on its role, whichever providers you have configured:
Planning, task analysis, decomposition into subtasks.
Code implementation, file editing, terminal tools.
Conversation, explanations, and questions without tools (Ask mode).
Ghost-text autocomplete in the editor with minimal latency.
Images in Chat, mockups, error screenshots, UI visual verification.
Automatic prompt enhancement before sending (optional in Chat).
Providers & models panel
Open CAWRA: Providers & models from the palette or the Hub to:
- Configure API keys per provider (SecretStorage).
- Assign models to each orchestrator role.
- Set a fallback if the primary provider fails.
- Select the Chat model per conversation.
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
- Open the global CAWRA AI menu (gear icon, bottom-left bar).
- Choose Idioma / Language / 语言 or directly English, Español, or 中文.
-
You can also use the palette:
Ctrl+Shift+P→CAWRA: Idioma / Language / 语言. -
CAWRA saves the preference in the user profile's
locale.jsonand 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
| Mode | What it does | When to use it |
|---|---|---|
| Ask | A single LLM call. Answers questions and may suggest files, but does not run the terminal or use agent tools. | Explanations, conceptual questions, idea review. |
| Edit | AgentLoop with file tools: read_file, write_file, edit_file, list_dir. No terminal. |
Refactors, create/edit files without compiling or installing. |
| Agent | Full AgentLoop: files + run_terminal, git_status, run_tests, etc. |
Compile, install dependencies, run tests, deploy. |
Chat elements
- Mode selector — Ask / Edit / Agent in the header.
- Model selector — Model for Ask conversation (from any configured provider).
- 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 the most suitable model to each phase, and executes in parallel when possible.
Typical flow
- Analysis — Understands the open project, dependencies, and the goal (with images if you attach them).
- Planning — The Planner (e.g. Grok 4.5 or Claude Sonnet 5) generates subtasks with dependencies.
- Execution — One or more Executors (e.g. Grok Build or GPT Sol) implement each subtask with code and terminal tools.
- Verification — QA, optional tests, and visual verification on web projects.
- 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 you have assigned (e.g. Gemini 3 Pro, Grok Vision or GPT Luna). 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 the assigned inline model (e.g. Gemini 3.5 Flash, Grok mini or local Ollama).
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.autoIndexOnOpenis active. - Reindex manually: Hub → Reindex project or
CAWRA: Reindexar proyecto. cawra.indexMaxFileslimits 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 likerm -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 (usuallyrooton 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 (typicallyroot).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/).
- Configure the host in
~/.ssh/configusing one of the formats above. - Open the palette (
Ctrl+Shift+P) and run CAWRA: Abrir ventana remota or CAWRA: Connect to Host.... - Select the alias (
SERVER_NAMEorHOST_NAME). If using a password, enter it when prompted. - Open the project folder on the remote server (File → Open Folder).
20. Keyboard shortcuts
| Shortcut | Action |
|---|---|
| Ctrl+L | Open / focus Task |
| Ctrl+Shift+G | Agent Graph |
| Ctrl+K | Inline editing (with selection) |
| Ctrl+I | Composer / Agent Mode |
| Ctrl+Shift+E | Explain selected code |
| Tab | Accept inline suggestion (ghost text) |
| Escape | Dismiss inline suggestion |
| Alt+\ | Force inline autocomplete |
| Ctrl+Enter | Send message in Chat / Task |
| Ctrl+Shift+P | Command Palette (all CAWRA commands) |
21. Frequently asked questions
Is CAWRA IDE free?
Yes. The IDE and orchestrator are free. You only pay for API usage with the provider you choose, at their rates.
Can I use several providers at once?
Yes. CAWRA 1.5 is multi-provider: configure the API keys you need and the system will automatically route the best model for each role. You can also use Ollama locally with no cloud API cost.
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 are my API keys stored?
In the VS Code/Codium secure secret store (SecretStorage), one key per provider. They are never saved in plain text in settings.json.
Does it work offline?
The editor yes; cloud AI features require a connection (except local Ollama). 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.
Visit the home page to register, download the latest version, or contact support.