# Regex Explainer

> Break a regular expression down into plain English, piece by piece, and flag the patterns that are dangerous rather than merely wrong: nested quantifiers that backtrack catastrophically, missing anchors that let a match float anywhere in the input, unescaped dots that match more than intended, and character classes whose ranges do not cover what their author assumed.

Four surfaces over one engine: an HTML page for people, a markdown
representation of every page at the same URLs, a JSON API, and an MCP server.
All four return the same answers — the engine is a single pure function and the
surfaces are thin wrappers over it.

For markdown, send `Accept: text/markdown` or append `?format=md` to any page
URL. Responses set `Vary: Accept`. Do not parse the HTML.

**What this is not:** Does not execute or test the expression against sample input, and does not translate between regex dialects. Recognises JavaScript regex syntax; Perl, PCRE, and .NET constructs that JavaScript lacks are reported as unsupported rather than guessed at.

Agent traffic is welcome and unmetered up to 250 calls per
UTC day per caller. Past that, endpoints return HTTP 402 with x402 payment
requirements ($0.001 per call, USDC on base).
Content is identical for agents and people; only the representation differs.

## Agent endpoints

- [MCP server](https://regex-explainer.gumballtools.com/api/mcp): Streamable HTTP. Tools: explain_regex.
- [OpenAPI document](https://regex-explainer.gumballtools.com/.well-known/openapi.json): Full machine-readable API description.
- [Explain a regex](https://regex-explainer.gumballtools.com/api/v1/explain?pattern=%5E%5Cd%2B%24): plain-English breakdown plus backtracking and anchoring warnings.
- [Full documentation](https://regex-explainer.gumballtools.com/llms-full.txt): Complete docs with worked examples, inline.
- [Changelog](https://regex-explainer.gumballtools.com/changelog.md): Breaking changes and additions.

## MCP tools

### `explain_regex`

Explain a regular expression in plain English and detect the failure modes that make patterns dangerous rather than merely wrong.

Use this whenever a regex needs to be read, reviewed, or verified — and ALWAYS before putting a pattern somewhere it will run against untrusted input. The critical check is catastrophic backtracking: a pattern like (a+)+$ is three characters longer than a safe equivalent, looks harmless, and takes minutes of CPU on a 30-character input that almost matches. That makes it a denial-of-service vector. Whether a pattern is vulnerable depends on whether nested quantifiers can match the same characters in more than one way, which is a structural property that is unreliable to judge by reading.

It also flags: missing anchors (an unanchored validator accepts any string that merely CONTAINS a valid value), unescaped dots, character ranges like [A-z] that span punctuation, alternation precedence mistakes where an anchor applies to only one branch, and constructs JavaScript does not support.

Input: `pattern` accepts either a bare pattern or a full /pattern/flags literal. JavaScript syntax; PCRE-only constructs are reported as unsupported rather than guessed at.

Returns: `summary` (one sentence), `steps` (an ordered walkthrough), `warnings` (each with a code, severity, detail, and fix), `flagNotes`, capture group counts and names, and `hasBlockingIssue` — check that flag first. If the pattern cannot be parsed it returns an error naming the position, rather than a plausible-looking explanation of something else.

## Markdown representations

Every page is available as markdown at the same canonical URL. Send
`Accept: text/markdown` or append `?format=md`. Responses set
`Vary: Accept`. Do not parse the HTML.

## Docs

- [Documentation and MCP setup](https://regex-explainer.gumballtools.com/docs): Copy-paste MCP config for Claude Code, Claude Desktop, and Cursor, plus curl examples.

## Pages

- [Regex Explainer](https://regex-explainer.gumballtools.com/): Explain any regular expression, and catch the ones that can hang
- [API and MCP setup](https://regex-explainer.gumballtools.com/docs): JSON API reference and MCP configuration
- [The email validation regex that hangs](https://regex-explainer.gumballtools.com/regex/email-validation-regex): A widely copy-pasted email pattern with nested quantifiers. It works on valid input and takes minutes on the wrong invalid input.
- [Catastrophic backtracking, minimal example](https://regex-explainer.gumballtools.com/regex/catastrophic-backtracking-example): The smallest pattern that exhibits exponential backtracking. Three characters longer than the safe version and indistinguishable by eye.
- [What does \d mean in regex?](https://regex-explainer.gumballtools.com/regex/what-does-slash-d-mean): The digit class, and what it does and does not include.
- [Regex for a YYYY-MM-DD date](https://regex-explainer.gumballtools.com/regex/regex-for-date-yyyy-mm-dd): Named capture groups for the parts, and why this validates shape but not calendar validity.
- [Regex for a semantic version](https://regex-explainer.gumballtools.com/regex/regex-for-semantic-version): Escaped dots, and what happens when you forget to escape them.
- [Why an unescaped dot matches too much](https://regex-explainer.gumballtools.com/regex/unescaped-dot-in-regex): A pattern written for a domain name that also matches strings with no dot in them at all.
- [Why [A-z] is almost never what you want](https://regex-explainer.gumballtools.com/regex/a-to-z-character-range): Ranges follow character codes, not the alphabet, so this one quietly includes six punctuation characters.
- [Greedy vs lazy quantifiers](https://regex-explainer.gumballtools.com/regex/greedy-vs-lazy-quantifiers): The same pattern with and without the lazy modifier, and what each one actually consumes.
- [Lookahead for password rules](https://regex-explainer.gumballtools.com/regex/lookahead-password-validation): Stacked lookaheads let you require several things at once without dictating their order.
- [What ^ and $ actually anchor to](https://regex-explainer.gumballtools.com/regex/regex-anchors-explained): The difference between validating a whole value and finding one inside other text.
- [Why ^a|b does not mean what it looks like](https://regex-explainer.gumballtools.com/regex/alternation-precedence-trap): Alternation binds more loosely than everything else, so the anchor applies to only one branch.
- [Regex for a URL](https://regex-explainer.gumballtools.com/regex/regex-for-url): A practical URL pattern, with the parts that are easy to get subtly wrong called out.
- [What \b matches](https://regex-explainer.gumballtools.com/regex/word-boundary-regex): Word boundaries are positions, not characters, which is why they behave oddly at the edges of a string.
- [Regex for a hex colour](https://regex-explainer.gumballtools.com/regex/regex-for-hex-color): Three or six hex digits, and why the alternation order matters here.