Wave Terminal

Essential Knowledge

Config Location

• macOS/Linux: ~/.config/waveterm/
• Widget registration: ~/.config/waveterm/widgets.json

Build Commands

# Using tsunami-build wrapper
./scripts/tsunami-build widgets/my-widget          # Build
./scripts/tsunami-build widgets/my-widget --run    # Build & run

# Using tsunami CLI directly
export TSUNAMI_SCAFFOLDPATH=/path/to/wave-terminal/dist/tsunamiscaffold
export TSUNAMI_SDKREPLACEPATH=/path/to/wave-terminal/tsunami
tsunami build /path/to/widget -o /path/to/widget/widget-name

Launching Widgets

# Launch a registered widget
wsh launch cog-spark              # By widget ID
wsh launch cog-chat -m            # Magnified mode

# Claude can launch widgets directly!
# Just use: wsh launch <widget-id>

Registering New Widgets

Add to ~/.config/waveterm/widgets.json:

{
  "my-widget": {
    "icon": "zap",
    "label": "my-widget",
    "color": "#fbbf24",
    "description": "Widget description",
    "display:order": 0,
    "blockdef": {
      "meta": {
        "view": "tsunami",
        "controller": "tsunami",
        "tsunami:apppath": "/path/to/widget/directory",
        "tsunami:env": {
          "COG_WORKSPACE": "/Users/slowbro/cog-workspace"
        }
      }
    }
  }
}

Icon options: See Lucide Icons - use zap, hexagon, message-square, sparkles, etc.

Three Atom Types

// ConfigAtom - User-configurable (appears in widget settings)
var intervalAtom = app.ConfigAtom("interval", 30, &app.AtomMeta{
    Desc: "Refresh interval", Min: app.Ptr(5.0), Max: app.Ptr(300.0),
})

// DataAtom - Runtime data (persisted, external access)
var dataAtom = app.DataAtom("data", []Item{}, nil)

// UseLocal - Component-scoped (auto-cleanup)
inputAtom := app.UseLocal("")

Key Hooks

app.UseLocal(initial)           // Local state
app.UseRef(initial)             // Mutable ref (no re-render)
app.UseEffect(fn, deps)         // Side effects
app.UseTicker(interval, fn, deps) // Periodic callback
app.UseId()                     // Component UUID

CogOS Widget Development (Whirlpools)

For cog-native widgets that integrate with the workspace substrate:

# Build a widget
./scripts/tsunami-build widgets/cog-eidolon

# Build and run standalone
./scripts/tsunami-build widgets/cog-chat --run

Load references/cog-widgets.md when:

• Creating widgets that read signals, memory, or identity
• Integrating SRC constants (Tau2, GEff, VarianceRatio)
• Building workspace-aware visualizations

Core Concepts (Always Available)

Tsunami Architecture

Go Backend (Tsunami)
├── Component definitions (React-like)
├── Virtual DOM rendering engine
├── State management (atoms + hooks)
└── RPC streaming to frontend
    ↓
Frontend (TypeScript)
├── Renders VDom sent from backend
├── Event handling (clicks, keyboard)
└── Sends events back to backend

Minimal Widget Structure

package main

import (
    "github.com/wavetermdev/waveterm/tsunami/app"
    "github.com/wavetermdev/waveterm/tsunami/vdom"
)

var AppMeta = app.AppMeta{
    Title:     "My Widget",
    ShortDesc: "Widget description",
}

var App = app.DefineComponent("App", func(_ struct{}) any {
    return vdom.H("div", map[string]any{
        "className": "p-4",
    }, "Hello from Tsunami!")
})

Key Files in a Widget

widget-name/
├── app.go          # Main component definitions
├── go.mod          # Go module (tsunami/app/widget-name)
├── go.sum          # Dependencies
├── manifest.json   # Widget metadata for Wave
└── static/         # Optional static assets

When to Load References

Load references/basics.md when:

• Starting a new widget from scratch
• Needing to understand Wave/Tsunami architecture
• Explaining how Tsunami differs from React

Load references/components.md when:

• Defining new components with DefineComponent
• Working with props and component composition
• Understanding the three component patterns (Text, Base, Custom)

