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

Adom Desktop

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

First-time setup? If the user hasn't installed the desktop app yet, see the Setup section below to walk them through downloading, installing, and connecting the app.

Quick check if desktop is connected:

adom-desktop ping

How It Works

Claude Code -> adom-desktop <command> -> Relay Server (HTTP :8766) -> WebSocket :8765 -> Adom Desktop App -> KiCad / Fusion 360 / Browser / Shell

The adom-desktop binary is a single Rust CLI that does everything:

• adom-desktop serve -- Start the relay server (WebSocket :8765 + HTTP API :8766)
• adom-desktop <command> '<json>' -- Send commands to the desktop app via the running relay

The relay server runs in the Docker container. The Adom Desktop app runs on the user's PC and connects via WebSocket.

Starting the Relay Server

The relay must be running before the desktop app can connect:

adom-desktop serve &

This starts:

• WebSocket server on 0.0.0.0:8765 (desktop app connects here)
• HTTP API on 127.0.0.1:8766 (CLI commands go here)

Check if it's running:

curl -sf http://127.0.0.1:8766/health

First-Time Setup (Install & Connect)

You are running on a Docker container. You have NO access to the user's desktop. Guide them step-by-step, ask questions, wait for answers, and verify each step.

Step 1: Check if already connected

adom-desktop ping

If this returns { "status": "connected" }, the desktop is already set up -- skip to "Verify the connection" below. If it errors, continue.

Step 2: Ensure the relay is running

curl -sf http://127.0.0.1:8766/health

If not running: adom-desktop serve &

Step 3: Ask what OS they use

Ask the user: "What operating system is your desktop/laptop? (Windows, Mac, or Linux)"

• Windows 10/11 -- proceed
• macOS / Linux -- "Support is coming soon. The desktop app currently only runs on Windows."

Step 4: Install & connect

