Skip to content

Commit f0a00e7

Browse files
sawkasawka
committed
update to modes documentation, add settings for setting default and hiding wave cloud
1 parent a99b4b0 commit f0a00e7

1 file changed

Lines changed: 113 additions & 67 deletions

File tree

‎docs/docs/waveai-modes.mdx‎

Lines changed: 113 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ AI modes are configured in `~/.config/waveterm/waveai.json`.
1515
2. Select "Settings" from the menu
1616
3. Choose "Wave AI Modes" from the settings sidebar
1717

18-
**Or edit from the command line:**
18+
**Or launch from the command line:**
1919
```bash
2020
wsh editconfig waveai.json
2121
```
@@ -43,83 +43,51 @@ Wave AI supports the following API types:
4343
- **`openai-responses`**: Uses the `/v1/responses` endpoint (modern API for GPT-5+ models)
4444
- **`google-gemini`**: Google's Gemini API format (automatically set when using `ai:provider: "google"`, not typically used directly)
4545

46-
## Configuration Structure
46+
## Global Wave AI Settings
4747

48-
### Minimal Configuration (with Provider)
48+
You can configure global Wave AI behavior in your Wave Terminal settings (separate from the mode configurations in `waveai.json`).
4949

50-
```json
51-
{
52-
"mode-key": {
53-
"display:name": "Qwen (OpenRouter)",
54-
"ai:provider": "openrouter",
55-
"ai:model": "qwen/qwen-2.5-coder-32b-instruct"
56-
}
57-
}
58-
```
50+
### Setting a Default AI Mode
5951

60-
### Full Configuration (all fields)
52+
After configuring a local model or custom mode, you can make it the default by setting `waveai:defaultmode` in your Wave Terminal settings.
6153

62-
```json
63-
{
64-
"mode-key": {
65-
"display:name": "Display Name",
66-
"display:order": 1,
67-
"display:icon": "icon-name",
68-
"display:description": "Full description",
69-
"ai:provider": "custom",
70-
"ai:apitype": "openai-chat",
71-
"ai:model": "model-name",
72-
"ai:thinkinglevel": "medium",
73-
"ai:endpoint": "http://localhost:11434/v1/chat/completions",
74-
"ai:azureapiversion": "v1",
75-
"ai:apitoken": "your-token",
76-
"ai:apitokensecretname": "PROVIDER_KEY",
77-
"ai:azureresourcename": "your-resource",
78-
"ai:azuredeployment": "your-deployment",
79-
"ai:capabilities": ["tools", "images", "pdfs"]
80-
}
81-
}
82-
```
54+
:::important
55+
Use the **mode key** (the key in your `waveai.json` configuration), not the display name. For example, use `"ollama-llama"` (the key), not `"Ollama - Llama 3.3"` (the display name).
56+
:::
8357

84-
### Field Reference
58+
**Using the settings command:**
59+
```bash
60+
wsh setconfig waveai:defaultmode="ollama-llama"
61+
```
8562

86-
| Field | Required | Description |
87-
|-------|----------|-------------|
88-
| `display:name` | Yes | Name shown in the AI mode selector |
89-
| `display:order` | No | Sort order in the selector (lower numbers first) |
90-
| `display:icon` | No | Icon identifier for the mode |
91-
| `display:description` | No | Full description of the mode |
92-
| `ai:provider` | No | Provider preset: `openai`, `openrouter`, `google`, `azure`, `azure-legacy`, `custom` |
93-
| `ai:apitype` | No | API type: `openai-chat`, `openai-responses`, or `google-gemini` (defaults to `openai-chat` if not specified) |
94-
| `ai:model` | No | Model identifier (required for most providers) |
95-
| `ai:thinkinglevel` | No | Thinking level: `low`, `medium`, or `high` |
96-
| `ai:endpoint` | No | *Full* API endpoint URL (auto-set by provider when available) |
97-
| `ai:azureapiversion` | No | Azure API version (for `azure-legacy` provider, defaults to `2025-04-01-preview`) |
98-
| `ai:apitoken` | No | API key/token (not recommended - use secrets instead) |
99-
| `ai:apitokensecretname` | No | Name of secret containing API token (auto-set by provider) |
100-
| `ai:azureresourcename` | No | Azure resource name (for Azure providers) |
101-
| `ai:azuredeployment` | No | Azure deployment name (for `azure-legacy` provider) |
102-
| `ai:capabilities` | No | Array of supported capabilities: `"tools"`, `"images"`, `"pdfs"` |
103-
| `waveai:cloud` | No | Internal - for Wave Cloud AI configuration only |
104-
| `waveai:premium` | No | Internal - for Wave Cloud AI configuration only |
63+
**Or edit settings.json directly:**
64+
1. Click the settings (gear) icon in the widget bar
65+
2. Select "Settings" from the menu
66+
3. Add the `waveai:defaultmode` key to your settings.json:
67+
```json
68+
"waveai:defaultmode": "ollama-llama"
69+
```
10570

