add-config

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

Step 1: Add to Go Struct Definition

Edit pkg/wconfig/settingsconfig.go and add your new field to the SettingsType struct:

type SettingsType struct {
    // ... existing fields ...

    // Add your new field with appropriate JSON tag
    MyNewSetting string `json:"mynew:setting,omitempty"`

    // For different types:
    MyBoolSetting   bool    `json:"mynew:boolsetting,omitempty"`
    MyNumberSetting float64 `json:"mynew:numbersetting,omitempty"`
    MyIntSetting    *int64  `json:"mynew:intsetting,omitempty"`    // Use pointer for optional ints
    MyArraySetting  []string `json:"mynew:arraysetting,omitempty"`
}

Naming Conventions:

• Use namespace prefixes (e.g., term:, window:, ai:, web:, app:)
• Use lowercase with colons as separators
• Field names should be descriptive and follow Go naming conventions
• Use omitempty tag to exclude empty values from JSON

Type Guidelines:

• Use *int64 and *float64 for optional numeric values
• Use *bool for optional boolean values (or bool if default is false)
• Use string for text values
• Use []string for arrays
• Use float64 for numbers that can be decimals