windows-remote-desktop-connection-doctor
Diagnoses Windows App (Remote Desktop / AVD / W365 / direct PC) connection problems on macOS: transport selection (UDP Shortpath vs WebSocket), VPN/proxy interference, and stuck "Configuring remote PC..." dialogs
Install / Use
npx skills add daymade/claude-code-skills --skill windows-remote-desktop-connection-doctorInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of windows-remote-desktop-connection-doctor
windows-remote-desktop-connection-doctor scores 93/100 on our quality scale, 714th of 4,700 Development & Engineering skills we index (top 16%).
Its SKILL.md is 16 KB long, well organised into 34 sections with 12 code examples: a thorough specification that gives an agent plenty to work with.
With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so windows-remote-desktop-connection-doctor is actively maintained.
- Our last check on 2026-10-26 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
windows-remote-desktop-connection-doctor compared with similar skills
All 4 of these similar skills score higher than windows-remote-desktop-connection-doctor; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| windows-remote-desktop-connection-doctor (this skill)by daymade | 93 | 1.4k | 53d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install windows-remote-desktop-connection-doctor?
- Run
npx skills add daymade/claude-code-skills --skill windows-remote-desktop-connection-doctor. The install tabs above show the steps for each supported agent. - Which AI agents does windows-remote-desktop-connection-doctor work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is windows-remote-desktop-connection-doctor safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is windows-remote-desktop-connection-doctor still maintained?
- The repository was last updated about 2 months ago, so windows-remote-desktop-connection-doctor is actively maintained.
Skill content
View source on GitHubname: windows-remote-desktop-connection-doctor description: >- Diagnoses Windows App (Remote Desktop / AVD / W365 / direct PC) connection problems on macOS: transport selection (UDP Shortpath vs WebSocket), VPN/proxy interference, and stuck "Configuring remote PC..." dialogs. Use when a VDI connection is slow/stuck, transport shows WebSocket not UDP, or Windows App freezes at a progress dialog. Not for general network diagnosis (use debugging-network-issues or tunnel-doctor). allowed-tools: Read, Grep, Bash
Windows Remote Desktop Connection Doctor
Diagnose and fix Windows App (Microsoft Remote Desktop / AVD / WVD / W365 / direct PC) connection issues on macOS, with focus on transport protocol optimization and root-cause falsification.
Methodology base: the general evidence-driven diagnosis discipline lives in the debugging-network-issues skill. This skill is the Windows-App / AVD transport domain layer — it leans toward connection-quality optimization more than root-cause falsification, so the methodology overlap is lighter.
Background
Azure Virtual Desktop transport priority: UDP Shortpath > TCP > WebSocket. UDP Shortpath provides the best experience (lowest latency, supports UDP Multicast). When it fails, the client falls back to WebSocket over TCP 443 through the gateway, adding significant latency overhead.
Direct PC connections use plain RDP over TCP 3389 (usually TLS-wrapped). They have no Connection Info panel, no gateway reachability tests, and no transport optimization step. For direct PC, the dominant failure modes are:
- The remote PC is off or unreachable (network/firewall).
- The Windows App client has a stale or expired Microsoft work/school account that poisons the auth orchestration, leaving the connection stuck at "Configuring remote PC...".
- The remote PC rebooted (often Windows Update), and the client cannot recover cleanly.
This skill handles both scenarios.
Diagnostic Workflow
Step 1: Determine the Connection Type and Symptom
Before collecting evidence, identify which scenario you are diagnosing:
| Scenario | Key Characteristic | Primary Evidence Source | |---|---|---| | AVD/WVD/W365 | User connects to a cloud desktop through a workspace/gateway | Connection Info panel, gateway health checks, UDP Shortpath logs | | Direct PC | User connects to a named PC by hostname or IP (e.g., a home workstation) | RDP protocol probe, Windows App log auth chain, Windows-side reboot events |
For AVD/WVD/W365, ask the user to provide the Connection Info from Windows App (click the signal icon in the toolbar). Key fields to extract:
| Field | What It Tells |
|-------|--------------|
| Transport Protocol | Current transport: UDP, UDP Multicast, WebSocket, or TCP |
| Round-Trip Time (RTT) | End-to-end latency in ms |
| Available Bandwidth | Current bandwidth in Mbps |
| Gateway | The AVD gateway hostname and port |
| Service Region | Azure region code (e.g., SEAS = South East Asia) |
If Transport Protocol is UDP or UDP Multicast, the connection is optimal — no further diagnosis needed.
If Transport Protocol is WebSocket or TCP, proceed to Step 2.
For Direct PC, the Connection Info panel does not exist. Instead, first run the RDP protocol probe in Step 2E to prove the server is reachable, then analyze the Windows App log for auth poisoning or reconnect failures. If the progress dialog is stuck at "Configuring remote PC...", strongly suspect client-side identity issues (see Category E).
Step 2: Collect Network Evidence
Gather evidence in parallel — do NOT make assumptions. Run the following checks simultaneously:
2A: Network Interfaces and Routing
ifconfig | grep -E "^[a-z]|inet |utun"
netstat -rn | head -40
scutil --proxy
Look for:
- utun interfaces: Identify VPN/proxy TUN tunnels (ShadowRocket, Clash, Tailscale)
- Default route priority: Which interface handles default traffic
- Split routing:
0/1 + 128.0/1 → utunpattern means a VPN captures all traffic - System proxy: HTTP/HTTPS proxy enabled on localhost ports
2B: RDP Client Process and Connections
# Find the Windows App process (NOT "msrdc" — the new client uses "Windows" as process name)
ps aux | grep -i -E 'msrdc|Windows' | grep -v grep
# Check its network connections
lsof -i -n -P 2>/dev/null | grep -i "Windows" | head -20
# Check for UDP connections
lsof -i UDP -n -P 2>/dev/null | head -30
Key evidence to look for:
- Source IP
198.18.0.x: Traffic is being routed through ShadowRocket/proxy TUN tunnel - No UDP connections from Windows process: Shortpath not established
- Only TCP 443: Fallback to gateway WebSocket transport
2C: VPN/Proxy State
# Environment proxy variables
env | grep -i proxy
# System proxy via scutil
scutil --proxy
# ShadowRocket config API (if accessible on local network)
NO_PROXY="<local-ip>" curl -s --connect-timeout 5 "http://<local-ip>:8080/api/read"
2D: Tailscale State (if running)
tailscale status
tailscale netcheck
The netcheck output reveals NAT type (MappingVariesByDestIP), UDP support, and public IP — valuable even when Tailscale is not the problem.
2E: Independent RDP Server Health Check (Direct PC)
This step is critical for direct PC connections and useful for AVD/WVD/W365 as a falsification test: it proves the server-side RDP stack is alive without relying on the Windows App client or any credentials.
Use the bundled probe script:
python3 scripts/probe_rdp_server.py <host> [port]
Example:
python3 scripts/probe_rdp_server.py my-pc.local 3389
A successful probe reports RDP server <host>:<port> is reachable and healthy (RDP + TLS). and means the problem is client-side (auth, app state, proxy, or identity). A failed probe means the problem is server-side or network (PC off, firewall, port unreachable, TLS interception).
See references/direct_pc_and_auth_diagnostics.md for detailed interpretation of probe results.
Step 3: Analyze Windows App Logs
This is the most critical step. Windows App logs contain transport negotiation details that no network-level test can reveal.
Log location on macOS:
~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows App/
Files are named: com.microsoft.rdc.macos_v<version>_<date>_<time>.log
Important: Windows App log timestamps are UTC. The user's clock and Windows Event logs are usually local time. Convert all timestamps to a single timezone before building a timeline.
Per-session tracking: each connection attempt gets a unique activity GUID in braces. Aggregate events by GUID to understand the lifecycle of one attempt. See references/windows_app_log_analysis.md for the GUID aggregation technique and references/direct_pc_and_auth_diagnostics.md for the direct-PC failure signatures.
See references/windows_app_log_analysis.md for detailed log parsing guidance.
Quick Log Search
LOG_DIR=~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows\ App
# Find the most recent log
LATEST_LOG=$(ls -t "$LOG_DIR"/*.log 2>/dev/null | head -1)
# Search for transport-critical entries (filter out noise)
grep -i -E "STUN|TURN|VPN|Routed|Shortpath|FetchClient|clientoption|GATEWAY.*ERR|Certificate.*valid|InternetConnectivity|Passed URL" "$LATEST_LOG" | grep -v "BasicStateManagement\|DynVC\|dynvcstat\|asynctransport"
Key Log Patterns
| Log Pattern | Meaning |
|-------------|---------|
| Passed: InternetConnectivity | Health check completed successfully |
| TCP/IP Traffic Routed Through VPN: No/Yes | Client detected VPN routing for TCP |
| STUN/TURN Traffic Routed Through VPN: Yes | Client detected VPN routing for STUN/TURN |
| Passed URL: https://...wvd.microsoft.com/ Response Time: Nms | Gateway reachability confirmed |
| FetchClientOptions exception: Request timed out | Critical: Client cannot get transport options from gateway |
| Certificate validation failed | TLS interception or DNS poisoning detected |
| OnRDWebRTCRedirectorRpc rtcSession not handled | WebRTC session setup not handled by client |
| OneAuthError_InteractionRequired | A cached Microsoft account token cannot be refreshed silently |
| No valid refresh tokens available in the cache | No usable cached credentials for the auth request |
| credential completion has been canceled | The interactive sign-in prompt was canceled |
| GATEWAY(ERR): ... UserCancelled(8) | Auth orchestration failed because sign-in was canceled |
| RDP_WAN: Client connMonitor goto CMSTATE_DROPPED | Connection monitor detected a dropped session |
| Channel::StartWrite failed / GetBuffer failed | Transport is dead; client is writing to a closed socket |
| ParseUserData: No data of type 0xc09 | Non-fatal — server answered MCS Connect; proves TCP path works |
| IHAddMouseEventToPDU / IHAddMouseWheelEventToPDU | Session is alive and receiving input |
Compare Working vs Broken Logs
When possible, compare a log from when the connection worked (UDP) with the current log:
# Compare startup health check blocks
for f in "$LOG_DIR"/*.log; do
echo "=== $(basename "$f") ==="
grep -E "InternetConnectivity|Routed Through VPN|Passed URL|FetchClient" "$f" | head -10
echo ""
done
A working log will contain the full health check block (InternetConnectivity, VPN routing detection, gateway URL tests). A broken log may show these entries missing entirely, or show certificate/timeout errors instead.
Step 4: Determine Root Cause
Based on collected evidence, identify the root cause category:
Category A: VPN/Proxy Interference
Evidence: Windows App source IP is 198.18.0.x, STUN/TURN routed through VPN, no UDP connections.
Fix: Add DIRECT rules for AVD traffic in the proxy tool:
DOMAIN-SUFFIX,wvd.microsoft.com,DIRECT
DOMAIN-SUFFIX,microsoft.com,DIRECT
IP-CIDR,13.104.0.0/14,DIRECT
Verify: Temporarily disable VPN/proxy, reconnect VDI, check if transport changes to UDP.
Category B: ISP/Network UDP Restriction
Evidence: Even with all VPNs off, still WebSocket. No UDP connections. FetchClientOptions timeout.
Verify:
# Test STUN connectivity to a known server
python3 -c "
import socket, struct, os
header = struct.pack('!HHI', 0x0001, 0, 0x2112A442) + os.urandom(12)
for srv in [('stun.l.google.com', 19302), ('stun1.l.google.com', 19302)]:
try:
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
s.settimeout(3)
s.sendto(header, srv)
data, addr = s.recvfrom(1024)
print(f'STUN from {srv[0]}: OK')
s.close(); break
except: print(f'STUN from {srv[0]}: FAILED'); s.close()
"
Fix options:
- Try mobile hotspot (isolate home network from ISP)
- Check router NAT type (Full Cone NAT preferred)
- Enable UPnP on router
- Try IPv6 if available
- Contact ISP about UDP restrictions
Category C: Client Health Check Failure
Evidence: Log shows certificate validation errors at startup, health check block (InternetConnectivity, STUN/TURN detection) missing from log, FetchClientOptions timeout.
This means the client cannot complete its diagnostic/capability discovery, preventing Shortpath negotiation.
Possible causes:
- ISP HTTPS interception/MITM (especially in China)
- DNS poisoning returning incorrect IPs for Microsoft diagnostic endpoints
- Firewall blocking Microsoft telemetry endpoints
Fix options:
- Change DNS to 8.8.8.8 or 1.1.1.1 (bypass ISP DNS)
- Route Microsoft traffic through a clean proxy
- Check if ISP injects certificates
Category D: Server-Side Shortpath Not Enabled
Evidence: Log shows no STUN/TURN or Shortpath related entries at all (not even detect
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
