Claude-elixir-phoenix tidewave-integration

Tidewave MCP runtime tools — debugging, smoke testing, live state inspection, SQL queries, hex docs. Use when evaluating code in a running Phoenix app.

install

source · Clone the upstream repo

git clone https://github.com/oliver-kriska/claude-elixir-phoenix

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/oliver-kriska/claude-elixir-phoenix "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/elixir-phoenix/skills/tidewave-integration" ~/.claude/skills/oliver-kriska-claude-elixir-phoenix-tidewave-integration && rm -rf "$T"

manifest: plugins/elixir-phoenix/skills/tidewave-integration/SKILL.md

Tidewave MCP Integration

Runtime intelligence for Phoenix apps via MCP. Prefer Tidewave tools over Bash when available.

Iron Laws — Never Violate These

DEV ONLY — Never use Tidewave tools in production contexts. Avoid on shared dev servers with production data copies

PREFER TIDEWAVE OVER BASH —

mcp__tidewave__get_docs

web_fetch

execute_sql_query

psql

CHECK AVAILABILITY FIRST — Use
```
/mcp
```
command or detect
```
mcp__tidewave__
```
tools
SQL IS READ-HEAVY — Use
```
execute_sql_query
```
for SELECT, be careful with mutations
EXACT VERSIONS —
```
get_docs
```
returns docs for YOUR mix.lock versions, not latest

Quick Reference

Task	Tidewave Tool	Fallback
Get docs	`mcp__tidewave__get_docs Module.func/3`	`web_fetch hexdocs.pm/...`
Run code	`mcp__tidewave__project_eval`	`mix run -e "code"`
SQL query	`mcp__tidewave__execute_sql_query`	`psql $DATABASE_URL`
Find source	`mcp__tidewave__get_source_location`	`grep -rn "defmodule"`
Inspect DOM	`mcp__Tidewave-Web__browser_eval`	Manual browser inspection
List schemas	`mcp__tidewave__get_ecto_schemas`	Read `lib/*/schemas/`
Read logs	`mcp__tidewave__get_logs level: :error`	`tail -f log/dev.log`

Detection

# Check endpoint
curl -s http://localhost:4000/tidewave/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

Or use

/mcp

in Claude Code to see connected servers.

Essential Patterns

Test Function Immediately

# mcp__tidewave__project_eval
MyApp.Accounts.create_user(%{email: "test@example.com"})

Verify Migration

-- mcp__tidewave__execute_sql_query
SELECT column_name, data_type FROM information_schema.columns
WHERE table_name = 'users';

Debug LiveView (with PID from browser)

# mcp__tidewave__project_eval
pid = pid("0.1234.0")
:sys.get_state(pid) |> Map.get(:socket) |> Map.get(:assigns) |> Map.keys()

Setup Requirements

# mix.exs
{:tidewave, "~> 0.1", only: :dev}

# endpoint.ex (in dev block)
plug Tidewave

# config/dev.exs (for LiveView source mapping)
config :phoenix_live_view,
  debug_heex_annotations: true,
  debug_attributes: true

Proactive Runtime Checks

Don't just use Tidewave reactively. Query runtime state at workflow checkpoints automatically:

After code edits:
```
get_logs level: :error
```
(catch runtime crashes)
After features complete:
```
project_eval
```
smoke test (behavioral check)
Before planning:
```
get_ecto_schemas
```
+ routes eval (concrete context)
When investigating: Auto-capture errors before asking user
LiveView UI bugs:
```
browser_eval
```
to inspect DOM state before editing components

See

${CLAUDE_SKILL_DIR}/references/proactive-patterns.md

for full integration points.

References

For detailed patterns, see:

${CLAUDE_SKILL_DIR}/references/proactive-patterns.md

- Push-like runtime patterns at workflow checkpoints

${CLAUDE_SKILL_DIR}/references/tool-examples.md

- Complete tool usage examples

${CLAUDE_SKILL_DIR}/references/validation-checklist.md

- Runtime validation patterns