Hello Curious Coders,

We have talked about Tidewave for a while now without installing it. That was on purpose.

Bruce made the reason plain in class:

“You might be curious as to why we waited this long. Well, I think that you should understand the tools that you’re working with and the layering before you add the accelerators and become dependent on them.”

– Bruce Tate

That is the discipline behind this whole series. Learn the raw tools first, get the memory hierarchy in order, and only then bolt on the accelerator. When you understand what the model already sees, you can use Tidewave with precision instead of hoping it fills the gaps. So let’s install it. And once it’s in, there are two directions you can wire it, which is the part that trips people up.

Three Pieces, Each With Two Halves

Before any code, hold a simple picture in your head. Installing Tidewave means putting three pieces in a room together: your application, Tidewave, and Claude. Each has something you interact with and something doing work behind it.

Your Phoenix app has its usual web front end and its backend, running where it always runs, on localhost:4000. Tidewave has both halves too. Its front end is a plain web application you log into. Its backend is where the real work happens: a plain HTTP GenServer that does the code generation and talks to the browser over HTTP. That backend runs on its own port, localhost:9832. Claude Code has the same split, but it looks different: the terminal or editor is the interface, and Claude is the service behind it.

Keep those two ports separate in your mind. Phoenix on 4000, Tidewave on 9832. Which service owns which port is the single detail that makes the rest of this make sense.

The Install: A Dependency and One Plug

The mechanics are short. Add the Tidewave dependency and run mix deps.get to pull down the code. Make sure you’re on Phoenix LiveView 1.1, since Tidewave needs it. Then you add exactly one thing to your endpoint: a plug.

Here Bruce reaches back to something we’ve leaned on all through the Elixir track.

“Remember that the endpoint is one giant function where the individual plugs are reducers. So I’m going to add a plug. This will ensure that Tidewave is loaded and started.”

– Bruce Tate

That framing is worth pausing on. A Phoenix endpoint is not a pile of configuration. It’s one function, and the plugs are the reducers that snap together to handle a request. Each plug takes the connection, does its bit, and passes it along. Adding Tidewave means adding one more reducer to that chain.

This plug does three things at once. It checks that you’re in the development environment, so nothing ships to production. It makes sure Tidewave is loaded and its MCP server is started. And it wraps your Phoenix app so all the Tidewave routes come along for the ride. That’s it. One reducer, guarded to dev, and Tidewave is part of your running app.

Direction One: Tidewave in the Browser

Now the fork. Start your Phoenix server, run your app at localhost:4000, and open it inside the Tidewave window. Your application is now running inside Tidewave, in the browser.

At this point Tidewave needs a provider, which is just the agent it runs through. You connect Claude Code as that provider. Say connect, and Tidewave starts Claude Code, ties the two together, and automatically pulls in the Tidewave MCP server. Ask Claude “who are you?” and it will tell you it’s Anthropic’s Claude Code. Ask what it can do through Tidewave, and a new set of tools appears: evaluate against the browser, restart the application, read the logs, run SQL, fetch your Ecto schemas.

This is the setup for UI-focused work. You’re in the browser, watching the page, and Claude is right there with you as the engine underneath Tidewave.

Direction Two: Claude Code With Tidewave as MCP

The other direction flips the roles. Instead of Tidewave running Claude Code, you run Claude Code and hand it Tidewave as an MCP server.

Make sure your app is running with mix phx.server, then, from a normal shell and not from inside Claude, add the server:

claude mcp add --transport http tidewave http://localhost:4000/tidewave/mcp

Look closely at that URL. The port is 4000, your running application’s port, not 9832. That surprises people. It works because the plug you added publishes the MCP routes as part of your app. The MCP server lives inside the application you already started, so you point Claude at the app.

Inside Claude Code, type /mcp. It lists your servers, you’ll see Tidewave connected, and it exposes seven tools: get docs, get source location, get logs, project_eval, execute SQL, and fetch Ecto schemas. A quick tour shows what that buys you.

Ask for docs on Phoenix.assign/3 and it returns the real documentation, drawn from the dependencies actually installed in your app. Run SELECT * FROM users and it executes against your Postgres through the Ecto connection. Even on an empty table it hands back the columns your schema defines. Call IEx.Helpers.exports on a context like your accounts module and it lists the public functions, grouped and typed. That last one is the tell: project_eval is a live IEx session running in your application’s context.

Same Model, More Knowledge

Here is the thing to carry away, because it’s easy to oversell. Wiring in Tidewave does not make Claude smarter. It’s the same model, reasoning the same way. What changed is what it can see.

“The MCP is part of the secret sauce for what makes Tidewave so effective. It has the tools that provide the metadata that everyday developers take advantage of.”

– Bruce Tate

That word, metadata, is the whole story. Without Tidewave, the model guesses at your function signatures, your schema, your installed versions. With it, the model asks. It reads the docs that match the version you actually have, queries the database you actually run, and inspects the modules that actually exist. Guessing becomes knowing.

So pick your direction by the work in front of you. In the browser, watching a LiveView take shape, run Tidewave with Claude Code as the provider. Planning and building the context layer from the terminal, run Claude Code with Tidewave as an MCP server. Either way, the same model now stands on live, version-matched knowledge instead of assumptions. And just remember which port belongs to which service.

Of those seven tools, one is the Swiss Army knife the whole workflow turns on. That’s project_eval, and it’s worth its own post.

— Paulo & Bruce