Desktop Integration

draw.io Desktop Integration

Overview

This skill covers the integration between Claude Code (running on desktop) and the draw.io desktop application (Electron-based). It enables a seamless workflow where the AI generates/edits diagram XML and the user visually refines it in the desktop editor.

Platform Detection

OS Detection Logic

detect_platform() {
    local os="$(uname -s 2>/dev/null || echo unknown)"
    case "$os" in
        Darwin)                    echo "macos" ;;
        Linux)
            # Check if running in WSL
            if grep -qi microsoft /proc/version 2>/dev/null; then
                echo "wsl"
            else
                echo "linux"
            fi
            ;;
        MINGW*|MSYS*|CYGWIN*)     echo "windows" ;;
        *)
            # Fallback: check for Windows env vars
            if [[ -n "${USERPROFILE:-}" ]]; then
                echo "windows"
            else
                echo "unknown"
            fi
            ;;
    esac
}

draw.io Executable Locations

Detection Priority

1. Check DRAWIO_EDITOR_PATH environment variable (user override)
2. Check PATH with command -v drawio
3. Check platform-specific common paths
4. Check for MCP Tool Server (@drawio/mcp) as alternative opener
5. Fall back to browser (https://app.diagrams.net)

draw.io Desktop CLI Reference

The draw.io desktop app supports command-line operations:

Export Commands

# Export to SVG
drawio --export --format svg input.drawio -o output.svg

# Export to PNG with 2x scale (retina)
drawio --export --format png --scale 2 input.drawio -o output.png

# Export to PDF
drawio --export --format pdf input.drawio -o output.pdf

# Export with embedded diagram XML (re-editable)
drawio --export --format svg --embed-diagram input.drawio -o output.drawio.svg

# Export specific page (0-indexed)
drawio --export --format svg --page-index 2 input.drawio -o page3.svg

# Export with transparent background
drawio --export --format png --transparent input.drawio -o output.png

# Export with border padding
drawio --export --format png --border 10 input.drawio -o output.png

# Export cropped to content
drawio --export --format svg --crop input.drawio -o output.svg

# Export all pages
drawio --export --format png --all-pages input.drawio -o output.png

Headless Export (Linux CI/CD)

When no display is available (SSH, Docker, CI), use xvfb-run:

# Install xvfb
sudo apt-get install -y xvfb

# Export with virtual framebuffer
xvfb-run -a drawio --export --format svg input.drawio -o output.svg

# Batch export all diagrams
for f in docs/*.drawio; do
    xvfb-run -a drawio --export --format svg --embed-diagram "$f" \
        -o "${f%.drawio}.drawio.svg"
done

Version Check

drawio --version
# Example output: 24.7.17

Desktop Workflows

Workflow 1: AI Creates → User Refines

Claude Code                         draw.io Desktop
─────────────                       ───────────────
1. drawio:create --output arch.drawio
   ↓ writes XML file
2. drawio:open --file arch.drawio
   ↓ launches desktop app ──────→   3. User sees diagram
                                    4. User drags/resizes/adds
                                    5. User saves (Ctrl+S)
   ↓ detects file change
6. Read the updated XML
7. drawio:enrich --level 2 arch.drawio
   ↓ writes enriched XML ───────→   8. Desktop auto-reloads

Workflow 2: User Designs → AI Exports

draw.io Desktop                     Claude Code
───────────────                     ─────────────
1. User creates diagram visually
2. User saves as project.drawio
                                    3. drawio:analyze project.drawio
                                       → quality report
                                    4. drawio:export --format svg
                                       --embed-diagram
                                    5. drawio:embed --platform github

Workflow 3: Side-by-Side Editing

Claude Code (terminal)              draw.io Desktop (window)
──────────────────────              ────────────────────────
1. drawio:edit --add-vertex         Auto-reload shows new shape
   "Auth Service"
2. drawio:edit --connect-to         Auto-reload shows connection
   "auth-svc" "api-gw"
3. drawio:style --preset dark       Auto-reload shows dark theme

Workflow 4: WSL Integration

When running Claude Code in WSL but want to use Windows draw.io:

# Convert WSL path to Windows path
WINPATH=$(wslpath -w "$PWD/docs/architecture.drawio")

# Open in Windows draw.io
"/mnt/c/Program Files/draw.io/draw.io.exe" "$WINPATH" &

# Or use Windows file association
cmd.exe /C "start \"\" \"$WINPATH\"" 2>/dev/null

Installation Guides

macOS

# Homebrew (recommended)
brew install --cask drawio

# Verify
/Applications/draw.io.app/Contents/MacOS/draw.io --version

Ubuntu/Debian

# Snap (auto-updates)
sudo snap install drawio

# Or .deb package
DRAWIO_VERSION="24.7.17"
wget "https://github.com/jgraph/drawio-desktop/releases/download/v${DRAWIO_VERSION}/drawio-amd64-${DRAWIO_VERSION}.deb"
sudo dpkg -i "drawio-amd64-${DRAWIO_VERSION}.deb"
sudo apt-get install -f  # fix dependencies if needed

# Verify
drawio --version

Fedora/RHEL

# Snap
sudo dnf install snapd
sudo snap install drawio

# Or Flatpak
flatpak install flathub com.jgraph.drawio.desktop

Windows

# Winget (recommended)
winget install JGraph.Draw

# Chocolatey
choco install drawio

# Verify
& "$env:LOCALAPPDATA\Programs\draw.io\draw.io.exe" --version

Arch Linux

# AUR
yay -S drawio-desktop-bin

MCP + Desktop Combined Setup

For the richest desktop experience, combine the MCP Tool Server with desktop app:

Claude Code (.mcp.json)

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["@drawio/mcp"],
      "env": {
        "DRAWIO_EDITOR_PATH": "/usr/bin/drawio"
      }
    }
  }
}

The MCP Tool Server's open_diagram tool will use the configured editor path.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "drawio-app": {
      "url": "https://mcp.draw.io/mcp"
    },
    "drawio-tool": {
      "command": "npx",
      "args": ["@drawio/mcp"]
    }
  }
}

File Watching

Native File Watching with fswatch (macOS)

fswatch -o docs/architecture.drawio | while read _; do
    echo "[$(date '+%H:%M:%S')] Diagram changed — re-analyzing..."
    # Trigger re-analysis or export
done

inotifywait (Linux)

inotifywait -m -e modify docs/architecture.drawio | while read _; do
    echo "[$(date '+%H:%M:%S')] Diagram changed"
done

PowerShell (Windows)

$watcher = New-Object System.IO.FileSystemWatcher
$watcher.Path = "docs"
$watcher.Filter = "*.drawio"
$watcher.EnableRaisingEvents = $true
Register-ObjectEvent $watcher Changed -Action {
    Write-Host "Diagram changed at $(Get-Date -Format 'HH:mm:ss')"
}

Auto-Reload Behavior

The draw.io desktop app monitors open files for external changes:

• Default: Prompts the user when an external change is detected
• Setting: Extras → Edit Configuration → add "autoSave": true for auto-reload
• draw.io config file (.drawio.json in user home):

{
  "autoSave": true,
  "autoSaveDelay": 500
}

This enables the workflow where Claude Code edits XML → desktop app auto-reloads.

Environment Variables

Troubleshooting

"Cannot open display" (Linux)

# Check display
echo $DISPLAY
# If empty, set it
export DISPLAY=:0

# For Wayland
echo $WAYLAND_DISPLAY

# For headless export without display
xvfb-run -a drawio --export --format svg input.drawio -o output.svg

"draw.io crashes on open" (Linux Snap)

# Snap needs connected interfaces
snap connections drawio
# If missing:
sudo snap connect drawio:removable-media

File permissions (macOS)

# If macOS blocks the app
xattr -cr /Applications/draw.io.app
# Or allow in System Preferences → Security & Privacy

WSL cannot open Windows apps

# Ensure interop is enabled
cat /proc/sys/fs/binfmt_misc/WSLInterop
# If missing, add to /etc/wsl.conf:
# [interop]
# enabled = true