Tidewave Integration

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 492f17636999 · 18 Oct 2026Report an issue or request a re-scan

• Publisheroliver-kriska GitHub userOwner of the repository this skill is read from
• Source folderoliver-kriska/claude-elixir-phoenix/plugins/elixir-phoenix/skills/tidewave-integrationThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict492f17636999A new audit runs when the source changes
• Repository statusNot archivedLast push 2 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

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

---
name: tidewave-integration
description: "Tidewave MCP runtime tools — debugging, smoke testing, live state inspection, SQL queries, hex docs. Use when evaluating code in a running Phoenix app."
effort: low
user-invocable: false
---

# Tidewave MCP Integration

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

## Iron Laws — Never Violate These

1. **DEV ONLY** — Never use Tidewave tools in production contexts. Avoid on shared dev servers with production data copies
2. **PREFER TIDEWAVE OVER BASH** — `mcp__tidewave__get_docs` > `web_fetch`, `execute_sql_query` > `psql`
3. **CHECK AVAILABILITY FIRST** — Call Tidewave only when matching `mcp__tidewave__*` tools are present
4. **SQL IS READ-HEAVY** — Use `execute_sql_query` for SELECT, be careful with mutations
5. **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

```bash
# 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

```elixir
# mcp__tidewave__project_eval
MyApp.Accounts.create_user(%{email: "[email protected]"})
```

### Verify Migration

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

### Debug LiveView (with PID from browser)

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

## Setup Requirements

```elixir
# mix.exs
{:tidewave, "~> 0.6", 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
```

The dependency and endpoint plug expose Tidewave's streamable HTTP server; they
do not register it with an MCP client. Configure the current runtime separately
with `http://localhost:<port>/tidewave/mcp`, then verify that Tidewave tools are
available before relying on this skill.

## Reliability Guards

**Worktree/port check (FIRST, in multi-worktree setups)**: multiple
worktrees = multiple dev servers on different ports. Before trusting any
Tidewave result, confirm the endpoint belongs to THIS checkout: grep
`config/dev.exs` for the configured port, and verify with
`project_eval File.cwd!()` — if it returns a different worktree path,
you're debugging the wrong server.

**Schema introspection BEFORE SQL**: never guess column names. Run
`get_ecto_schemas` (or query `information_schema.columns`) before writing
SQL against a table you haven't already introspected this session. A
guessed-column error costs more than the introspection.

**Output-size guard**: runtime output is unbounded. Always cap it —
`LIMIT 20` in SQL, `Enum.take(20)` in evals, `inspect(x, limit: 50,
printable_limit: 500)` for large structs. Re-query narrower rather than
dumping wide.

**browser_eval fallback**: if `mcp__Tidewave-Web__browser_eval` is absent
or errors, don't stall — inspect the same state server-side: LiveView
assigns via `:sys.get_state(pid)` in `project_eval`, rendered HTML via
`Phoenix.LiveViewTest`, or read the template source directly.

**QA walkthrough pattern**: after a feature completes, run a short
checklist through `project_eval`/`browser_eval`: create the record, fetch
it back, exercise the main event, check `get_logs level: :error` is clean.
Report each step's pass/fail — not just "smoke test passed".

## Proactive Runtime Checks

**Query runtime state at workflow checkpoints** without waiting
to be asked:

- **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

Excerpt, first 5,156 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-18
   ✓SAFE B 89 / 100

   first audit · source 492f17636999

Questions about Tidewave Integration

• github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins — the audited source at commit 492f17636999 and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology