Tidewave Phoenix Documentation

Tidewave is an AI developer toolkit designed for full-stack Phoenix and Rails applications. It aims to increase productivity when using coding agents to build web applications through three primary components:

• Tidewave Toolbar: A tool for creating prompts via UI element inspection, building UI variants, and diagnosing web accessibility or application errors.
• Tidewave Connect: A bridge that connects your coding agent to your browser, enabling testing, debugging, and video recording with captions, overlays, and narration.
• Tidewave MCP: A Model Context Protocol (MCP) implementation that connects your coding agent directly to your web framework. This allows the agent to run code, query databases, and read documentation specific to your project's dependencies.

Spaces allow you to connect a single Tidewave IDE tab to multiple web applications and manage multiple coding agents side-by-side. These applications can be different instances of the same app or entirely different applications.

To use a Space, Tidewave IDE only requires the port on which your web application is running. The IDE organizes these connections in the sidebar.

Tidewave IDE allows you to enable external agents that implement the Agent Client Protocol (ACP). These can be enabled in the External Agents tab under the Advanced Settings.

Note: Because ACP is an evolving protocol, compatibility with all agents is not guaranteed.

The Task Board in Tidewave IDE allows you to break large goals into smaller, trackable tasks that persist across different chat sessions. This is useful for:

• Planning: Breaking a large goal into a structured plan to delegate across sessions.
• Parallel workstreams: Using one session to manage tasks while another session claims and completes them.
• Resuming work: Closing a session and returning later to continue exactly where you left off.

Tasks are stored in your ~/.claude/tasks folder to ensure cross-agent compatibility, even if you are not using Claude Code.

The UI variant system relies on specific HTML attributes that the agent uses to annotate elements. Tidewave automatically teaches the agent how to apply these:

1. data-tw-container: Marks the element that acts as the wrapper for the variants.
2. data-tw-variant: Marks the individual variant elements within a container.

Rendering Behavior: All variants are rendered on the page, but only one active variant is visible at a time. This makes the system ideal for exploring UI changes, component designs, or different component states (e.g., different steps in a wizard). For large-scale changes like entire navigation flows, using git branches is recommended instead.

When variants are present, a floating UI appears at the bottom of the page to allow switching between them.

When running Tidewave IDE as a browser app (PWA), you gain access to several OS-level integrations:

• Menu Bar Integration: Clicking "Open in browser" in the Tidewave IDE menu (located at the top right on macOS/Linux or bottom right on Windows) will launch the browser app window.
• Agent Notifications: When the agent is waiting for user input, a notification indicator will appear in your OS dock or taskbar.

When setting up a remote Tidewave IDE environment, keep the following requirements in mind:

1. Co-location: The Tidewave IDE must run on the same machine as your web application to ensure it has access to the project files.
2. HTTPS: It is strongly advised to use HTTPS addresses for remote access. Remote instances may not function correctly over unencrypted connections.
3. CLI Usage: When running Tidewave IDE on a remote node, you must use the Tidewave IDE CLI.

Before starting an actual video recording, the agent performs a rehearsal.

During this phase, the agent:

1. Practices the sequence to iron out details.
2. Identifies elements using query selectors (IDs, labels) to handle dynamic pages.
3. Performs any necessary changes and then cleans them up before the actual recording begins.

For highly dynamic pages, it is recommended to reinforce instructions for the agent to use stable query selectors to ensure the rehearsal and recording are successful.

Tidewave's data collection policies are as follows:

Tidewave Package

• Logs basic request metadata (e.g., timestamps, features used).
• Prompts are NOT logged unless you explicitly opt in.

Tidewave IDE

• Logs basic request metadata (e.g., timestamps, model used, token counts).
• Prompts and messages are NOT logged unless you explicitly opt in.
• Tidewave does not receive, process, or store tool call results.

Note: The underlying coding agent you use may store data separately according to their own user agreement; this is outside of Tidewave's control.

You can extend Tidewave IDE beyond the official providers using these methods:

OpenCode Providers

OpenCode supports over 75 providers (e.g., OpenRouter, Moonshot AI). You can add new models directly within the Tidewave IDE Provider settings by clicking the Add models button.

Codex Custom Providers

You can configure Codex to work with any OpenAI-compatible endpoint (like Ollama or OpenRouter) by editing your ~/.codex/config.toml file.

# Example: Using Codex with OpenRouter in ~/.codex/config.toml
model = "anthropic/claude-sonnet-4.5"
model_provider = "openrouter"

[model_providers.openrouter]
name = "Openrouter"
base_url = "https://openrouter.ai/api/v1"
http_headers = { "Authorization" = "Bearer sk-or-v1-..." }
wire_api = "chat"

Tidewave Connect supports viewport customization to simulate different devices and test responsive breakpoints.

Manual Control: Users can click the display icon in the top right of the Tidewave interface to select from available presets or enter custom dimensions.

Agent Control: Coding agents can also manipulate the viewport. You can ask an agent to verify how your application renders on mobile or specific screen sizes to ensure breakpoints are functioning correctly.