Adding a New Configuration Setting to Wave Terminal

This guide explains how to add a new configuration setting to Wave Terminal's hierarchical configuration system.

Configuration System Overview

Wave Terminal uses a hierarchical configuration system with:

1. Go Struct Definitions - Type-safe configuration structure in pkg/wconfig/settingsconfig.go
2. JSON Schema - Auto-generated validation schema in schema/settings.json
3. Default Values - Built-in defaults in pkg/wconfig/defaultconfig/settings.json
4. User Configuration - User overrides in ~/.config/waveterm/settings.json
5. Block Metadata - Block-level overrides in pkg/waveobj/wtypemeta.go
6. Documentation - User-facing docs in docs/docs/config.mdx

Settings cascade from defaults → user settings → connection config → block overrides.

Step-by-Step Guide