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

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

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:

1. Clarify edge cases — "Should it match Unicode? Multi-line? Partial strings?"
2. Write the pattern — Start simple, add complexity as needed
3. Explain every part — Use the explanation field with bullet points
4. Provide test cases — At least 2 matching + 2 failing strings
5. Show the visualization — Start the server if not running

Debugging Existing Regex

When the user has a regex that isn't working:

1. Understand the intent — "What should this match?"
2. Identify the bug — Run mental simulation, find the failure point
3. Explain the issue — "The pattern fails at character N because..."
4. Fix and visualize — Update data.json, let the animation show the fix
5. Compare before/after — Explain what changed and why

Iterative Refinement

The power move: user tests in browser, sees failure, asks you to fix.

1. User: "It's not matching X"
2. You: Explain WHY it fails (the animation shows the derailment point)
3. You: Fix the pattern, update data.json
4. Browser: Diagram morphs, user retests
5. Repeat until perfect

Regex Parser Coverage

The template's built-in parser handles:

Visual Reference

Color Coding

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)