Tunnel Doctor
Diagnose and fix conflicts between Tailscale and proxy/VPN tools on macOS — route hijacking, proxy env vars, SSH double-tunneling, and the ~60s DNS resolver stall.
Tailscale ping works but SSH hangs for 60 seconds, and you can't tell if it's DNS, the proxy, or the TUN fabric lying to you. This playbook isolates the real conflict and fixes it.
Who it's for: developers, remote-dev users, macOS power users
Example
"Tailscale ping works but git push hangs for a minute" → Claude identifies the proxy/DNS conflict and applies the right route or env-var fix
CLAUDE.md Template
New here? 3-minute setup guide → | Already set up? Copy the template below.
npx ccplaybooks add tunnel-doctor# Tunnel Doctor
Diagnose and fix conflicts when Tailscale coexists with proxy/VPN tools on macOS, with specific guidance for SSH access to WSL instances.
> **Methodology base:** the general diagnostic discipline this skill builds on — evidence over assumption, falsification over confirmation, layered isolation, counter-review — lives in the **debugging-network-issues** skill. This skill is the macOS Tailscale⨯proxy *domain* layer on top of it; reach for the base skill when the symptom is *not* a known Tailscale/proxy conflict.
## Five Conflict Layers
Proxy/VPN tools on macOS create conflicts at five independent layers. Layers 1-3 affect Tailscale connectivity; Layer 4 affects SSH git operations; Layer 5 affects VM/container runtimes:
| Layer | What breaks | What still works | Root cause |
|-------|-------------|------------------|------------|Get new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
Diagnose and fix conflicts between Tailscale and proxy/VPN tools on macOS — route hijacking, proxy env vars, SSH double-tunneling, and the ~60s DNS resolver stall.
What's Inside
The template covers:
- Five Conflict Layers
- Diagnostic Workflow
- SOP: Remote Development via Tailscale
- ── Health Checks ─────────────────────────────────────
- ── Route Warmup ──────────────────────────────────────
- ── Remote Development ────────────────────────────────
Quick Start
Step 1: Create a Project Folder
Make a dedicated folder for this workflow and open it in Claude Code.
Step 2: Download the Template
Click Download above to save the template, then drop it into your project as CLAUDE.md (or paste it into your existing one).
Step 3: Start Working
Tell Claude what you need in plain language — it will follow the template's workflow automatically. For example:
Tailscale ping works but git push hangs for a minute
Claude reads the template and runs the steps for you.