jord0-cmd REGTRAX — Regex Railroad Visualizer
"Don't just write Regex. Replay it."
Author: jord0 | Version: 1.0
Prerequisites
- Python 3 (for
http.server) - Modern browser (Chrome, Firefox, Safari, Edge)
Usage
Describe what you want to match, or paste a regex you want to understand. REGTRAX generates an animated railroad diagram and serves it in your browser.
Match email addresses that end in .gov or .mil
Debug this regex: ^(\d{4}-\d{2}-\d{2})\s(INFO|WARN|ERROR)\s(\w+):\s(.+)$
Explain this pattern — I inherited it and nobody knows what it does
What You See
A dark-themed railroad diagram with colour-coded nodes: cyan for literals, amber for character classes, violet for quantifiers, emerald for groups, rose for anchors. Type a test string and watch a photon walk the track — green on match, red on failure with the exact derailment point highlighted.
When to Invoke
- User asks for help writing a regex
- User wants to understand/debug an existing regex
- User says "regex", "pattern", "match", "railroad", "visualize"
- User provides a natural language description of what to match
- User has a regex that isn't working and wants to see why
Capability Lookup
| Task | REGTRAX Does |
|---|---|
| Natural language → regex | Write the pattern + explanation |
| Explain existing regex | Parse it, describe each part |
| Debug failing regex | Visualize where the match fails |
| Test regex interactively | Animated dot traversal in browser |
| Compare regex versions | Update pattern, diagram morphs live |
| Teach regex concepts | Visual railroad + plain English |
How It Works
The Flow
1. User describes what they want to match (or provides a regex to debug)
2. You write the regex pattern with plain-English explanation
3. Copy template → /tmp/regtrax/index.html
4. Write regex data → /tmp/regtrax/data.json
5. Start local server on port 8787
6. User opens browser, tests strings, sees animated diagram
7. User asks for changes → you update data.json → diagram morphs live
Step-by-Step
1. Set Up the Server (First Time)
mkdir -p /tmp/regtrax
cp ~/.claude/skills/REGTRAX/references/template.html /tmp/regtrax/index.html
2. Write the Data File
Write /tmp/regtrax/data.json with the regex pattern, flags, explanation, and test cases:
{
"pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
"flags": "",
"explanation": "Matches email addresses:\n- ^ anchors to start of string\n- [a-zA-Z0-9._%+-]+ matches the local part (letters, digits, dots, underscores, percent, plus, hyphen)\n- @ matches the literal @ symbol\n- [a-zA-Z0-9.-]+ matches the domain name\n- \\.[a-zA-Z]{2,} matches a dot followed by the TLD (2+ letters)\n- $ anchors to end of string",
"testCases": [
{ "input": "hello@world.com", "shouldMatch": true },
{ "input": "user+tag@domain.co.uk", "shouldMatch": true },
{ "input": "not-an-email", "shouldMatch": false },
{ "input": "@missing-local.com", "shouldMatch": false }
]
}
3. Start the Server
cd /tmp/regtrax && python3 -m http.server 8787
Run this in the background. Tell the user to open http://localhost:8787.
4. Update the Pattern (Live)
When the user asks for changes, just rewrite /tmp/regtrax/data.json. The browser
polls every 500ms and will detect the change automatically. The diagram morphs in place.
Do NOT restart the server. The HTML poller handles everything.
The data.json Contract
| Field | Type | Required | Description |
|---|---|---|---|
pattern |
string | yes | The regex pattern (no delimiters) |
flags |
string | no | Regex flags: i, g, m, s, etc. |
explanation |
string | yes | Plain-English explanation with bullet points |
testCases |
array | no | Array of { input, shouldMatch } objects |
Escaping Rules
JSON requires double-escaping backslashes. \d becomes \\d, \. becomes \\., etc.
Regex: ^\d{3}-\d{4}$
JSON: "^\\d{3}-\\d{4}$"
AI Partnership Patterns
Building Regex from Natural Language
When the user describes what to match:
- Clarify edge cases — "Should it match Unicode? Multi-line? Partial strings?"
- Write the pattern — Start simple, add complexity as needed
- Explain every part — Use the explanation field with bullet points
- Provide test cases — At least 2 matching + 2 failing strings
- Show the visualization — Start the server if not running
Debugging Existing Regex
When the user has a regex that isn't working:
- Understand the intent — "What should this match?"
- Identify the bug — Run mental simulation, find the failure point
- Explain the issue — "The pattern fails at character N because..."
- Fix and visualize — Update data.json, let the animation show the fix
- Compare before/after — Explain what changed and why
Iterative Refinement
The power move: user tests in browser, sees failure, asks you to fix.
- User: "It's not matching X"
- You: Explain WHY it fails (the animation shows the derailment point)
- You: Fix the pattern, update data.json
- Browser: Diagram morphs, user retests
- Repeat until perfect
Regex Parser Coverage
The template's built-in parser handles:
| Feature | Syntax | Supported |
|---|---|---|
| Literals | a, 1, @ |
Yes |
| Escaped chars | \d, \w, \s, \. |
Yes |
| Hex escapes | \x00-\xFF |
Yes |
| Unicode escapes | \u0000-\uFFFF |
Yes |
| Character classes | [a-z], [^0-9], [\w\s] |
Yes |
| Dot (any char) | . |
Yes |
| Alternation | a|b|c |
Yes |
| Quantifiers | ?, *, + |
Yes |
| Bounded quantifiers | {n}, {n,}, {n,m} |
Yes |
| Lazy quantifiers | ??, *?, +? |
Yes |
| Capturing groups | (abc) |
Yes |
| Named groups | (?<name>abc) |
Yes |
| Non-capturing groups | (?:abc) |
Yes |
| Backreferences | \1-\9 |
Yes |
| Anchors | ^, $ |
Yes |
| Word boundaries | \b, \B |
Yes |
| Positive lookahead | (?=abc) |
Yes |
| Negative lookahead | (?!abc) |
Yes |
| Lookbehind | (?<=), (?<!) |
No |
| Unicode properties | \p{L} |
No |
Visual Reference
Color Coding
| Node Type | Color | Var |
|---|---|---|
| Literals | Cyan/teal | --cyan: #06b6d4 |
| Character classes | Amber | --amber: #f59e0b |
| Quantifiers | Violet | --violet: #8b5cf6 |
| Groups | Emerald | --emerald: #10b981 |
| Anchors | Rose | --rose: #f43f5e |
Animation States
- Idle: Faint breathing glow on tracks
- Advancing: Cyan photon with fading trail
- Match: Green pulse, all tracks light up
- Fail: Red photon derails with gravity fall
- Scrubbing: Manual step-through, no animation
Serving Instructions
Start Server
mkdir -p /tmp/regtrax
cp ~/.claude/skills/REGTRAX/references/template.html /tmp/regtrax/index.html
cd /tmp/regtrax && python3 -m http.server 8787 &
Check If Already Running
lsof -i :8787
If already running, skip the server start. Just update data.json.
Stop Server
kill $(lsof -t -i :8787) 2>/dev/null
Companion Skills
- REFRAX — Visual code comprehension (different visual domain)
- LOCUS — Interactive image hotspots
- OPTIC — AI image generation
Security Checklist
- No external CDN or script tags — everything is inline
- No eval() or Function() constructor
- No localStorage/sessionStorage of sensitive data
- Server binds to localhost only (python http.server default)
- data.json contains only pattern data, no executable code
- Template is read-only — Claude never modifies it at runtime
Quality Checklist
- Pattern is syntactically valid (test with
new RegExp()mentally) - Explanation covers every part of the pattern
- At least 2 matching + 2 failing test cases provided
- Escaping is correct in JSON (double backslashes)
- Server is running before telling user to open browser
- data.json is valid JSON (no trailing commas, proper quotes)