---
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://<container-ip>: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:**
```bash
# 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](https://github.com/adom-inc/gallia) monorepo. Server code lives in `server/`, MCP wrapper in `server/mcp/server.js`, desktop app in `desktop/src-tauri/`.