QR Bridge

Entry point reconnaissance tool. Decode QR codes, trace redirect chains, inspect gated destinations, and explain what the link actually needs.

When to Use This Skill

Activate when the user asks to:

• Decode / scan / read a QR code from an image
• Trace where a short URL redirects to
• Check if a link requires WeChat / WeCom / login / app
• Diagnose why a link "doesn't work"
• Generate a QR code from text or URL

Setup (First Run Only)

Before first use, compile the Swift decoder binary:

bash ~/.claude/skills/qr-bridge/scripts/setup.sh

If setup was already run, the binary exists at ~/.claude/skills/qr-bridge/scripts/qr-decode. Skip setup if it exists.

Commands

1. DECODE - Extract QR code content from an image

Step 1: Check if binary exists

ls ~/.claude/skills/qr-bridge/scripts/qr-decode 2>/dev/null && echo "COMPILED" || echo "NEED_SETUP"

If NEED_SETUP, run:

swiftc ~/.claude/skills/qr-bridge/scripts/qr-decode.swift -o ~/.claude/skills/qr-bridge/scripts/qr-decode -O

Step 2: Run decoder (compiled binary - fast)

~/.claude/skills/qr-bridge/scripts/qr-decode "/path/to/image.png"

Step 3: If compiled binary fails, use interpreted mode (slower but always works)

swift ~/.claude/skills/qr-bridge/scripts/qr-decode.swift "/path/to/image.png"

Step 4: If CoreImage fails, try pyzbar fallback

python3 -c "
from pyzbar.pyzbar import decode
from PIL import Image
import json, sys
img = Image.open(sys.argv[1])
results = decode(img)
out = [{'message': r.data.decode(), 'symbology': r.type} for r in results]
print(json.dumps({'ok': bool(out), 'count': len(out), 'results': out}, indent=2))
" "/path/to/image.png"

Output format (JSON):

{
  "ok": true,
  "count": 1,
  "results": [
    {
      "message": "https://example.com/path",
      "symbology": "QRCode",
      "bounds": { "x": 0, "y": 0, "width": 200, "height": 200 }
    }
  ],
  "file": "/path/to/image.png",
  "error": null
}

2. TRACE - Follow redirect chains

After decoding a URL from a QR code (or given a URL directly), trace the full redirect chain:

curl -sIL -o /dev/null -w '%{url_effective}\n' --max-redirs 15 --connect-timeout 10 "URL_HERE" 2>&1

For the full chain with each hop, use:

curl -sIL --max-redirs 15 --connect-timeout 10 -w '\n--- FINAL: %{url_effective} (HTTP %{http_code}) ---\n' "URL_HERE" 2>&1

Parse the Location: headers from the output to build the chain:

1. https://short.link/abc        → 302
2. https://tracking.example.com  → 301
3. https://final-destination.com → 200

3. INSPECT - Detect gated destinations

After tracing, inspect the final URL for access gates. Check for these patterns:

WeChat/WeCom Gates (common in Chinese QR codes):

• Domain contains: weixin.qq.com, work.weixin.qq.com, mp.weixin.qq.com, open.weixin.qq.com
• Redirect to open.weixin.qq.com/connect/oauth2/authorize
• Response contains: 请在微信客户端打开, 请在企业微信客户端打开
• Response header logicret: -2 = article not found / deleted / unpublished
• User-Agent gating: returns different content for WeChat UA vs browser UA
• WeChat mini-program links: weixin://dl/business/?appid= — cannot be opened outside WeChat

App-Gated Links:

• Taobao: tb.cn, m.tb.cn — returns 200 with JS redirect to Taobao app. Look for tbopen:// scheme or s_status: STATUS_NORMAL header
• Douyin: v.douyin.com — 302 redirect to www.douyin.com, then 404 for invalid links. Valid links redirect to www.douyin.com/video/
• Xiaohongshu: xhslink.com — 307 → www.xiaohongshu.com. Look for snssdk:// or xhsdiscover:// deep-link schemes
• Alipay: ur.alipay.com — redirects to alipays:// scheme
• Response contains deep-link schemes: weixin://, alipays://, tbopen://, snssdk://, xhsdiscover://
• Meta refresh or JavaScript redirect to app store

