---

name: gallia
description: Use when the user wants to send files to their desktop, control KiCad or Fusion 360, send desktop notifications, or troubleshoot the Conduit connection. Provides MCP tools for bridging the Docker container to the user's local machine.

Adom Conduit

Bridge between Claude Code (running in an Adom Docker container) and the user's desktop applications via WebSocket.

How It Works

Claude Code → MCP stdio → Conduit Server (HTTP :8766) → WebSocket :8765 → Desktop Conduit App → KiCad / Fusion 360 / Shell

The Conduit Server runs in the Docker container. The Adom Desktop Conduit app runs on the user's PC and connects via WebSocket. Claude Code interacts with the server through MCP tools.

Available MCP Tools

Connection Management

• conduit_status — Check who's connected, their capabilities, and connection freshness (lastPong timestamp). Use this to debug connection issues.
• conduit_kick_all — Force-disconnect all WebSocket clients. Active Desktop Conduit apps auto-reconnect within seconds. Use this to clean up stale connections causing timeouts.

File Transfer

• send_files — Send files from the Docker container to the desktop. Files are base64-encoded in transit.
  • filePaths: array of absolute paths on the server
  • targetApp: "kicad", "fusion360", or "general"
  • destinationFolder: relative subfolder only (e.g. "kicad/symbols", "fusion"). The desktop app controls the base directory (configured receive dir, or Downloads). Absolute paths are rejected — do not pass C:\... paths.
  • Returns destinationPaths[] with the absolute path of every saved file — use these for follow-up commands.

Desktop Notifications

• notify_user — Send a desktop notification with optional action buttons. Returns which button the user clicked.
  • title, body, level (info/warning/error/emergency), actions (button labels)

KiCad Tools

• kicad_install_symbol — Send a .kicad_sym file and install it as a library in one step (preferred over separate send_files + kicad_install_library)
• kicad_install_library — Install a symbol, footprint, or 3D model library
• kicad_open_board — Open a .kicad_pcb file
• kicad_open_schematic — Open a .kicad_sch file
• kicad_open_symbol_editor — Open the Symbol Editor, optionally navigating to a specific symbol
• kicad_open_footprint_editor — Open the Footprint Editor
• kicad_open_3d_viewer — Open the 3D Viewer
• kicad_run_drc — Run Design Rule Check on a board
• kicad_close — Close all KiCad windows
• kicad_close_symbol_editor, kicad_close_footprint_editor, kicad_close_3d_viewer

Fusion 360 Tools

Fusion 360 uses a two-tier architecture:

• External bridge (port 8773, auto-started): handles launch, detection, file opening
• AdomBridge add-in (port 8774, runs inside Fusion): required for export, design queries, Electronics/EAGLE commands

General

• fusion_import_step — Import a STEP/STL/IGES/etc file into Fusion 360 as a new document tab

Electronics / EAGLE (requires AdomBridge add-in)

These commands control Fusion 360's Electronics workspace (inherited from EAGLE). electron_run commands require an active Electronics editor (schematic, board, or library) — not just the "Electronics Design" overview.

• fusion_open_lbr — Open an EAGLE .lbr library file in the Electronics Library editor. Args: filePath (required), symbolName (navigate to symbol after open), verify (run EXPORT SCRIPT to confirm library loaded)
• fusion_open_electronics — Check if the Electronics workspace is active. Returns workspace name and whether electron_run commands will work.
• fusion_electron_run — Execute any EAGLE command via Electron.run. Examples: "EDIT R.sym", "WINDOW FIT", "DISPLAY", "EXPORT SCRIPT /path/out.scr"
• fusion_execute_text_command — Low-level app.executeTextCommand() access. Examples: "DebugCommands.ActiveWorkspace", "Document.newDesignFromLocal /path/file.lbr"
• fusion_export_lbr — Export the open Electronics library as an EAGLE .scr script file (useful for verification)
• fusion_save_lbr — Save the open Electronics library as a .flbr file on the desktop

Desktop Screenshots

Take screenshots of the user's remote desktop or individual windows. The screenshot is captured on the desktop machine, sent back through WebSocket as base64, and returned to you as an MCP image you can see directly.

Always save screenshots to project-content/screenshots/. Always pass savePath when calling screenshot tools.