Load references/state.md when:

• Adding state to widgets (atoms)
• Using hooks like UseAsync, UseLocal
• Managing shared state across components

Load references/vdom.md when:

• Building UI with vdom.H()
• Handling events (onClick, onChange, onKeyDown)
• Working with conditional rendering or lists

Load references/ai-integration.md when:

• Integrating AI capabilities into widgets
• Working with streaming responses
• Configuring AI providers or presets

Load references/wsh.md when:

• Programmatically managing Wave workspaces
• Running CLI commands from widgets
• Automating widget spawning or layout

Common Patterns

Component with State

var Counter = app.DefineComponent("Counter", func(_ struct{}) any {
    countAtom := app.UseLocal(0)

    return vdom.H("div", nil,
        vdom.H("span", nil, fmt.Sprintf("Count: %d", countAtom.Get())),
        vdom.H("button", map[string]any{
            "onClick": func() { countAtom.Set(countAtom.Get() + 1) },
        }, "Increment"),
    )
})

Async Data Loading

var DataList = app.DefineComponent("DataList", func(_ struct{}) any {
    dataAtom := app.UseAsync(func() []Item {
        // Fetch data (runs in goroutine)
        return fetchItems()
    })

    items := dataAtom.Get()
    if items == nil {
        return vdom.H("div", nil, "Loading...")
    }

    return vdom.H("ul", nil,
        // Map over items...
    )
})

Event Handling

vdom.H("input", map[string]any{
    "type":      "text",
    "value":     inputAtom.Get(),
    "onChange":  func(e vdom.VDomEvent) { inputAtom.Set(e.TargetValue) },
    "onKeyDown": func(e vdom.VDomEvent) {
        if e.KeyData != nil && e.KeyData.Key == "Enter" {
            handleSubmit()
        }
    },
})

Widget Layout (Critical)

Wave's block-content container has position: relative, which enables a key layout pattern:

Filling the Widget Pane

Problem: h-full doesn't work because Wave uses min-h-full on the VDom container.

Solution: Use absolute inset-0 to fill the positioned ancestor:

var App = app.DefineComponent("App", func(_ struct{}) any {
    return vdom.H("div", map[string]any{
        // absolute inset-0 fills the block-content container
        "className": "absolute inset-0 flex flex-col overflow-hidden bg-gray-950",
    },
        // Widget content...
    )
})

Pinned Header/Footer with Scrolling Middle

For chat-style UIs with fixed header and input at bottom:

return vdom.H("div", map[string]any{
    "className": "absolute inset-0 flex flex-col overflow-hidden",
},
    // Header - pinned to top
    vdom.H("div", map[string]any{
        "className": "flex-shrink-0 p-2 border-b border-gray-800",
    }, "Header"),

    // Middle - scrollable content area
    vdom.H("div", map[string]any{
        "className": "flex-1 min-h-0 overflow-y-auto p-4",
    },
        // Scrollable content here
    ),

    // Footer - pinned to bottom
    vdom.H("div", map[string]any{
        "className": "flex-shrink-0 p-2 border-t border-gray-800",
    }, "Footer/Input"),
)

Key CSS classes:

• absolute inset-0 - Fill the positioned parent (block-content)
• flex-shrink-0 - Prevent header/footer from shrinking
• flex-1 min-h-0 - Allow middle to fill remaining space and enable scrolling
• overflow-y-auto - Enable vertical scrolling in middle section
• overflow-hidden - Prevent content overflow on root

Built-in Markdown Rendering

Wave provides a built-in markdown component:

vdom.H("wave:markdown", map[string]any{
    "text":       "# Hello **World**\n\nThis is markdown.",
    "className":  "prose prose-invert",
    "scrollable": false,  // true for scrollable markdown blocks
})

Uses react-markdown on the frontend. No external Go libraries needed.

Troubleshooting

Widget Development Workflow

1. Create widget directory in appropriate location
2. Initialize go.mod with tsunami/app/widget-name module path
3. Create app.go with AppMeta and App component
4. Create manifest.json with widget metadata
5. Build and test with Wave Terminal
6. Iterate on components and state management