myflames — MySQL Query Plan Visualizer

Visualize EXPLAIN ANALYZE FORMAT=JSON output as interactive SVG charts — and project the same analysis for AI agents and CI. One parser, many outputs, zero external dependencies. View on GitHub →

Documentation

Getting StartedInstall, first flame graph, live connection mode View TypesWhen to use each of the 5 visualization types CLI ReferenceEvery command, flag, and option ArchitectureHow the parser, renderers, and advisor work Teach Lessons (9)Animated algorithm walkthroughs with cost models

For AI agents & CI — one analysis, many projections

Raw EXPLAIN ANALYZE FORMAT=JSON is verbose: an LLM burns tokens parsing it before it can reason, and an SVG is invisible to an agent. myflames parses and analyzes a plan once, then projects it into a compact, source-grounded form an agent or pipeline can consume directly.

Token-cheap digest
  • myflames digest explain.json — a compact, LLM-ready digest (summary, warnings, fixes, plan skeleton) to paste into a model instead of the raw plan.
  • myflames digest explain.json --cost — measures the token + $ saving vs pasting the raw plan (typically ~4× fewer tokens). Exact counts via --tokenizer claude (your key) or --tokenizer gpt (keyless tiktoken).
Ranked advice & CI gate
  • myflames advise explain.json --json — ranked warnings + suggestions, each with a confidence.
  • myflames check explain.json --fail-on full_scan,filesort — exits 1 if a trigger matches; a CI / pre-commit / agent-loop gate (0 clean, 1 tripped, 2 bad input).
MCP server

Let an agent (Claude Code, Cursor, …) call myflames directly.

pip install 'myflames[mcp]'
claude mcp add myflames -- myflames-mcp

Tools: analyze_plan, digest_plan, compare_plans, explain_optimizer_switch, explain_query.

Machine-readable everywhere
  • Every --output writes a JSON sidecar (schema v1.3) beside the HTML/SVG, so tools and agents never parse the picture.
  • myflames diff before.json after.json --json emits a structured compare-1.0 delta.

Agent & CI subcommands reference →

Learn the algorithms — myflames teach

Interactive, offline-first HTML lessons that animate MySQL 8.4 and MariaDB 11.x internals with correct cost models. Every lesson has in-page sliders — no CLI flags, no re-running. Generated with myflames teach <lesson> -o <file>.html.

Storage internals Join algorithms
Query optimization

All 9 lessons with descriptions →

Flame graph — full execution hierarchy (default view)

Open full page (interactive) →

Bar chart — slowest operations first

Open full page (interactive) →

Treemap — area proportional to total time

Open full page (interactive) →

Diagram — Visual Explain-style flow

Open full page (interactive) →

Execution tree — collapsible plan tree

Open full page (interactive) →

Query Analysis panel — scenario demos

Each view includes a Query Analysis panel: optimizer features detected, warnings, and concrete tuning suggestions.

Full table scan
Hash join
BNL join buffer
Index Condition Pushdown

Complex queries — real-world patterns

Non-trivial query shapes captured live against MySQL 8.4: multi-CTE with window functions, correlated subqueries (the N+1 anti-pattern), and recursive CTEs for tree traversal. Each demo pipes through the advisor + collector pipeline and emits a JSON sidecar next to the HTML so AI agents and external tools can consume the analysis without parsing the SVG.

CTE + window functions

Top-3 earners per department using ROW_NUMBER() OVER (PARTITION BY …).

Correlated subquery

N+1 anti-pattern: per-row scalar subquery to look up max/count.

Recursive CTE

Org-chart traversal — anchor + recursive JOIN until depth limit.

Optimizer switches — one flag per demo

Plans captured live with a specific @@optimizer_switch feature active, so you can see what each switch looks like in a real EXPLAIN plan and read the one-line impact the advisor emits.

MySQL 8.4
MariaDB 11.4

Live connection mode — connect + explain + advise

These demos came from running myflames with real connection flags (-h host -P port -u user -p -e "SELECT …") against MySQL 8.4 and MariaDB 11.4. Each one embeds the collected schema, stats, and session variables, plus environment-specific tuning suggestions generated by the advisor. All 3 outputs (.svg, .html, .json) are produced by a single CLI invocation.

MySQL 8.4
MariaDB 11.4

HTML report — self-contained shareable report

Generate with myflames --output report.html explain.json. Includes embedded chart, analysis sidebar, and export buttons.

Open HTML report demo →

Before vs After comparison

Generate with myflames compare before.json after.json. Shows time deltas, operator changes, and a "what got better / worse" summary.

Open comparison demo →

Repository and README • Getting Started • CLI Reference • Architecture