106-
### AI Capabilities
71+
This will make the specified mode the default selection when opening Wave AI features.
10772

108-
The `ai:capabilities` field specifies what features the AI mode supports:
73+
### Hiding Wave Cloud Modes
10974

110-
- **`tools`** - Enables AI tool usage for file reading/writing, shell integration, and widget interaction
111-
- **`images`** - Allows image attachments in chat (model can view uploaded images)
112-
- **`pdfs`** - Allows PDF file attachments in chat (model can read PDF content)
75+
If you prefer to use only your local or custom models and want to hide Wave's cloud AI modes from the mode dropdown, set `waveai:showcloudmodes` to `false`:
11376

114-
**Provider-specific behavior:**
115-
- **OpenAI and Google providers**: Capabilities are automatically configured based on the model. You don't need to specify them.
116-
- **OpenRouter, Azure, Azure-Legacy, and Custom providers**: You must manually specify capabilities based on your model's features.
77+
**Using the settings command:**
78+
```bash
79+
wsh setconfig waveai:showcloudmodes=false
80+
```
11781

118-
:::warning
119-
If you don't include `"tools"` in the `ai:capabilities` array, the AI model will not be able to interact with your Wave terminal widgets, read/write files, or execute commands. Most AI modes should include `"tools"` for the best Wave experience.
120-
:::
82+
**Or edit settings.json directly:**
83+
1. Click the settings (gear) icon in the widget bar
84+
2. Select "Settings" from the menu
85+
3. Add the `waveai:showcloudmodes` key to your settings.json:
86+
```json
87+
"waveai:showcloudmodes": false
88+
```
12189

122-
Most models support `tools` and can benefit from it. Vision-capable models should include `images`. Not all models support PDFs, so only include `pdfs` if your model can process them.
90+
This will hide Wave's built-in cloud AI modes, showing only your custom configured modes.
12391

12492
## Local Model Examples
12593

