KiCad - the KiCad Bridge

@@ -1,445 +1,188 @@-# Adom KiCad Bridge Plugin--A Python-based bridge server that enables the Adom Desktop to control KiCad 9 on Windows. It receives commands over HTTP and translates them into KiCad operations — opening/closing editors, installing libraries, loading specific symbols and footprints, viewing 3D models, and running design rule checks.--## Architecture--```-Cloud (Claude Code)-  | WebSocket-Adom Relay Server (Docker)-  | WebSocket-Adom Desktop (Tauri, this machine)-  | HTTP POST to localhost:8772-KiCad Bridge Server (this plugin)-  | subprocess / Win32 API / file manipulation-KiCad 9 (project manager, symbol editor, footprint editor, 3D viewer, pcbnew, eeschema, kicad-cli)-```--The bridge server runs on `http://127.0.0.1:8772` and exposes two endpoints:--- **`GET /health`** — Returns KiCad detection info and server status-- **`POST /command`** — Accepts a JSON command and returns a JSON result--## Requirements--- Python 3.10+ (system Python or KiCad's bundled Python)-- KiCad 9.x installed on Windows-- No pip dependencies — uses Python stdlib only--## Quick Start--```bash-# From the project root-python plugins/kicad/server.py--# Or use the batch launcher (auto-finds Python)-plugins\kicad\start.bat-```--## Commands--All commands are sent as `POST /command` with JSON body `{"command": "<name>", "args": {...}}`.-All responses are JSON with `{"success": bool, "output": "...", ...}`.--### `install_library`--Installs a symbol or footprint library file into KiCad's user directory and registers it in the global library table.--**Symbol library:**--```json-{-  "command": "install_library",-  "args": {-    "libraryPath": "C:/path/to/library.kicad_sym",-    "libraryType": "symbol",-    "libraryName": "My Symbols",-    "description": "Custom symbol library"-  }-}-```--**Footprint library (with optional 3D model):**--```json-{-  "command": "install_library",-  "args": {-    "libraryPath": "C:/path/to/footprint.kicad_mod",-    "libraryType": "footprint",-    "libraryName": "My Footprints",-    "description": "Custom footprint library",-    "model3dPath": "C:/path/to/model.wrl"-  }-}-```--| Arg | Required | Description |-|-----|----------|-------------|-| `libraryPath` | yes | Absolute path to `.kicad_sym`, `.kicad_mod`, or `.pretty` directory |-| `libraryType` | yes | `"symbol"` or `"footprint"` |-| `libraryName` | no | Display name in KiCad (defaults to filename stem) |-| `description` | no | Description shown in KiCad's library manager |-| `model3dPath` | no | Path to 3D model file (footprint only; `.wrl`, `.step`, etc.) |--**How it works:**--- **Symbols**: Copies `.kicad_sym` to `~/Documents/KiCad/9.0/symbols/` and adds an entry to `sym-lib-table`-- **Footprints**: Creates a `.pretty` directory in `~/Documents/KiCad/9.0/footprints/`, copies the `.kicad_mod` inside, and adds an entry to `fp-lib-table`. Multiple footprints can be added to the same library.-- **3D models**: If `model3dPath` is provided, copies the model to `~/Documents/KiCad/9.0/3dmodels/<libraryName>.3dshapes/` and inserts a `(model ...)` reference into the footprint file-- Rejects duplicate library names (but allows adding footprints to existing libraries)-- **Important**: Libraries installed while KiCad is running won't be visible until KiCad restarts. Use `close_kicad` first if KiCad is already open.--### `open_symbol_editor`--Opens the KiCad Symbol Editor and optionally navigates to and loads a specific symbol. If KiCad is not running, it will be launched automatically.--```json-{-  "command": "open_symbol_editor",-  "args": {-    "symbolName": "ADOM_MCU",-    "libraryName": "Adom Test Symbols"-  }-}-```--| Arg | Required | Description |-|-----|----------|-------------|-| `symbolName` | no | Symbol to navigate to and load in the editor canvas |-| `libraryName` | no | Library containing the symbol (used as fallback search text) |--- Sends Win32 `WM_COMMAND` to the KiCad project manager to open the Symbol Editor-- If `symbolName` is provided, uses automated search + keyboard shortcuts to load the symbol-- If the requested symbol is already loaded, the editor is brought to the foreground-- Requires the library to be installed first via `install_library`-- Uses a PowerShell helper script (`navigate_symbol.ps1`) for Win32 UI automation--### `open_footprint_editor`--Opens the KiCad Footprint Editor and optionally navigates to and loads a specific footprint. If KiCad is not running, it will be launched automatically.--```json-{-  "command": "open_footprint_editor",-  "args": {-    "footprintName": "ADOM_R0805",-    "libraryName": "My Footprints"-  }-}-```--| Arg | Required | Description |-|-----|----------|-------------|-| `footprintName` | no | Footprint to navigate to and load in the editor canvas |-| `libraryName` | no | Library containing the footprint (used as fallback search text) |--- KiCad 9's launcher buttons use dynamically-assigned WM_COMMAND IDs that are unreliable, so this handler uses a mouse-click approach: it finds the "Footprint Editor" label in the project manager, locates the adjacent icon panel (~51x51 px), and clicks it-- If `footprintName` is provided, uses the same PowerShell navigation script as the Symbol Editor-- If the requested footprint is already loaded, the editor is brought to the foreground--### `open_3d_viewer`--Opens KiCad's 3D Viewer. Works from either the Footprint Editor or the PCB Editor (pcbnew).--```json-{-  "command": "open_3d_viewer",-  "args": {}-}-```--- **From Footprint Editor**: sends `WM_COMMAND 20500` (View > 3D Viewer)-- **From PCB Editor (pcbnew)**: sends `Alt+3` keystroke (View > 3D Viewer)-- Tries Footprint Editor first, then PCB Editor-- Requires a footprint/board to be loaded for the 3D model to display--### `close_symbol_editor`--Closes the KiCad Symbol Editor window. The KiCad project manager remains open.--```json-{-  "command": "close_symbol_editor",-  "args": {}-}-```--- Sends `WM_CLOSE` to the Symbol Editor window-- Idempotent: returns success even if the Symbol Editor is not open-- If the symbol has unsaved changes, KiCad will prompt the user to save--### `close_footprint_editor`--Closes the KiCad Footprint Editor window. Also closes the 3D Viewer if it was opened from the Footprint Editor. The KiCad project manager remains open.--```json-{-  "command": "close_footprint_editor",-  "args": {}-}-```--- Idempotent: returns success even if the Footprint Editor is not open--### `close_3d_viewer`--Closes the KiCad 3D Viewer window. The Footprint Editor remains open.--```json-{-  "command": "close_3d_viewer",-  "args": {}-}-```--- Idempotent: returns success even if the 3D Viewer is not open--### `close_kicad`--Closes all KiCad windows — editors and viewers first, then the project manager.--```json-{-  "command": "close_kicad",-  "args": {}-}-```--- Closes Symbol Editor, Footprint Editor, 3D Viewer, and other editor windows before the project manager-- Idempotent: returns success even if KiCad is not running-- If any editor has unsaved changes, KiCad will prompt the user to save-- Useful before `install_library` to ensure newly installed libraries are visible on next launch--### `open_board`--Opens a PCB file in KiCad's PCB editor (pcbnew).--```json-{-  "command": "open_board",-  "args": {-    "filePath": "C:/path/to/board.kicad_pcb"-  }-}-```--### `open_schematic`--Opens a schematic file in KiCad's schematic editor (eeschema).--```json-{-  "command": "open_schematic",-  "args": {-    "filePath": "C:/path/to/schematic.kicad_sch"-  }-}-```--### `run_drc`--Runs a Design Rule Check on a PCB file using `kicad-cli` and returns structured results.--```json-{-  "command": "run_drc",-  "args": {-    "filePath": "C:/path/to/board.kicad_pcb"-  }-}-```--Response includes parsed violations:--```json-{-  "success": true,-  "output": "DRC complete: 2 error(s), 1 warning(s), 3 total",-  "data": {-    "violations": [-      {-        "type": "clearance",-        "severity": "error",-        "description": "Clearance violation (0.15mm < 0.2mm)",-        "items": [{"description": "U1 pad 3", "pos": {"x": 100, "y": 50}}]-      }-    ],-    "summary": {"total": 3, "errors": 2, "warnings": 1}-  }-}-```--### `install_symbol` (preferred for symbols)--Decodes a base64-encoded `.kicad_sym` file and merges the symbol(s) into the single global **Adom** library (`Adom.kicad_sym`). All Adom-installed symbols live in one KiCad library. The library is created automatically on first use and registered in `sym-lib-table`. Subsequent installs add or update symbols in the same file.--```json-{-  "command": "install_symbol",-  "args": {-    "fileName": "BQ76952.kicad_sym",-    "fileContent": "<base64-encoded-.kicad_sym-file>",-    "symbolName": "BQ76952",-    "openEditor": true-  }-}-```--| Arg | Required | Description |-|-----|----------|-------------|-| `fileName` | yes | Original filename (`.kicad_sym` extension added if missing) |-| `fileContent` | yes | Base64-encoded `.kicad_sym` file content |-| `symbolName` | no | Specific symbol name to navigate to in the editor |-| `openEditor` | no | Whether to open Symbol Editor after install (default: `true`) |--**What it does internally:**-1. Decodes base64 `fileContent`-2. Extracts `(symbol ...)` blocks from the file-3. Merges into `Adom.kicad_sym` (creates the library + registers in `sym-lib-table` if needed)-4. If the symbol already exists in the Adom library, it is updated in place-5. If `openEditor` is true: opens Symbol Editor and navigates to the symbol--**No KiCad restart needed** -- the Adom library is pre-registered at bridge startup, so symbol updates are available immediately.--### `adom_library_status`--Query the current state of the Adom symbol library.--```json-{-  "command": "adom_library_status",-  "args": {}-}-```--Returns `{exists, registered, created, symbols}`. If the library is missing (e.g. user reset global libraries), calling this command will recreate it.--### `fix_keyboard`--Recovery command for when KiCad UI automation leaves modifier keys (Alt, Ctrl, Shift, Win) stuck.--```json-{-  "command": "fix_keyboard",-  "args": {}-}-```--Sends key-up events for all modifier keys and unlocks the foreground window lock. Safe to call even if nothing is stuck.--## Recommended Workflows--### Install and view a symbol (preferred -- single command)--```-1. install_symbol  (fileName, fileContent, symbolName, openEditor: true)-   -- Merges symbol into the global "Adom" library, opens Symbol Editor-   -- No KiCad restart needed (library is pre-registered at bridge startup)-```--### Install and view a symbol (multi-step alternative)--```-1. install_library     (install the .kicad_sym file as a separate library)-2. close_kicad         (ensure KiCad reloads library tables on next launch)-3. open_symbol_editor  (launches KiCad, opens Symbol Editor, loads the symbol)-Note: Creates a separate library per symbol. Prefer install_symbol which merges into the single Adom library.-```--### Install a footprint with 3D model and view it--```-1. install_library        (install .kicad_mod with model3dPath for .wrl/.step file)-2. close_kicad            (ensure KiCad reloads library tables on next launch)-3. open_footprint_editor  (launches KiCad, opens Footprint Editor, loads the footprint)-4. open_3d_viewer         (shows the 3D model of the loaded footprint)-```--### Iterate on a symbol design--```-1. install_symbol      (updated fileContent, same symbolName)-   -- Updates the symbol in the Adom library and reopens editor-   -- No restart needed since the library is already registered-```--### Iterate on a footprint design--```-1. install_library         (install/update the .kicad_mod file, optionally with 3D model)-2. close_kicad             (close everything to reload libraries)-3. open_footprint_editor   (open the updated footprint for review)-4. open_3d_viewer          (optionally check the 3D model)-5. close_3d_viewer         (close the viewer)-6. close_footprint_editor  (clean up when done)-```--### Full component review (symbol + footprint + 3D)--```-1. install_symbol          (symbol via single Adom library)-2. install_library         (footprint .kicad_mod with model3dPath)-3. close_kicad             (reload footprint library tables)-4. open_symbol_editor      (review symbol -- already in Adom library)-5. close_symbol_editor-6. open_footprint_editor   (review footprint)-7. open_3d_viewer          (review 3D model)-8. close_3d_viewer-9. close_footprint_editor-```--## File Structure--```-plugins/kicad/-├── server.py                  # HTTP server (entry point), ensures Adom library on startup-├── kicad_detect.py            # Auto-detects KiCad installation paths-├── lib_table.py               # S-expression parser for sym-lib-table / fp-lib-table-├── adom_library.py            # Single global Adom symbol library management-├── navigate_symbol.ps1        # PowerShell helper for editor UI automation-├── launch_editor.ps1          # PowerShell helper for launching KiCad editor windows-├── handlers/-│   ├── __init__.py-│   ├── open_files.py          # open_board, open_schematic-│   ├── open_symbol_editor.py  # Win32 automation to open Symbol Editor + load symbol-│   ├── open_footprint_editor.py # Win32 automation to open Footprint Editor + 3D Viewer-│   ├── close_windows.py       # close_symbol_editor, close_footprint_editor, close_3d_viewer, close_kicad-│   ├── install_library.py     # Library installation + table modification (symbols + footprints + 3D models)-│   ├── install_symbol.py      # Decode + merge symbol into Adom library + open editor-│   ├── run_drc.py             # DRC via kicad-cli with JSON parsing-│   └── fix_keyboard.py        # Release stuck modifier keys + unlock foreground-├── start.bat                  # Windows launcher script-└── README.md                  # This file-```--## Integration with Adom Desktop--The Tauri app's `commands.rs` forwards all KiCad commands (`"app": "kicad"`) to this bridge server via HTTP POST. The bridge server is **auto-started** when Adom Desktop launches and **auto-restarted** if it's not running when a command arrives. On startup, the bridge calls `ensure_adom_library()` to guarantee the global Adom symbol library exists and is registered in KiCad's `sym-lib-table`.--## Configuration--- **Port**: Default `8772`, override with `--port <N>`-- **KiCad detection**: Searches `C:/Program Files/KiCad/{9.0,8.0,7.0}/` automatically-- **Config dir**: `%APPDATA%/kicad/<version>/` (library tables live here)-- **User dir**: `~/Documents/KiCad/<version>/` (installed libraries are copied here)--## Contributing & forking — open source under the Adom org--**Adom KiCad Bridge Plugin** is **open source** under the **adom** org on the [Adom Wiki](https://wiki.adom.inc/adom/adom-desktop-kicad-bridge). The full source lives in this page's repo — open the **Files** tab, or `adompkg install adom/adom-desktop-kicad-bridge` and edit the package. Third-party developers are welcome to modify it and contribute back.--**Modify it**-- Get the source from the Files tab (or `adompkg install adom/adom-desktop-kicad-bridge`), make your changes, and rebuild.--**Contribute back to Adom — two paths**-1. **Pull request (preferred).** The wiki runs a PR-per-page flow: propose your change on this page and the maintainer reviews + merges it — no fork needed.-2. **Fork + breadcrumb.** Prefer your own fork or add-on? Publish it as your own wiki page, then drop a **breadcrumb on _this_ page** pointing at your fork so it's discoverable:-   - Read existing trails: `GET https://wiki.adom.inc/api/v1/pages/adom-desktop-kicad-bridge/breadcrumbs`-   - Attach a breadcrumb from your fork's page targeting this anchor (a short label + your slug).--   The breadcrumb leaves a **linked path back here**, so **Adom's AI can auto-discover your fork** and surface it to users — the trail is followable both ways. Your fork stays yours; the original stays discoverable.--## License--**MIT** — © 2026 Adom Industries Inc. Open source; see [LICENSE](LICENSE). Modify, fork, and redistribute freely.+# Reference bridge: KiCad
+
+## Source code + contributing (2026-05)
+
+The KiCad bridge moved out of `adom-inc/adom-desktop`'s monorepo into its own dedicated repo so the community can extend it without coordinating with Adom Desktop's release cycle.
+
+### Where the source lives
+
+The canonical repo is **[`adom-inc/adom-bridge-kicad`](https://github.com/adom-inc/adom-bridge-kicad)** on GitHub. It's private today and will go public after a review pass.
+
+In the meantime, the full source — code, history, contributing guide, license — is **mirrored on this wiki page**:
+
+| Download | What it is | How to use |
+|---|---|---|
+| [`adom-bridge-kicad-source.tar.gz`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop-kicad-bridge/adom-bridge-kicad-source.tar.gz) | Clean source tree, no `.git` directory. ~165 KB. | `tar xzf adom-bridge-kicad-source.tar.gz && cd adom-bridge-kicad/` |
+| [`adom-bridge-kicad.bundle`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop-kicad-bridge/adom-bridge-kicad.bundle) | Git bundle with full commit history. ~240 KB. | `git clone https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop-kicad-bridge/adom-bridge-kicad.bundle adom-bridge-kicad && cd adom-bridge-kicad && git log` |
+
+No GitHub account needed to download either — both URLs are public.
+
+### How to contribute
+
+We accept community improvements. Most useful targets right now:
+
+- **KiCad 11 support** — when KiCad 11 ships, the `kicad_detect.py` discovery + the in-process bridge plugin both need updates. Fork-friendly.
+- **macOS / Linux ports** — bridge currently Windows-only; cross-platform PRs welcome.
+- **New verbs** — anything KiCad exposes via `pcbnew.*` / `kicad-cli` that you'd find useful.
+
+Two contribution paths, depending on your access:
+
+**With a GitHub account (preferred):** wait until we make the repo public, then fork on GitHub and open a PR. We're aiming to flip the repo public in the next maintenance pass.
+
+**Without GitHub access (patch-by-email-style, available right now):** Clone the bundle, make your changes, generate a patch with `git format-patch origin/main..HEAD --stdout > my-changes.patch`, and email it to **`[email protected]`**. Adom maintainers will review and apply.
+
+See `CONTRIBUTING.md` inside the tarball/bundle for the full PR + ship workflow.
+
+### How shipping works after merge
+
+1. Maintainer merges your PR into `main`
+2. Maintainer tags `v<X.Y.Z>` + runs `bash scripts/release-bridge.sh kicad` on their box
+3. New zip + manifest published to this wiki page (replaces current version)
+4. Every Adom Desktop install running v1.7.19+ auto-picks up your change within 4 hours OR immediately via `adom-desktop refresh_bridges`
+
+No NSIS installer rebuild required. Your code reaches real users in ~30s after merge.
+
+### License
+
+MIT — see the `LICENSE` file in the tarball.
+
+---
+
+
+The KiCad bridge is one of three reference implementations bundled with Adom Desktop. It's the most complex of the three — a multi-instance Python server that runs alongside KiCad GUI processes and provides both a forward path (CLI → bridge → kicad-cli) and a reverse path (CLI → bridge → in-process Python plugin inside KiCad).
+
+If you're authoring a new third-party bridge, see the [bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges) first. Use this page for architectural reference once you've grasped the basics.
+
+## Quick facts
+
+| | |
+|---|---|
+| Name | `kicad` |
+| Display | KiCad EDA |
+| Spawn kind | Python (`server.py`) |
+| Port | 8772 |
+| Verb prefix | `kicad_*` (23 verbs) |
+| Watcher | yes (`*.kicad_pcb`, `*.kicad_sch`, `*.kicad_pro`) |
+| Source zip | [`kicad-bridge-v0.8.2.zip`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-v0.8.2.zip) |
+| Manifest | [`kicad-bridge-manifest.json`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-manifest.json) |
+| User-facing skill | [`kicad-SKILL.md`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-SKILL.md) |
+
+## What it does
+
+- **Forward path** (CLI → bridge → kicad-cli): board/schematic linting (`kicad_lint_board`, `kicad_lint_schematic`, `kicad_lint_library`), DRC/ERC (`kicad_run_drc`, `kicad_run_erc`), format upgrades, exports.
+- **Window automation** (CLI → bridge → Win32): launch editors (`kicad_open_board`, `kicad_open_schematic`, …), list open editors, capture screenshots of all KiCad windows, send keystrokes, click at coords.
+- **Reverse path** (CLI → bridge → in-process plugin inside KiCad): `kicad_bridge_call` invokes a Python handler running INSIDE the running KiCad GUI exe, with access to `pcbnew.*` / future `kipy`. This gives Docker-side Claude live introspection of the actually-open board without a round-trip through file exports.
+
+## `bridge.json`
+
+```json
+{
+  "manifest_version": 1,
+  "name": "kicad",
+  "displayName": "KiCad EDA",
+  "version": "0.8.2",
+  "description": "Reverse bridge for KiCad — board/schematic introspection, lint via kicad-cli, plugin install, multi-instance probe, in-process DRC.",
+  "homepage": "https://github.com/adom-inc/adom-desktop",
+  "author": "Adom Inc.",
+  "license": "MIT",
+  "spawn": {
+    "kind": "python",
+    "entrypoint": "server.py",
+    "port": 8772,
+    "healthEndpoint": "http://127.0.0.1:8772/status",
+    "stopMethod": "kill",
+    "killImageName": "python.exe"
+  },
+  "verbPrefixes": ["kicad_"],
+  "verbs": [
+    "kicad_open_board", "kicad_open_schematic", "kicad_open_symbol_editor",
+    "kicad_open_footprint_editor", "kicad_open_3d_viewer",
+    "kicad_list_versions",
+    "kicad_run_drc", "kicad_run_erc",
+    "kicad_lint_board", "kicad_lint_schematic", "kicad_lint_library",
+    "kicad_format_upgrade",
+    "kicad_install_plugin", "kicad_install_symbol", "kicad_install_footprint",
+    "kicad_bridge_status", "kicad_bridge_call",
+    "kicad_open_editors", "kicad_window_info", "kicad_screenshot_all",
+    "kicad_send_key", "kicad_click", "kicad_close"
+  ],
+  "dependencies": { "python": ">=3.11", "kicad": ">=10.0" },
+  "category": "EDA",
+  "tags": ["pcb", "schematic", "open-source", "kicad-10", "kicad-11-ready"],
+  "watcher": {
+    "supports": true,
+    "displayName": "Project Watch",
+    "description": "Monitors a KiCad project folder for file changes and syncs them to Docker.",
+    "defaultGlobs": ["*.kicad_pcb", "*.kicad_sch", "*.kicad_pro"],
+    "configKey": "project_watch"
+  }
+}
+```
+
+The `watcher` field declares that this bridge supports project-watching — the GUI renders a 👁 pip on the chip when watching is active. See the [bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges#bridgejson-schema) for the full schema.
+
+## Architecture highlights
+
+```
+kicad/
+├── server.py              ← HTTP entry point; routes /command to handlers/
+├── handlers/              ← One module per logical verb group
+│   ├── board_ops.py       ← kicad_run_drc, kicad_lint_board, kicad_open_board, …
+│   ├── schematic_ops.py
+│   ├── library_ops.py
+│   ├── window_automation.py  ← Win32 SendInput, PrintWindow, EnumWindows
+│   ├── bridge_call.py     ← Reverse bridge dispatch into the in-process plugin
+│   └── …
+├── kicad_detect.py        ← Find installed KiCad versions, exe paths, USER_SITE
+├── adom_library.py        ← Symbol/footprint discovery in sym-lib-table.txt
+├── lib_table.py           ← Add/remove rows in *-lib-table files
+├── plugin_install.py      ← Copy adom_bridge.py into USER_SITE/usercustomize.py
+├── plugin_payload/
+│   └── adom_bridge.py     ← Reverse-bridge plugin loaded INSIDE every KiCad GUI exe
+├── parsers/               ← .kicad_sym, .kicad_mod, .kicad_pcb tokenizers
+└── start.bat              ← Windows launcher for local dev
+```
+
+The reverse-bridge plugin (`plugin_payload/adom_bridge.py`) is what makes the kicad bridge special. KiCad's bundled Python interpreter overrides `site.USER_SITE` to `%USERPROFILE%\Documents\KiCad\10.0\3rdparty\Python311\site-packages\`, and the `usercustomize.py` import hook fires on every KiCad GUI exe start (`kicad.exe`, `pcbnew.exe`, `eeschema.exe`, `kicad-cli.exe`). Our plugin uses this hook to launch a tiny websocket client that connects to the bridge — turning every running KiCad into a remote-controllable instance.
+
+## Reverse-bridge example
+
+```bash
+# From cloud Docker: list every open KiCad GUI exe + which board it has loaded
+adom-desktop kicad_open_editors
+
+# Direct in-process call: ask the running pcbnew.exe what board it has open
+adom-desktop kicad_bridge_call '{"method":"get_board_info"}'
+
+# Run a DRC IN-PROCESS — no file write, no kicad-cli detour
+adom-desktop kicad_bridge_call '{"method":"run_drc","args":{"severity":"error"}}'
+```
+
+The bridge dispatches these to `adom_bridge.py` running inside pcbnew. The handler executes against the live `pcbnew.GetBoard()` and returns JSON over the websocket.
+
+## Reference: install the source locally to read
+
+```bash
+# Pull the zip (no auth needed — wiki static URL)
+curl -L https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-v0.8.2.zip -o /tmp/kicad-bridge.zip
+
+# Extract
+mkdir -p /tmp/kicad-bridge && cd /tmp/kicad-bridge && python3 -c "import zipfile; zipfile.ZipFile('/tmp/kicad-bridge.zip').extractall()"
+ls -la
+```
+
+You'll see `server.py`, `bridge.json`, `handlers/`, `plugin_payload/`, etc. — fork the layout for your own bridge.
+
+## Related
+
+- **[Bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges)** — `bridge.json` schema, packaging recipe, lifecycle
+- **[Puppeteer bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-puppeteer-bridge)** — simpler architecture, single-instance, Node + Chrome for Testing
+- **[Fusion 360 bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-fusion-bridge)** — passthrough-to-add-in pattern
+- **[adom-desktop main page](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop)** — install the parent app first+++![How the KiCad bridge works](arch.png)++![KiCad verbs Claude can call](verbs.png)++![What you can ask Claude to do](outcomes.png)

@@ -1,111 +1,193 @@ ----name: adom-desktop-kicad-public: true-description: "Launch and drive KiCad on the user's laptop (KiCad 7/8/9/10 supported, multi-version side-by-side) from this container via the adom-desktop CLI. Open schematics/boards/symbols/footprints, run DRC, install sym-lib-table / fp-lib-table libraries, show the 3D viewer, capture KiCad window screenshots, send keyboard shortcuts and click coordinates. Trigger words: kicad, open schematic, open board, open pcb, open symbol, open footprint, KiCad symbol editor, KiCad footprint editor, KiCad 3D viewer, run DRC, install KiCad library, sym-lib-table, fp-lib-table, KiCad screenshot, kicad_send_key, kicad_click, kicad_window_info, kicad_screenshot_all, close KiCad, kicad versions, kicad_list_versions, KiCad bridge."+name: adom-desktop-kicad-bridge+description: KiCad bridge for Adom Desktop — reference + verbs. --- -# adom-desktop — KiCad bridge--All commands dispatch to the KiCad Python bridge running alongside the desktop app. Invoke from this container via Bash:--```bash-adom-desktop kicad_<action> '<json_args>'-```--The leading `kicad_` routes the call to the KiCad plugin; the `<action>` names below are the plugin-side command names.--## Multi-version (KiCad 9 + KiCad 10 side-by-side)--Users can have multiple KiCad versions installed at the same time. The bridge auto-discovers everything under `C:/Program Files/KiCad/<version>/` and **defaults to the newest installed version** if you don't specify one.--```bash-# Discover what's installed (run this first if unsure)-adom-desktop kicad_list_versions '{}'-# → {"versions":[{"version":"10.0", "default":true, ...}, {"version":"9.0", ...}], "default":"10.0", "count":2}-```--Every `kicad_open_*` (and `install_*`, `run_drc`) command accepts an optional **`kicadVersion`** arg to pin a specific install:--```bash-# Open in KiCad 10 (newest — default if you omit kicadVersion)-adom-desktop kicad_open_board '{"filePath":"C:/designs/foo.kicad_pcb"}'--# Open in KiCad 9 explicitly (e.g. to check that an older project still works)-adom-desktop kicad_open_board '{"filePath":"C:/designs/foo.kicad_pcb","kicadVersion":"9.0"}'-```--If you pass a version that's not installed, the bridge returns a hint listing the installed versions. The success response includes `kicadVersionUsed` so you can confirm which install actually ran.--> **Note on libraries / config**: each KiCad version has its own `sym-lib-table` and `fp-lib-table` (in `%APPDATA%/kicad/<version>/`). `kicad_install_library` writes to the table of whichever version was selected — so if the user installs a library and then asks "open it in KiCad 9", you may need to install it under both versions.--## Commands--| CLI form | Action | Purpose | Key args |-|---|---|---|---|-| `kicad_list_versions` | `list_versions` | Enumerate every installed KiCad version with paths and which one is the default | — |-| `kicad_check_for_updates` | `check_for_updates` | Read-only: installed KiCad vs latest STABLE (from downloads.kicad.org / KiCad GitLab tags); flags when the install predates the modern IPC/kipy automation API and should be upgraded | — |-| `kicad_upgrade` | `upgrade` | Download the **official** KiCad installer from downloads.kicad.org and silent-install it (`/S`) — **not winget** (winget lags the real release). May raise a UAC prompt to approve | optional `version`, `force` |-| `kicad_open_schematic` | `open_schematic` | Open a `.kicad_sch` in the Schematic Editor | `filePath`, optional `kicadVersion` |-| `kicad_open_board` | `open_board` | Open a `.kicad_pcb` in the PCB Editor | `filePath`, optional `kicadVersion` |-| `kicad_open_symbol_editor` | `open_symbol_editor` | Launch Symbol Editor (optional: open specific library/symbol) | `libraryName`, `symbolName`, optional `kicadVersion` |-| `kicad_open_footprint_editor` | `open_footprint_editor` | Launch Footprint Editor | `libraryName`, `footprintName`, optional `kicadVersion` |-| `kicad_open_3d_viewer` | `open_3d_viewer` | Show the board (or footprint) in 3D viewer | `editor` ("auto"/"pcb"/"fp" — "auto" prefers the board when both editors are open, no need to close sub-editors), optional `kicadVersion` |-| `kicad_close_symbol_editor` | `close_symbol_editor` | Close Symbol Editor | — |-| `kicad_close_footprint_editor` | `close_footprint_editor` | Close Footprint Editor | — |-| `kicad_close_3d_viewer` | `close_3d_viewer` | Close 3D viewer | — |-| `kicad_close` | `close` | Close KiCad (all editors) | — |-| `kicad_window_info` | `window_info` | Enumerate open KiCad windows (HWND, title, bounds, editor type) | — |-| `kicad_install_library` | `install_library` | Register a `.kicad_sym` + `.pretty/` pair in sym-lib-table + fp-lib-table | `libraryPath`, `libraryType`, `libraryName`, optional `kicadVersion` |-| `kicad_install_symbol` | `install_symbol` | Add a single symbol to an existing library | `fileName`, `fileContent`, optional `kicadVersion` |-| `kicad_install_footprint` | `install_footprint` | Add a single footprint to an existing library | `library`, `footprint_path`, optional `kicadVersion` |-| `kicad_run_drc` | `run_drc` | Run DRC on the current board, return violations | `filePath`, optional `kicadVersion` |-| `kicad_fix_keyboard` | `fix_keyboard` | Workaround stuck-modifier bug after screen lock | — |-| `kicad_screenshot_all` | `screenshot_all` | Capture every open KiCad window (lossless PNGs) | — |-| `kicad_send_key` | `send_key` | Send a keystroke to a KiCad window — supports modifier combos ("alt+3", "ctrl+s", "ctrl+shift+s") | `hwnd`, `key` |-| `kicad_click` | `click` | Send a click at (x, y) in a KiCad window | `hwnd`, `x`, `y` |-| `kicad_adom_library_status` | `adom_library_status` | Report whether the Adom shared library is registered | — |--## Quick examples--```bash-# Open a schematic-adom-desktop kicad_open_schematic '{"path":"C:/designs/foo.kicad_sch"}'--# List open KiCad windows-adom-desktop kicad_window_info '{}'--# Screenshot every KiCad window-adom-desktop kicad_screenshot_all '{}'--# Run DRC-adom-desktop kicad_run_drc '{"board_path":"C:/designs/foo.kicad_pcb"}'--# Install a library pair-adom-desktop kicad_install_library '{-  "name":"my-lib",-  "sym_path":"C:/libs/my-lib.kicad_sym",-  "fp_path":"C:/libs/my-lib.pretty"-}'-```--## Error shape--Every failing response includes a `_hint` field with a human-readable next step — surface it to the user verbatim when a KiCad command fails.--## Bridge architecture (v1.8.31+) — you don't need to know any port--Earlier versions of the KiCad bridge listened on hardcoded port `8772`. **As of v1.8.31, bridges use OS-assigned ephemeral ports** — every spawn gets a new free port. You never need to know it.--- The CLI (`adom-desktop kicad_*`) automatically routes through adom-desktop's direct API (default port 47200 as of v1.8.33, with auto-fallback to 47201-47209 if 47200 is taken). adom-desktop then forwards to the bridge's actual runtime port.-- The bridge port is internal plumbing and can change every spawn. `bridge_list` reports it as `spawn.runtimePort` for debugging only — do NOT hardcode that anywhere.-- Why: this lets adom-desktop coexist with Hydrogen Desktop (which used to claim 8772 itself) and any other tool that grabs ports in the 8000 range. Side-by-side bridges from different apps no longer collide.-- The relay path (Docker → wss proxy → Windows GUI) is unchanged — same `adom-desktop kicad_*` verbs, same JSON shape.--If you ever find yourself wanting to talk directly to the KiCad bridge process: don't. Go through the verb dispatch. If the verb you need doesn't exist, request a feature in `adom-inc/adom-desktop`.--## Related--- `adom-desktop-discovery` (gallia) — ensures the CLI + relay are installed.-- `adom-desktop-fusion` — sibling bridge for Fusion 360.-- `adom-desktop-direct-api` — the direct API contract (port 47200 + 47201-47209 fallback, discovery file at `~/.adom/direct-api-port`).-- Repo: `adom-inc/adom-desktop/plugins/kicad/`+# Reference bridge: KiCad
+
+## Source code + contributing (2026-05)
+
+The KiCad bridge moved out of `adom-inc/adom-desktop`'s monorepo into its own dedicated repo so the community can extend it without coordinating with Adom Desktop's release cycle.
+
+### Where the source lives
+
+The canonical repo is **[`adom-inc/adom-bridge-kicad`](https://github.com/adom-inc/adom-bridge-kicad)** on GitHub. It's private today and will go public after a review pass.
+
+In the meantime, the full source — code, history, contributing guide, license — is **mirrored on this wiki page**:
+
+| Download | What it is | How to use |
+|---|---|---|
+| [`adom-bridge-kicad-source.tar.gz`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop-kicad-bridge/adom-bridge-kicad-source.tar.gz) | Clean source tree, no `.git` directory. ~165 KB. | `tar xzf adom-bridge-kicad-source.tar.gz && cd adom-bridge-kicad/` |
+| [`adom-bridge-kicad.bundle`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop-kicad-bridge/adom-bridge-kicad.bundle) | Git bundle with full commit history. ~240 KB. | `git clone https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop-kicad-bridge/adom-bridge-kicad.bundle adom-bridge-kicad && cd adom-bridge-kicad && git log` |
+
+No GitHub account needed to download either — both URLs are public.
+
+### How to contribute
+
+We accept community improvements. Most useful targets right now:
+
+- **KiCad 11 support** — when KiCad 11 ships, the `kicad_detect.py` discovery + the in-process bridge plugin both need updates. Fork-friendly.
+- **macOS / Linux ports** — bridge currently Windows-only; cross-platform PRs welcome.
+- **New verbs** — anything KiCad exposes via `pcbnew.*` / `kicad-cli` that you'd find useful.
+
+Two contribution paths, depending on your access:
+
+**With a GitHub account (preferred):** wait until we make the repo public, then fork on GitHub and open a PR. We're aiming to flip the repo public in the next maintenance pass.
+
+**Without GitHub access (patch-by-email-style, available right now):** Clone the bundle, make your changes, generate a patch with `git format-patch origin/main..HEAD --stdout > my-changes.patch`, and email it to **`[email protected]`**. Adom maintainers will review and apply.
+
+See `CONTRIBUTING.md` inside the tarball/bundle for the full PR + ship workflow.
+
+### How shipping works after merge
+
+1. Maintainer merges your PR into `main`
+2. Maintainer tags `v<X.Y.Z>` + runs `bash scripts/release-bridge.sh kicad` on their box
+3. New zip + manifest published to this wiki page (replaces current version)
+4. Every Adom Desktop install running v1.7.19+ auto-picks up your change within 4 hours OR immediately via `adom-desktop refresh_bridges`
+
+No NSIS installer rebuild required. Your code reaches real users in ~30s after merge.
+
+### License
+
+MIT — see the `LICENSE` file in the tarball.
+
+---
+
+
+The KiCad bridge is one of three reference implementations bundled with Adom Desktop. It's the most complex of the three — a multi-instance Python server that runs alongside KiCad GUI processes and provides both a forward path (CLI → bridge → kicad-cli) and a reverse path (CLI → bridge → in-process Python plugin inside KiCad).
+
+If you're authoring a new third-party bridge, see the [bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges) first. Use this page for architectural reference once you've grasped the basics.
+
+## Quick facts
+
+| | |
+|---|---|
+| Name | `kicad` |
+| Display | KiCad EDA |
+| Spawn kind | Python (`server.py`) |
+| Port | 8772 |
+| Verb prefix | `kicad_*` (23 verbs) |
+| Watcher | yes (`*.kicad_pcb`, `*.kicad_sch`, `*.kicad_pro`) |
+| Source zip | [`kicad-bridge-v0.8.2.zip`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-v0.8.2.zip) |
+| Manifest | [`kicad-bridge-manifest.json`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-manifest.json) |
+| User-facing skill | [`kicad-SKILL.md`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-SKILL.md) |
+
+## What it does
+
+- **Forward path** (CLI → bridge → kicad-cli): board/schematic linting (`kicad_lint_board`, `kicad_lint_schematic`, `kicad_lint_library`), DRC/ERC (`kicad_run_drc`, `kicad_run_erc`), format upgrades, exports.
+- **Window automation** (CLI → bridge → Win32): launch editors (`kicad_open_board`, `kicad_open_schematic`, …), list open editors, capture screenshots of all KiCad windows, send keystrokes, click at coords.
+- **Reverse path** (CLI → bridge → in-process plugin inside KiCad): `kicad_bridge_call` invokes a Python handler running INSIDE the running KiCad GUI exe, with access to `pcbnew.*` / future `kipy`. This gives Docker-side Claude live introspection of the actually-open board without a round-trip through file exports.
+
+## `bridge.json`
+
+```json
+{
+  "manifest_version": 1,
+  "name": "kicad",
+  "displayName": "KiCad EDA",
+  "version": "0.8.2",
+  "description": "Reverse bridge for KiCad — board/schematic introspection, lint via kicad-cli, plugin install, multi-instance probe, in-process DRC.",
+  "homepage": "https://github.com/adom-inc/adom-desktop",
+  "author": "Adom Inc.",
+  "license": "MIT",
+  "spawn": {
+    "kind": "python",
+    "entrypoint": "server.py",
+    "port": 8772,
+    "healthEndpoint": "http://127.0.0.1:8772/status",
+    "stopMethod": "kill",
+    "killImageName": "python.exe"
+  },
+  "verbPrefixes": ["kicad_"],
+  "verbs": [
+    "kicad_open_board", "kicad_open_schematic", "kicad_open_symbol_editor",
+    "kicad_open_footprint_editor", "kicad_open_3d_viewer",
+    "kicad_list_versions",
+    "kicad_run_drc", "kicad_run_erc",
+    "kicad_lint_board", "kicad_lint_schematic", "kicad_lint_library",
+    "kicad_format_upgrade",
+    "kicad_install_plugin", "kicad_install_symbol", "kicad_install_footprint",
+    "kicad_bridge_status", "kicad_bridge_call",
+    "kicad_open_editors", "kicad_window_info", "kicad_screenshot_all",
+    "kicad_send_key", "kicad_click", "kicad_close"
+  ],
+  "dependencies": { "python": ">=3.11", "kicad": ">=10.0" },
+  "category": "EDA",
+  "tags": ["pcb", "schematic", "open-source", "kicad-10", "kicad-11-ready"],
+  "watcher": {
+    "supports": true,
+    "displayName": "Project Watch",
+    "description": "Monitors a KiCad project folder for file changes and syncs them to Docker.",
+    "defaultGlobs": ["*.kicad_pcb", "*.kicad_sch", "*.kicad_pro"],
+    "configKey": "project_watch"
+  }
+}
+```
+
+The `watcher` field declares that this bridge supports project-watching — the GUI renders a 👁 pip on the chip when watching is active. See the [bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges#bridgejson-schema) for the full schema.
+
+## Architecture highlights
+
+```
+kicad/
+├── server.py              ← HTTP entry point; routes /command to handlers/
+├── handlers/              ← One module per logical verb group
+│   ├── board_ops.py       ← kicad_run_drc, kicad_lint_board, kicad_open_board, …
+│   ├── schematic_ops.py
+│   ├── library_ops.py
+│   ├── window_automation.py  ← Win32 SendInput, PrintWindow, EnumWindows
+│   ├── bridge_call.py     ← Reverse bridge dispatch into the in-process plugin
+│   └── …
+├── kicad_detect.py        ← Find installed KiCad versions, exe paths, USER_SITE
+├── adom_library.py        ← Symbol/footprint discovery in sym-lib-table.txt
+├── lib_table.py           ← Add/remove rows in *-lib-table files
+├── plugin_install.py      ← Copy adom_bridge.py into USER_SITE/usercustomize.py
+├── plugin_payload/
+│   └── adom_bridge.py     ← Reverse-bridge plugin loaded INSIDE every KiCad GUI exe
+├── parsers/               ← .kicad_sym, .kicad_mod, .kicad_pcb tokenizers
+└── start.bat              ← Windows launcher for local dev
+```
+
+The reverse-bridge plugin (`plugin_payload/adom_bridge.py`) is what makes the kicad bridge special. KiCad's bundled Python interpreter overrides `site.USER_SITE` to `%USERPROFILE%\Documents\KiCad\10.0\3rdparty\Python311\site-packages\`, and the `usercustomize.py` import hook fires on every KiCad GUI exe start (`kicad.exe`, `pcbnew.exe`, `eeschema.exe`, `kicad-cli.exe`). Our plugin uses this hook to launch a tiny websocket client that connects to the bridge — turning every running KiCad into a remote-controllable instance.
+
+## Reverse-bridge example
+
+```bash
+# From cloud Docker: list every open KiCad GUI exe + which board it has loaded
+adom-desktop kicad_open_editors
+
+# Direct in-process call: ask the running pcbnew.exe what board it has open
+adom-desktop kicad_bridge_call '{"method":"get_board_info"}'
+
+# Run a DRC IN-PROCESS — no file write, no kicad-cli detour
+adom-desktop kicad_bridge_call '{"method":"run_drc","args":{"severity":"error"}}'
+```
+
+The bridge dispatches these to `adom_bridge.py` running inside pcbnew. The handler executes against the live `pcbnew.GetBoard()` and returns JSON over the websocket.
+
+## Reference: install the source locally to read
+
+```bash
+# Pull the zip (no auth needed — wiki static URL)
+curl -L https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-v0.8.2.zip -o /tmp/kicad-bridge.zip
+
+# Extract
+mkdir -p /tmp/kicad-bridge && cd /tmp/kicad-bridge && python3 -c "import zipfile; zipfile.ZipFile('/tmp/kicad-bridge.zip').extractall()"
+ls -la
+```
+
+You'll see `server.py`, `bridge.json`, `handlers/`, `plugin_payload/`, etc. — fork the layout for your own bridge.
+
+## Related
+
+- **[Bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges)** — `bridge.json` schema, packaging recipe, lifecycle
+- **[Puppeteer bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-puppeteer-bridge)** — simpler architecture, single-instance, Node + Chrome for Testing
+- **[Fusion 360 bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-fusion-bridge)** — passthrough-to-add-in pattern
+- **[adom-desktop main page](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop)** — install the parent app first+++![How the KiCad bridge works](arch.png)++![KiCad verbs Claude can call](verbs.png)++![What you can ask Claude to do](outcomes.png)