sqlplan-slim

sqlplan-slim compacts SQL Server Showplan XML (.sqlplan) into small, agent-friendly Markdown or JSON. It is meant for Codex, Claude Code, and similar agentic coding tools that should reason about execution plans without spending most of their context window on raw XML.

Demo

go run ./cmd/sqlplan-slim summarize ./testdata/actual_join.sqlplan --level full

Example output:

PLAN v1 stmt=SELECT ce=170 dop=1 cost=0.02894 redacted=true

WARN
- none

HOT
- high_cost op=0 score=100.0 Sort 100.0% estimated subtree cost
- high_cost op=2 score=60.5 Nested Loops 60.5% estimated subtree cost

TREE
0 Sort log=TopN Sort e=13.04 a=8 cost=100.0%
  1 Compute Scalar e=13.04 a=? cost=60.5%
    2 Nested Loops log=Inner Join e=13.04 a=8 cost=60.5%
      4 Index Seek e=3 a=3 cost=11.4% obj=db.Sales.SalesOrderHeader/IX_SalesOrderHeader_CustomerID

Getting Started

Build from source:

go build -o .\bin\sqlplan-slim.exe .\cmd\sqlplan-slim

Run a compact summary:

.\bin\sqlplan-slim.exe summarize .\testdata\estimated_index_seek.sqlplan

Run the full compact operator tree:

.\bin\sqlplan-slim.exe summarize .\testdata\estimated_index_seek.sqlplan --level full

Emit JSON for scripts, tests, or future MCP wrappers:

.\bin\sqlplan-slim.exe summarize .\testdata\estimated_index_seek.sqlplan --level full --format json

Defaults are --level summary, --format md, --top 30, and redaction enabled. Use --no-redact only for trusted local analysis.

CLI

sqlplan-slim summarize <file.sqlplan> [--level summary|full] [--format md|json] [--top N] [--redact|--no-redact]
sqlplan-slim version

Output sections:

• PLAN: statement metadata, SQL Server build, cardinality estimator, DOP, estimated cost, redaction state.
• WARN: plan warnings such as missing indexes, spills, memory grants, implicit conversions, and cardinality mismatches.
• HOT: prioritized operator hotspots by estimated cost and warning severity.
• TREE: compact operator tree, included only with --level full.
• LEGEND: stable decoding table for agents.

Legend shortcuts:

• e: estimated rows.
• a: actual rows; ? means estimated-only or runtime rows absent.
• cost: estimated subtree cost share.
• seek: seek predicate.
• pred: filter, join, or residual predicate.
• est_miss: max(actual/estimated, estimated/actual).
• spill: tempdb spill warning.

Agent Integration

The recommended pattern is two-stage:

1. Ask the agent to run sqlplan-slim summarize <plan.sqlplan> --level summary.
2. Ask for --level full only when it needs the compact operator tree or predicates.

Raw Showplan XML should be read only when the compact output cannot answer the question.

Codex Skill

This repository includes a ready-to-copy Codex plugin skill template:

• integrations/codex-plugin/sqlplan-slim/.codex-plugin/plugin.json
• integrations/codex-plugin/sqlplan-slim/skills/sqlplan-slim/SKILL.md

For a personal local Codex plugin, copy the template to your Codex plugin folder and adjust the binary path in SKILL.md:

New-Item -ItemType Directory -Force "$HOME\plugins" | Out-Null
Copy-Item -Recurse .\integrations\codex-plugin\sqlplan-slim "$HOME\plugins\sqlplan-slim"

Then add or update your personal marketplace file at ~/.agents/plugins/marketplace.json so it contains:

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "sqlplan-slim",
      "source": {
        "source": "local",
        "path": "./plugins/sqlplan-slim"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Some Codex builds expose plugin installation in the app UI instead of the CLI. If your CLI supports plugin management, install from the personal marketplace with the command shown by your Codex version. Otherwise open the plugin from the Codex app marketplace view after copying the files.

Claude Code

Claude Code can use a project instruction file. Copy the template to the project where you analyze plans:

Copy-Item .\integrations\claude-code\CLAUDE.md .\CLAUDE.md

Then adjust the binary path if needed. The template tells Claude Code to run sqlplan-slim before reading raw .sqlplan XML.

Validation

Run unit tests:

go test ./...

Regenerate the public test fixtures from a local AdventureWorks database:

.\scripts\generate-adventureworks-fixtures.ps1 -Server localhost -Database AdventureWorks2022 -Username sa -Password '<password>'
go test ./...

Validate against local external plan folders, when present:

.\scripts\validate-external-plans.ps1 -Roots @('C:\path\to\plans') -Level summary -Format md
.\scripts\validate-external-plans.ps1 -Roots @('C:\path\to\plans') -Level full -Format md

Last measured result across one private local validation corpus of 50 real .sqlplan files:

• summary: 50/50 parsed, 1,163,822 input bytes to 37,284 output bytes, 31.2x reduction.
• full: 50/50 parsed, 1,163,822 input bytes to 59,744 output bytes, 19.5x reduction.

Scope

sqlplan-slim is a lossy analysis view, not a replacement for the original plan. It intentionally extracts the parts that usually matter for first-pass agent analysis: operator tree, object access, estimates vs actual rows, predicates, cost hotspots, missing indexes, spills, lookups, scans, and key warnings.

The parser is tolerant and uses Go's encoding/xml token stream instead of generated Showplan XSD bindings, so unknown SQL Server plan elements are ignored unless they are explicitly modeled.

Contributing

Before changing parser behavior, regenerate or update a fixture under testdata and run:

go test ./...
.\scripts\validate-external-plans.ps1 -Roots @('C:\path\to\plans') -Level summary -Format md
.\scripts\validate-external-plans.ps1 -Roots @('C:\path\to\plans') -Level full -Format md

Do not commit private customer plans. Prefer AdventureWorks-generated plans for public fixtures.