Wave Terminal

The wsh command is Wave Terminal's core CLI. It enables interaction between terminal commands and Wave's graphical elements (blocks). Key capabilities include:

• Controlling graphical widgets from the CLI.
• Sharing data between terminal sessions and GUI components.
• Managing workspaces programmatically.
• Connecting local and remote environments.
• Sending CLI output and files directly to AI conversations.
• Running commands in isolated blocks.

The Tsunami AI Builder uses a split-screen interface to facilitate iterative app development via AI chat:

Left Panel

• Chat: The primary interface for communicating with the AI to describe desired changes.

Right Panel

Top Section (Tabs):

• Preview (Default): A live, auto-updating view of the running Tsunami application.
• Code: A Monaco editor for manual editing of the app.go file.
• Files: A browser for managing static assets (images, etc.).

Bottom Section:

• Build Panel: A closable panel showing compilation status, success messages, or detailed error messages with line numbers. It auto-runs after AI edits or manual code changes.

A UIMessage is the source of truth for your application's UI state. It represents the complete message history, including metadata, data parts, and all contextual information required for rendering the UI and managing client-side functionality.

Key Distinction:

• ModelMessage: Represents the state or context passed specifically to the AI model.
• UIMessage: Contains the full application state needed for the user interface.

WSH (wsh) is a cross-platform Go binary that runs on remote hosts to provide RPC services to Wave Terminal. It enables advanced features like file synchronization and deep shell integration.

Key Components:

• wsh version: Checks the installed version.
• wsh connserver: A long-running RPC server that handles file operations, command execution, and remote state information via a domain socket.

Installation Process: If WSH is missing or outdated, Wave Terminal will:

1. Detect the remote platform using uname -sm.
2. (Optional) Prompt the user for permission.
3. Copy the appropriate binary to ~/.waveterm/bin/wsh on the remote host.
4. Set executable permissions and restart the connection process.

Modes of Operation:

• With WSH: Full RPC support, file sync, and enhanced integration.
• Without WSH: Fallback mode providing basic shell access only.

Wave uses the wsh badge command to set or clear visual indicators on the current block or tab.

Key Behaviors:

• Auto-clear: Badges automatically disappear when you focus the block (click into it). They serve as transient "look here" signals.
• Badge Rollup: If a tab contains multiple terminals (blocks), Wave displays the badge with the highest priority on the tab header. If priorities are tied, the earliest badge set is shown.
• Priority Levels: Higher numbers take precedence. It is recommended to use high priorities (15–25) for permission-blocking signals and low priorities (5–10) for informational signals.

Customization:

• Icons: Use Font Awesome icon names (excluding the fa- prefix).
• Colors: Use any valid CSS color (hex, named colors, etc.).

Wave AI is a context-aware assistant that can access your workspace to assist with debugging and file operations.

Capabilities

• Terminal Context: Reads terminal output and scrollback for analysis.
• File Operations: Can read, write, and edit files (requires user approval and includes automatic backups).
• Local Models: Supports Ollama, LM Studio, and other OpenAI-compatible providers.
• BYOK: Supports OpenAI, Claude, Gemini, Azure, and Perplexity.

CLI Integration

You can use the wsh ai command to pipe output or attach files directly from the command line to the AI assistant. For more detailed usage, refer to the Wave AI documentation.

Wave Terminal uses a multi-layered focus system to coordinate visual feedback, layout state, and actual browser interaction. It separates concerns into four distinct layers:

1. Layout Focus State: Managed via Jotai atoms (e.g., nodeModel.isFocused) to track which block is logically focused.
2. Visual Focus Ring: CSS styling that provides immediate feedback to the user.
3. DOM Focus: The actual browser focus on interactive elements (like an input or terminal).
4. View-Specific Focus: Custom logic implemented by view models (e.g., XTerm terminal focus) to handle specialized input requirements.

This separation allows the UI to show a focus ring immediately on mousedown (Visual Focus) while deferring the actual DOM focus until the click interaction is complete, preventing the disruption of text selections.

Anthropic's API bills and rate-limits based on token counts. When calculating total input tokens for a request, you must sum the following three fields from the usage object:

1. input_tokens
2. cache_creation_input_tokens
3. cache_read_input_tokens

Note that output_tokens will be non-zero even for an empty string response due to internal API transformations.

When the model provides citations, the structure of the citation depends on the source document type:

• PDFs: Returns page_location.
• Plain text: Returns char_location.
• Content documents: Returns content_block_location.