Naming convention: desktop-<descriptive-name>-YYYY-MM-DD-HhMMam/pm.png. The prefix indicates the source (desktop for conduit screenshots, paste for Gallia Viewer paste utility). After the prefix, analyze the image content and choose a short, memorable descriptive name. Timestamp uses 12-hour format (e.g. desktop-kicad-footprint-editor-2026-02-24-7h43am.png, desktop-3d-viewer-tssop14-2026-02-24-11h05pm.png). This makes files easy to identify later without opening them.

After saving a screenshot, always send a desktop notification via notify_user with the full file path including the descriptive filename (e.g. "Saved: desktop-3d-viewer-tssop14-20260224070100.png"). The filename is valuable feedback since it reflects the image analysis.

Workflow: Call desktop_list_windows first to see what's open and get HWNDs, then call desktop_screenshot_window with the HWND to capture a specific window.

• desktop_list_windows — List all visible windows on the remote desktop (returns HWND, title, class name, position/size for each)
• desktop_screenshot_window — Capture a specific window by HWND. Returns PNG image directly to Claude (viewable). Always pass savePath to save to project-content/screenshots/.
• desktop_screenshot_screen — Capture the entire remote desktop (all monitors). Returns PNG image directly to Claude. Always pass savePath to save to project-content/screenshots/.

Data flow: Desktop captures → base64 PNG → WebSocket → Conduit Server (Docker) → MCP response → Claude sees the image. The MCP server also writes the PNG to the container filesystem at savePath.

Shell & USB

• shell_execute — Run a shell command on the desktop (user approves first). Use where python / C:\Python3xx\python.exe for Python — avoid python which may not be on PATH.
• usb_list — List USB devices on the desktop
• usb_mount / usb_unmount — Mount or unmount USB devices

Troubleshooting

Check connection status

Use conduit_status to see all connected clients. A healthy connection shows:

• One client from the user's hostname
• A recent lastPong timestamp (within the last 60 seconds)

Stale connections causing timeouts

Symptoms: send_files or KiCad commands time out after 30s. Multiple clients from the same hostname in conduit_status.

The server auto-prunes dead connections within ~60s via WebSocket protocol-level ping/pong. If you're hitting timeouts now, use conduit_kick_all to reset — active Desktop Conduit apps reconnect within seconds.

No desktop client connected

If conduit_status shows no clients:

1. Confirm the Adom Desktop Conduit app is running on the user's PC
2. Confirm it's pointed at the correct WebSocket URL (ws://:8765)
3. Check if the container's port 8765 is exposed and reachable

MCP server restart vs session restart

The MCP server (server/mcp/server.js) runs as a subprocess of Claude Code.

• To reload code changes (e.g. bug fixes to existing tools): kill the process — Claude Code will auto-respawn it. Trigger respawn by calling any conduit tool.
• To see newly added tools: requires a full Claude Code session restart. New tools added to server.js are registered at session start; killing and respawning the server mid-session does NOT add them to the visible tool list.

Shell commands on Windows

shell_execute runs in cmd.exe. JSON quoting in inline -d arguments is unreliable — prefer writing a .py or .json file via send_files then executing it. Use the full Python path (e.g. C:\Python314\python.exe) as python may not be on PATH.

Fusion 360 Electronics commands fail

If electron_run returns "Not in Electronics editor":

1. Call fusion_open_electronics to check current workspace
2. The user must have a schematic, board, or .lbr open and active — the "Electronics Design" overview does not count
3. Use fusion_open_lbr to open a library file which switches to the Electronics Library editor automatically

Process Management — CRITICAL

NEVER kill processes by raw PID or broad port matching. You can accidentally kill
code-server and crash the entire container, forcing the user to restart.

Safe service commands:

# Start all services (idempotent)
bash /home/adom/gallia/scripts/start-services.sh

# Stop specific services (safe targeted pkill)
pkill -f 'node.*services/wiki/server.js'     # wiki
pkill -f 'node.*viewer/server.js'             # viewer
pkill -f 'node.*viewer/mgmt-server.js'        # mgmt relay
pkill -f 'node.*server/server.js'             # conduit

NEVER do:

• kill <PID> without 100% certainty of what it is
• lsof -ti:PORT | xargs kill
• fuser -k PORT/tcp
• killall node

Services auto-start on container boot via /usr/local/bin/code-server-entrypoint.sh
which calls /home/adom/gallia/scripts/start-services.sh.

Repo Location

This skill is part of the gallia monorepo. Server code lives in server/, MCP wrapper in server/mcp/server.js, desktop app in desktop/src-tauri/.