Wave Terminal

Wave Terminal: Configuration & Memory Optimization

Overview

Wave Terminal (~/.config/waveterm/) is an open-source, Electron-based terminal. Its config uses flat namespace:key JSON. Memory optimization focuses on reducing Chromium's footprint: GPU acceleration, tab cache, scrollback buffer, and background processes.

Config File Location

• Main config: ~/.config/waveterm/settings.json
• Themes: ~/.config/waveterm/termthemes/
• Widgets: ~/.config/waveterm/widgets/
• Backgrounds: ~/.config/waveterm/presets/

Memory Optimization Settings

Heavy Hitters (Biggest RAM Impact)

Medium Impact

Low Impact / Quality of Life

AI Configuration

Wave Terminal has a built-in AI panel with configurable modes.

File Structure

• AI modes: ~/.config/waveterm/waveai/*.json — each file is an AI mode (filename = mode ID)
• Default mode: Set via waveai:defaultmode in settings.json
• Visibility: Set app:hideaibutton: false to show AI panel in UI

AI Mode Config Format (AIModeConfigType)

{
  "display:name": "My Mode",
  "display:order": 1,
  "display:description": "What this mode does",
  "display:icon": "sparkles | zap | dollar-sign | brain | globe",
  "ai:provider": "openrouter | openai | google | anthropic | azure | wave | custom",
  "ai:apitype": "openai-chat | openai-responses | google-gemini",
  "ai:model": "model-name-here",
  "ai:thinkinglevel": "low | medium | high",
  "ai:verbosity": "low | medium | high",
  "ai:endpoint": "https://api.example.com/v1",
  "ai:apitoken": "sk-...",
  "ai:capabilities": ["tools", "images", "pdfs"],
  "ai:switchcompat": ["other-mode-id-1", "other-mode-id-2"]
}

Supported Providers

Secret Storage

• Put API key directly in ai:apitoken field, OR
• Use Wave's secret manager: wsh setsecret <name> then reference with ai:apitokensecretname

Switching Modes

• ai:switchcompat lists compatible mode IDs the user can switch to mid-conversation
• Set waveai:defaultmode in settings.json to your preferred default mode ID

Startup Performance Tweaks

Electron Flags (via CLI or desktop entry)

# Disable Chromium sandbox (for container/CI environments)
wave --no-sandbox

# Disable GPU shader disk cache
wave --disable-gpu-shader-disk-cache

# Disable Chromium features that consume memory
wave --disable-features=TranslateUI,ChromeWhatsNewUI

Environment Variables

# Reduce Chromium shared memory
export ELECTRON_EXTRA_LAUNCH_ARGS="--disable-gpu-shader-disk-cache --max_old_space_size=4096"

Durable Sessions (Memory-Safe Config)

Durable sessions persist terminal state across restarts. For memory-constrained setups:

{
  "term:durable": false
}

Set to false to prevent session state accumulation.

Management Commands

# Open config in built-in editor
wsh editconfig

# List all settings
wsh getconfig

# Set a specific value
wsh setconfig "term:fontsize" 14

# Open Wave config directory
wsh opendir

Memory Monitoring

# Check Wave process memory
ps aux | grep wave | grep -v grep

# Check resident memory
ps -eo pid,comm,rss | grep wave

# Detailed Electron memory
cat /proc/$(pgrep -f wave | head -1)/status | grep -E "VmRSS|VmSize"

Reset to Defaults

# Remove user config to reset
rm ~/.config/waveterm/settings.json
# Or selectively reset a key
wsh setconfig "window:disablehardwareacceleration" false

Related: sys-tune (System Tuning Manager)

sys-tune is the companion CLI for system-level tuning, optimization, and memory management.

# Quick integration with Wave
sys-tune status                  # Shows Wave memory alongside system health
sys-tune doctor                  # Diagnoses system (incl. Wave GPU settings)
sys-tune cache flush             # Clears Wave caches + system caches
sys-tune profile apply desktop   # Balanced kernel params for desktop use
sys-tune browser optimize all    # Apply memory flags to all browsers

Key Commands

Profiles

Installation

# sys-tune lives at ~/.local/bin/sys-tune
# Aliases: tune, tune-st, tune-dr, tune-auto, tune-mon, ...
# Bash completion included in ~/.bashrc