Login Walls:

• HTTP 401 or 403 status
• Redirect to /login, /signin, /oauth/authorize
• Response contains login form elements

Content Validity Check (run AFTER gate detection):

• WeChat: header logicret value — -2 means content invalid/deleted
• Douyin: final destination is 404 = video removed or link expired
• Taobao: response body contains 对不起 or 宝贝不存在 = product delisted

Detection commands:

# Step 1: Check response headers for platform signals
curl -sI --max-redirs 10 --connect-timeout 10 "URL_HERE" 2>&1

# Step 2: Check with browser-like UA
curl -sL --max-redirs 10 --connect-timeout 10 \
  -H "User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15" \
  "URL_HERE" | head -c 5000

# Step 3: Check with WeChat UA (reveals WeChat-gated content)
curl -sL --max-redirs 10 --connect-timeout 10 \
  -H "User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 MicroMessenger/8.0.0" \
  "URL_HERE" | head -c 5000

# Step 4: Compare — if Step 2 and Step 3 return different content, the link is UA-gated

Header signals to check:

• logicret: -2 → WeChat article invalid
• s_status: STATUS_NORMAL → Taobao link active
• Location: containing app deep-link schemes → app-gated redirect

4. DIAGNOSE - Explain and suggest next steps

Based on decode + trace + inspect results, provide a structured diagnosis:

Output format:

## QR Bridge Diagnosis

**Source:** [image filename]
**Decoded:** [raw content from QR]
**Type:** [URL | Text | vCard | WiFi | other]

### Redirect Chain
1. [url] → [status]
2. [url] → [status]
3. [url] → [final status]

### Access Gate
- **Gate type:** [WeChat | WeCom | Login | App-only | None]
- **Why it fails:** [explanation in plain language]
- **What it needs:** [specific requirement]

### Next Steps
- [actionable suggestion 1]
- [actionable suggestion 2]

Common diagnoses to provide:

5. GENERATE - Create QR codes from text/URLs

python3 -c "
import qrcode, sys, os
data = sys.argv[1]
out = sys.argv[2] if len(sys.argv) > 2 else os.path.expanduser('~/Desktop/qr-output.png')
qr = qrcode.QRCode(version=None, error_correction=qrcode.constants.ERROR_CORRECT_H, box_size=10, border=4)
qr.add_data(data)
qr.make(fit=True)
img = qr.make_image(fill_color='black', back_color='white')
img.save(out)
print(f'QR code saved to: {out}')
print(f'Content: {data}')
print(f'Size: {img.size[0]}x{img.size[1]}px')
" "CONTENT_HERE" "/output/path.png"

If qrcode is not installed:

pip3 install "qrcode[pil]"

Full Workflow

When the user provides a QR code image, run the full pipeline automatically:

1. DECODE the image
2. If the decoded content is a URL:

a. TRACE the redirect chain b. INSPECT the final destination for gates c. DIAGNOSE with full report

1. If the decoded content is NOT a URL (plain text, WiFi config, vCard, etc.):

a. Present the content with type identification b. Skip trace/inspect

Always present results in the structured diagnosis format above.

Error Handling

Image cannot be read:

• Verify the file exists and path is correct
• Check format (PNG, JPEG, HEIC, TIFF supported)
• Suggest converting if format is unusual: sips -s format png input.webp --out converted.png

No QR code detected:

• Image may be too low resolution
• QR code may be partially obscured
• Suggest: crop to QR region, improve contrast, try a screenshot instead of photo
• Try pyzbar fallback (different algorithm may succeed)

Redirect fails (timeout/DNS):

• Short link service may be down
• Link may have expired
• Try again with longer timeout: --connect-timeout 30

Cannot determine gate type:

• Fetch page content and look for clues in HTML/JS
• Check response headers for X-Powered-By, Server, custom headers
• Report what IS known and suggest manual inspection

Notes

• This skill is macOS-native. CoreImage is the primary decoder (zero external dependencies).
• The Swift binary is compiled once and reused for speed (~10ms vs ~2s interpreted).
• For batch processing, loop the binary over multiple files.
• All output is designed to be actionable: never just say "it failed" -- explain WHY and WHAT TO DO.