Claude Skill

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.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download oliver-kriska-claude-elixir-phoenix-plugins_elixir-phoenix_skills_tidewave-integration-9767a82.zip · 7 KB

Install

skills CLI npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/tidewave-integration
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
Git git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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

# 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.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
Files (claude-elixir-phoenix)
  • references
    • proactive-patterns.md 3.8 KB
      Loading…
    • tool-examples.md 3.9 KB
      Loading…
    • validation-checklist.md 3.4 KB
      Loading…
  • SKILL.md 5.1 KB
    ---
    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: "test@example.com"})
    ```
    
    ### 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
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.