Run adom-desktop setup_desktop to get the installer_url and server_config fields. Then present both options to the user — the Claude Code prompt (fastest) and the manual steps (if they don't have Claude Code/Desktop):

Option A: Automatic setup via Claude Code (recommended)

If you have Claude Code or Claude Desktop on your laptop, paste this prompt:

Install Adom Desktop and connect it to my cloud container. Download the installer from <installer_url>, run it silently, then write this JSON to %USERPROFILE%\.adom\config.json:

{"servers":[<server_config JSON>]}

Then launch "Adom Desktop" from the Start Menu.

(Replace <installer_url> and <server_config JSON> with the actual values from setup_desktop.)

Option B: Manual setup

1. Download the installer:
2. Run it and follow the prompts — the app installs to the Start Menu as "Adom Desktop"
3. Open Adom Desktop from the Start Menu
4. Paste this JSON into the text field that says "Paste server JSON to add ..." and press Enter:

   <server_config JSON>
   

5. The server will appear and auto-connect

Wait for the user to confirm they see a green dot next to the server name before proceeding.

Important: Each container has its own relay server. New containers need a new entry -- old entries from previous containers won't work.

Step 6: Verify the connection

adom-desktop ping
# Expected: { "echo": "pong", "roundTripMs": ..., "status": "connected" }

adom-desktop status
# Expected: one client with the user's hostname and capabilities

adom-desktop notify_user '{"title":"Hello from Docker!","body":"Your desktop is connected."}'

Tell the user what you see. If ping succeeds:

"Your desktop is connected! I can now send files to your machine, open browser windows for visual debugging, control KiCad and Fusion 360, take screenshots of your desktop, and send you notifications."

Step 7: Offer the demo

After a successful first-time setup, offer the interactive demo:

"Want to see a quick demo of everything I can do? It takes about 2 minutes and shows off notifications, screenshots, browser automation, and more — all live in a webview right here."

If yes → trigger the adom-desktop-demo skill.

Step 8: Optional -- Node.js for browser features

Ask: "Would you like to use the visual browser debugging feature? This opens Chrome windows on your desktop that I can control."

• Yes + Node.js installed -- "Great, the browser bridge auto-installs deps on first use."
• Yes + no Node.js -- "Download Node.js from https://nodejs.org (LTS), install it, then restart Adom Desktop."
• No -- skip, they can enable it later

Common connection issues

CLI Tool

adom-desktop <command> '<json-args>'

Examples:

adom-desktop ping
adom-desktop status
adom-desktop browser_open_window '{"sessionId":"dart2","url":"https://example.com"}'
adom-desktop browser_eval '{"sessionId":"dart2","expr":"document.title"}'
adom-desktop browser_screenshot '{"sessionId":"dart2"}'
adom-desktop browser_list_windows
adom-desktop browser_close_window '{"sessionId":"dart2"}'
adom-desktop notify_user '{"title":"Hello","body":"From Docker"}'
adom-desktop shell_execute '{"command":"echo hello"}'
adom-desktop pull_file '{"filePaths":["C:\\Users\\john\\Downloads\\image.png"],"saveTo":"/tmp"}'

Output: JSON to stdout. Screenshots save to /tmp/conduit-screenshots/ and return the file path.

Config location: The desktop app stores server config at ~/.adom/config.json (%USERPROFILE%\.adom\config.json). This is separate from the binary — config survives updates and reinstalls.

Available Commands

Connection Management

• ping -- 5s round-trip test. Use BEFORE browser/shell commands to verify the desktop connection is alive.
• status -- Check who's connected, their capabilities, desktop paths, and app installation status. The desktop.apps object shows:
  • kicad.installed / kicad.version / kicad.bridgeRunning
  • fusion360.installed / fusion360.running / fusion360.bridgeRunning / fusion360.addinInstalled / fusion360.addinConnected
  • browser.bridgeRunning
• kick_all -- Force-disconnect all WebSocket clients. Active Adom Desktop apps auto-reconnect within seconds.

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. Absolute paths are rejected.
  • Returns destinationPaths[] with the absolute path of every saved file.

• pull_file -- Pull files from the desktop to the container.

  • filePaths: array of absolute Windows paths on the desktop
  • saveTo: directory on the container to save files (default: /tmp)

Desktop Notifications

• notify_user -- Send a desktop notification with optional action buttons.
  • title, body, level (info/warning/error/emergency), actions (array of button labels)

KiCad Tools

• kicad_install_symbol -- Send a .kicad_sym file and install it as a 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
• 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

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

• fusion_launch -- Launch Fusion 360 and wait for it + AdomBridge add-in to be ready (~15-30s). Call this before any other Fusion command if status shows fusion360.running: false. Returns addinConnected: true when ready.

• fusion_import_step -- Import a STEP/STL/IGES file into Fusion 360

• fusion_open_lbr -- Open an EAGLE .lbr library file

• fusion_open_electronics -- Check if the Electronics workspace is active

• fusion_electron_run -- Execute any EAGLE command via Electron.run

• fusion_execute_text_command -- Low-level app.executeTextCommand() access

• fusion_export_lbr -- Export the open Electronics library as an EAGLE .scr script

• fusion_save_lbr -- Save the open Electronics library as a .flbr file

• fusion_close -- Close Fusion 360. Always call this when done with Fusion 360 commands to clean up.

Desktop Screenshots

Take screenshots of the user's desktop or individual windows. All screenshots use lossless PNG.

Always save screenshots to project-content/screenshots/.

Naming convention: desktop-<descriptive-name>-YYYY-MM-DD-HhMMam/pm.png

Workflow: Call desktop_list_windows first to get HWNDs, then desktop_screenshot_window with the HWND.

• desktop_list_windows -- List all visible windows (returns HWND, title, class name, position/size)
• desktop_screenshot_window -- Capture a specific window by HWND
• desktop_screenshot_screen -- Capture the entire desktop (all monitors)

Browser Automation (Puppeteer)

Multi-session Puppeteer -- each session gets its own Chrome window. Auto-starts on first command. Always pass sessionId on every command.

• browser_open_window -- Open a Chrome window. Args: sessionId (required), url (required), freshProfile (optional)
• browser_close_window -- Close a session's Chrome window. Args: sessionId
• browser_list_windows -- List all open sessions with URL, title, active status
• browser_navigate -- Navigate to a new URL. Args: sessionId, url
• browser_screenshot -- Capture screenshot, auto-resized to <=1568px. Args: sessionId, maxWidth, fullPage
• browser_eval -- Evaluate JS in the page context. Args: sessionId, expr
• browser_errors -- Collected console/page errors. Args: sessionId, clear (default true)
• browser_reload -- Reload the page. Args: sessionId
• browser_status -- All sessions with URLs and error counts
• browser_close -- Close ALL sessions
• browser_wait -- Wait for content to settle. Args: ms
• browser_alert_window -- Flash the Windows taskbar orange. Always call after updating a pup window. Args: sessionId
• browser_focus_window -- Bring a session's window to foreground. Args: sessionId

Shell

• shell_execute -- Run a shell command on the desktop. Returns {pending: true, requestId} when the approval dialog shows. Poll with get_deferred_result for the output after the user approves.
• shell_kill_all -- Kill all running shell commands and deny pending approvals.

Use where python / C:\Python3xx\python.exe for Python -- avoid python which may not be on PATH.

Detecting App Installation

After connecting, always run adom-desktop status to check what's installed. The desktop.apps object tells you exactly what the user has:

adom-desktop status
# Look at the desktop.apps field in the response

Handling "not installed" errors

When a command returns errorCode: "kicad_not_installed" or errorCode: "fusion_not_installed", guide the user through installation:

KiCad not installed:

KiCad isn't installed on your desktop. Would you like to install it? Download from: https://www.kicad.org/download/ It's free and open source. Install the latest stable version (9.x recommended). Let me know when the install is done and I'll verify the connection.

After install, have them restart Adom Desktop (so the KiCad bridge re-detects).

Fusion 360 not installed:

Fusion 360 isn't installed on your desktop. Would you like to install it? Download from: https://www.autodesk.com/products/fusion-360 It's free for personal/hobby use (requires an Autodesk account). Let me know when the install is done and I'll verify the connection.

After install, have them restart Adom Desktop, then run adom-desktop status to verify.

Handling "not running" errors

When errorCode: "fusion_not_running", launch it programmatically:

adom-desktop fusion_launch
# Waits ~15-30s for Fusion to start + add-in to connect
# Returns {"success": true, "addinConnected": true}

KiCad doesn't need to be running for most commands (the bridge launches it on demand).

Handling "add-in not installed" errors

When Fusion is running but addinInstalled: false or addinConnected: false:

The AdomBridge add-in needs to be installed in Fusion 360. I can install it for you — this lets me control Fusion remotely.

The add-in auto-installs when the Fusion bridge starts and Fusion is detected.

Troubleshooting

Check connection status

Use status to see connected clients. A healthy connection shows one client from the user's hostname with a recent lastPong timestamp.

Stale connections causing timeouts

Use kick_all to reset -- active Adom Desktop apps reconnect within seconds.

No desktop client connected

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

Relay not running

curl -sf http://127.0.0.1:8766/health
# If fails: adom-desktop serve &

Shell commands on Windows

shell_execute runs in cmd.exe. Prefer writing scripts via send_files then executing them. Use the full Python path.

Building from Source

cd cli && cargo build --release
# Binary at: cli/target/release/adom-desktop

Repo

github.com/adom-inc/adom-desktop