#202: Intro to Tidewave

I recently made some updates to the ElixirCasts site and I used Tidewave to help me debug issues and add new features quickly. If you’re not familiar with Tidewave, it’s a browser-based AI coding agent with deep Phoenix integration developed by José Valim and the team at Dashbit.

In this episode, we’ll explore how we can use Tidewave to make some changes to our music application here, which lists different artists and their albums. We’ll see how Tidewave can help us navigate our codebase, update the UI, query for data, and even fix bugs automatically.

Our application uses Phoenix, but it’s worth noting that Tidewave also works with non-Phoenix Elixir applications. Let’s start by installing Tidewave in our project. First, we’ll go over to Hex and grab the Tidewave configuration. Then we’ll open our Mixfile and add Tidewave to our list of dependencies.

Since Tidewave is a development tool that we won’t need in production, let’s ensure it’s only available in our development environment by adding only: :dev:

# mix.exs

...
[
  ...
  {:tidewave, "~> 0.5", only: :dev},
  ...
]
...

With our dependency added, let’s go to the command line and run mix deps.get to install Tidewave:

$ mix deps.get
...
New:
  circular_buffer 1.0.0
  tidewave 0.5.0

Great! Now we need to configure our Phoenix application to use Tidewave. Let’s check the docs, specifically the Tidewave for Phoenix installation documentation. There are some additional steps if you’ve upgraded from an older version of Phoenix or LiveView, but since I created our example app with Phoenix 1.8, we’re using the latest conventions.

All we need to do is add this code to our endpoint.ex module just before the if code_reloading? conditional. Let’s open our endpoint file and find the code_reloading? block. We’ll paste in our code just before that:

# lib/my_app_web/endpoint.ex
...

if Code.ensure_loaded?(Tidewave) do
  plug Tidewave
end
...

This code ensures that Tidewave is only plugged into our application if it’s actually loaded. With our configuration complete, let’s go to the command line and start our development server:

$ mix phx.server
...

Now we can go back to our application in the browser and navigate to the /tidewave route, which is a route that Tidewave adds to our application. Great, Tidewave is running! Before we can start using it, we need to log in through GitHub. I’ll go ahead and do that now.

Perfect! After logging in, we can see our application displayed in the Tidewave interface, along with some navigation features above it. This gives us a live preview of our app alongside the AI agent interface.

Now, to use the Tidewave agent, we need to configure an AI provider. Tidewave supports several options: Anthropic, GitHub Copilot, OpenAI, and OpenRouter. I’ll use Anthropic for this tutorial, so all we need to do is paste in an Anthropic API key.

Tidewave has a couple of different plans.

• It is free for open-source projects
• The Pro plan includes a free trial with a limit of 20 messages per month, which is perfect for testing Tidewave and light development work
• There’s also a team plan for larger organizations

It’s important to remember that when using Tidewave, you’ll be charged for the tokens you use via your AI provider.

One more thing to note, our example project doesn’t have an AGENTS.md file, but Tidewave recognizes this and uses a default. You can copy this default locally, make changes specific to your application’s needs, and then reload Tidewave to use it.

Alright, now let’s start using Tidewave, beginning with its unique point-and-click feature. When I enable this selector mode, you can see it highlights different parts of our UI as we hover over them. We can use this to ask the agent about specific parts of the application UI. Let’s test it out. I’ll select the “Edit” link and then add the prompt: “What component renders this link and what file is it in?”

Before we submit our prompt, notice that we can specify which AI model we want to use. Let’s stick with the default here and run our prompt.

We can watch as Tidewave analyzes our selection and then tells us exactly what file it’s in: the AlbumLive.Index module and even gives us the exact line number. This is an incredible feature for navigating unfamiliar codebases or quickly locating specific UI components.

Now let’s put Tidewave to work making actual changes to our UI. Let’s prompt Tidewave to: “Please update the ‘Edit’ and ‘Delete’ links to be buttons consistent with the ‘Artist’ and ‘New Album’ buttons.”

I’ll fast-forward things here, but as Tidewave processes this request, it shows us the code it wants to add, which we need to confirm. This gives us a chance to review changes before they’re applied. The proposed changes look good, but before I confirm, I’ll toggle the toggle auto-run mode in Tidewave’s settings. This allows Tidewave to continue working on a task until it’s completed, without asking for confirmation at each step.

With that enabled, we’ll confirm the action. When it’s finished, the agent provides a clear summary. It has updated the ‘Edit’ and ‘Delete’ links to be buttons and gives us a breakdown of the specific changes made. Let’s test these changes in the browser to confirm they work. These changes look great!

Now let’s check out another feature: instead of opening a console and running database queries manually, we can ask Tidewave questions about our data directly. Let’s ask: “What artist has the most albums in the database?”. Tidewave connects directly to our database and tells us we have 3 different artists, each with 2 albums. This feature is really convenient for quick data checks during development.

Now let’s see how Tidewave handles adding entirely new features. Let’s prompt it to: “Please add a stats section at the top of the album index showing which artist(s) has the most albums.”

Great, it’s finished! Looking at the change summary, we can see it:

• Added a new database function to calculate the statistics
• Updated the UI template to display the stats
• Modified the LiveView mount callback to load the statistics when the page loads

And we can see the new stats section is now displayed at the top of our page, showing our album statistics.

Now let’s explore one of my favorite features: debugging. To see this in action, let’s intentionally introduce an error. Let’s open our application code, go to the Artist module, and add a typo. Before we trigger the error, let’s look at the context window monitor in Tidewave. This shows how much of our conversation context we’ve used. If you ever want to start a fresh chat without the previous context, you can do that and still have access to previous chats.

Alright, now let’s click through our application. And as soon as we hit the error, Tidewave immediately recognizes it and prompts us to fix it!

Let’s let it work its magic. And there we go, it found our typo and fixed it for us!

Tidewave represents an exciting new frontier in Elixir development. We’ve seen how it can:

• Help us navigate unfamiliar codebases with point-and-click selection
• Make consistent UI updates across our application
• Query our database without leaving the browser
• Add new features with proper integration
• Automatically debug runtime errors

Whether you’re working on a new Phoenix project or maintaining an existing one, Tidewave can significantly speed up your development process.