@@ -132,7 +100,7 @@ Most models support `tools` and can benefit from it. Vision-capable models shoul
132100
"ollama-llama": {
133101
"display:name": "Ollama - Llama 3.3",
134102
"display:order": 1,
135-
"display:icon": "llama",
103+
"display:icon": "microchip",
136104
"display:description": "Local Llama 3.3 70B model via Ollama",
137105
"ai:apitype": "openai-chat",
138106
"ai:model": "llama3.3:70b",
@@ -420,3 +388,81 @@ If you get "model not found" errors:
420388
- Use `openai-chat` for Ollama, LM Studio, custom endpoints, and most cloud providers
421389
- Use `openai-responses` for newer OpenAI models (GPT-5+) or when your provider specifically requires it
422390
- Provider presets automatically set the correct API type when needed
391+
392+
## Configuration Reference
393+
394+
### Minimal Configuration (with Provider)
395+
396+
```json
397+
{
398+
"mode-key": {
399+
"display:name": "Qwen (OpenRouter)",
400+
"ai:provider": "openrouter",
401+
"ai:model": "qwen/qwen-2.5-coder-32b-instruct"
402+
}
403+
}
404+
```
405+
406+
### Full Configuration (all fields)
407+
408+
```json
409+
{
410+
"mode-key": {
411+
"display:name": "Display Name",
412+
"display:order": 1,
413+
"display:icon": "icon-name",
414+
"display:description": "Full description",
415+
"ai:provider": "custom",
416+
"ai:apitype": "openai-chat",
417+
"ai:model": "model-name",
418+
"ai:thinkinglevel": "medium",
419+
"ai:endpoint": "http://localhost:11434/v1/chat/completions",
420+
"ai:azureapiversion": "v1",
421+
"ai:apitoken": "your-token",
422+
"ai:apitokensecretname": "PROVIDER_KEY",
423+
"ai:azureresourcename": "your-resource",
424+
"ai:azuredeployment": "your-deployment",
425+
"ai:capabilities": ["tools", "images", "pdfs"]
426+
}
427+
}
428+
```
429+
430+
### Field Reference
431+
432+
| Field | Required | Description |
433+
|-------|----------|-------------|
434+
| `display:name` | Yes | Name shown in the AI mode selector |
435+
| `display:order` | No | Sort order in the selector (lower numbers first) |
436+
| `display:icon` | No | Icon identifier for the mode (can use any [FontAwesome icon](https://fontawesome.com/search), use the name without the "fa-" prefix). Default is "sparkles" |
437+
| `display:description` | No | Full description of the mode |
438+
| `ai:provider` | No | Provider preset: `openai`, `openrouter`, `google`, `azure`, `azure-legacy`, `custom` |
439+
| `ai:apitype` | No | API type: `openai-chat`, `openai-responses`, or `google-gemini` (defaults to `openai-chat` if not specified) |
440+
| `ai:model` | No | Model identifier (required for most providers) |
441+
| `ai:thinkinglevel` | No | Thinking level: `low`, `medium`, or `high` |
442+
| `ai:endpoint` | No | *Full* API endpoint URL (auto-set by provider when available) |
443+
| `ai:azureapiversion` | No | Azure API version (for `azure-legacy` provider, defaults to `2025-04-01-preview`) |
444+
| `ai:apitoken` | No | API key/token (not recommended - use secrets instead) |
445+
| `ai:apitokensecretname` | No | Name of secret containing API token (auto-set by provider) |
446+
| `ai:azureresourcename` | No | Azure resource name (for Azure providers) |
447+
| `ai:azuredeployment` | No | Azure deployment name (for `azure-legacy` provider) |
448+
| `ai:capabilities` | No | Array of supported capabilities: `"tools"`, `"images"`, `"pdfs"` |
449+
| `waveai:cloud` | No | Internal - for Wave Cloud AI configuration only |
450+
| `waveai:premium` | No | Internal - for Wave Cloud AI configuration only |
451+
452+
### AI Capabilities
453+
454+
The `ai:capabilities` field specifies what features the AI mode supports:
455+
456+
- **`tools`** - Enables AI tool usage for file reading/writing, shell integration, and widget interaction
457+
- **`images`** - Allows image attachments in chat (model can view uploaded images)
458+
- **`pdfs`** - Allows PDF file attachments in chat (model can read PDF content)
459+
460+
**Provider-specific behavior:**
461+
- **OpenAI and Google providers**: Capabilities are automatically configured based on the model. You don't need to specify them.
462+
- **OpenRouter, Azure, Azure-Legacy, and Custom providers**: You must manually specify capabilities based on your model's features.
463+
464+
:::warning
465+
If you don't include `"tools"` in the `ai:capabilities` array, the AI model will not be able to interact with your Wave terminal widgets, read/write files, or execute commands. Most AI modes should include `"tools"` for the best Wave experience.
466+
:::
467+
468+
Most models support `tools` and can benefit from it. Vision-capable models should include `images`. Not all models support PDFs, so only include `pdfs` if your model can process them.

0 commit comments

Comments
 (0)