app
Reference bridge: KiCad
UnreviewedReference implementation of the KiCad bridge — multi-instance Python server, forward path via kicad-cli, reverse path via in-process plugin. Most complex of the three bundled bridges.
{
"schema_version": 1,
"type": "app",
"slug": "adom-desktop-kicad-bridge",
"title": "Reference bridge: KiCad",
"brief": "Reference implementation of the KiCad bridge — multi-instance Python server, forward path via kicad-cli, reverse path via in-process plugin. Most complex of the three bundled bridges.",
"version": "1.0.0",
"tags": [],
"license": "MIT",
"discovery_triggers": [
"kicad bridge",
"kicad bridge source",
"kicad_bridge_call",
"reverse bridge",
"in-process kicad plugin",
"kicad bridge architecture",
"pcbnew bridge",
"eeschema bridge",
"kicad plugin payload",
"adom_bridge.py",
"usercustomize.py kicad",
"multi-instance bridge",
"kicad bridge reference",
"fork the kicad bridge"
],
"discovery_pitch": "Reference implementation of the KiCad bridge — multi-instance Python server, forward path via kicad-cli, reverse path via in-process plugin (kicad_bridge_call). The most complex of the three bundled bridges; use as a deep-dive reference when authoring your own.",
"sample_prompts": [
{
"label": "Read kicad bridge source",
"prompt": "Download the kicad-bridge zip from the wiki and walk me through its server.py"
},
{
"label": "Add a new kicad verb",
"prompt": "Help me add a new kicad_get_layer_image verb to the in-process bridge plugin"
},
{
"label": "Understand reverse bridge",
"prompt": "Explain how kicad_bridge_call routes from cloud Docker into the running pcbnew.exe"
},
{
"label": "List kicad verbs",
"prompt": "adom-desktop bridge_list and show me the kicad verbs"
},
{
"label": "Try the watcher pip",
"prompt": "Enable project watch in Adom Desktop settings for a kicad project"
}
],
"install": {
"binary_name": "adom-desktop-kicad-bridge",
"install_dir": "",
"install_hint": "",
"version_cmd": ""
},
"readme": "# Reference bridge: KiCad\r\n\r\n## Source code + contributing (2026-05)\r\n\r\nThe 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.\r\n\r\n### Where the source lives\r\n\r\nThe 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.\r\n\r\nIn the meantime, the full source — code, history, contributing guide, license — is **mirrored on this wiki page**:\r\n\r\n| Download | What it is | How to use |\r\n|---|---|---|\r\n| [`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/` |\r\n| [`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` |\r\n\r\nNo GitHub account needed to download either — both URLs are public.\r\n\r\n### How to contribute\r\n\r\nWe accept community improvements. Most useful targets right now:\r\n\r\n- **KiCad 11 support** — when KiCad 11 ships, the `kicad_detect.py` discovery + the in-process bridge plugin both need updates. Fork-friendly.\r\n- **macOS / Linux ports** — bridge currently Windows-only; cross-platform PRs welcome.\r\n- **New verbs** — anything KiCad exposes via `pcbnew.*` / `kicad-cli` that you'd find useful.\r\n\r\nTwo contribution paths, depending on your access:\r\n\r\n**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.\r\n\r\n**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.\r\n\r\nSee `CONTRIBUTING.md` inside the tarball/bundle for the full PR + ship workflow.\r\n\r\n### How shipping works after merge\r\n\r\n1. Maintainer merges your PR into `main`\r\n2. Maintainer tags `v<X.Y.Z>` + runs `bash scripts/release-bridge.sh kicad` on their box\r\n3. New zip + manifest published to this wiki page (replaces current version)\r\n4. Every Adom Desktop install running v1.7.19+ auto-picks up your change within 4 hours OR immediately via `adom-desktop refresh_bridges`\r\n\r\nNo NSIS installer rebuild required. Your code reaches real users in ~30s after merge.\r\n\r\n### License\r\n\r\nMIT — see the `LICENSE` file in the tarball.\r\n\r\n---\r\n\r\n\r\nThe 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).\r\n\r\nIf 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.\r\n\r\n## Quick facts\r\n\r\n| | |\r\n|---|---|\r\n| Name | `kicad` |\r\n| Display | KiCad EDA |\r\n| Spawn kind | Python (`server.py`) |\r\n| Port | 8772 |\r\n| Verb prefix | `kicad_*` (23 verbs) |\r\n| Watcher | yes (`*.kicad_pcb`, `*.kicad_sch`, `*.kicad_pro`) |\r\n| Source zip | [`kicad-bridge-v0.8.2.zip`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-v0.8.2.zip) |\r\n| Manifest | [`kicad-bridge-manifest.json`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-manifest.json) |\r\n| User-facing skill | [`kicad-SKILL.md`](https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-SKILL.md) |\r\n\r\n## What it does\r\n\r\n- **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.\r\n- **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.\r\n- **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.\r\n\r\n## `bridge.json`\r\n\r\n```json\r\n{\r\n \"manifest_version\": 1,\r\n \"name\": \"kicad\",\r\n \"displayName\": \"KiCad EDA\",\r\n \"version\": \"0.8.2\",\r\n \"description\": \"Reverse bridge for KiCad — board/schematic introspection, lint via kicad-cli, plugin install, multi-instance probe, in-process DRC.\",\r\n \"homepage\": \"https://github.com/adom-inc/adom-desktop\",\r\n \"author\": \"Adom Inc.\",\r\n \"license\": \"MIT\",\r\n \"spawn\": {\r\n \"kind\": \"python\",\r\n \"entrypoint\": \"server.py\",\r\n \"port\": 8772,\r\n \"healthEndpoint\": \"http://127.0.0.1:8772/status\",\r\n \"stopMethod\": \"kill\",\r\n \"killImageName\": \"python.exe\"\r\n },\r\n \"verbPrefixes\": [\"kicad_\"],\r\n \"verbs\": [\r\n \"kicad_open_board\", \"kicad_open_schematic\", \"kicad_open_symbol_editor\",\r\n \"kicad_open_footprint_editor\", \"kicad_open_3d_viewer\",\r\n \"kicad_list_versions\",\r\n \"kicad_run_drc\", \"kicad_run_erc\",\r\n \"kicad_lint_board\", \"kicad_lint_schematic\", \"kicad_lint_library\",\r\n \"kicad_format_upgrade\",\r\n \"kicad_install_plugin\", \"kicad_install_symbol\", \"kicad_install_footprint\",\r\n \"kicad_bridge_status\", \"kicad_bridge_call\",\r\n \"kicad_open_editors\", \"kicad_window_info\", \"kicad_screenshot_all\",\r\n \"kicad_send_key\", \"kicad_click\", \"kicad_close\"\r\n ],\r\n \"dependencies\": { \"python\": \">=3.11\", \"kicad\": \">=10.0\" },\r\n \"category\": \"EDA\",\r\n \"tags\": [\"pcb\", \"schematic\", \"open-source\", \"kicad-10\", \"kicad-11-ready\"],\r\n \"watcher\": {\r\n \"supports\": true,\r\n \"displayName\": \"Project Watch\",\r\n \"description\": \"Monitors a KiCad project folder for file changes and syncs them to Docker.\",\r\n \"defaultGlobs\": [\"*.kicad_pcb\", \"*.kicad_sch\", \"*.kicad_pro\"],\r\n \"configKey\": \"project_watch\"\r\n }\r\n}\r\n```\r\n\r\nThe `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.\r\n\r\n## Architecture highlights\r\n\r\n```\r\nkicad/\r\n├── server.py ← HTTP entry point; routes /command to handlers/\r\n├── handlers/ ← One module per logical verb group\r\n│ ├── board_ops.py ← kicad_run_drc, kicad_lint_board, kicad_open_board, …\r\n│ ├── schematic_ops.py\r\n│ ├── library_ops.py\r\n│ ├── window_automation.py ← Win32 SendInput, PrintWindow, EnumWindows\r\n│ ├── bridge_call.py ← Reverse bridge dispatch into the in-process plugin\r\n│ └── …\r\n├── kicad_detect.py ← Find installed KiCad versions, exe paths, USER_SITE\r\n├── adom_library.py ← Symbol/footprint discovery in sym-lib-table.txt\r\n├── lib_table.py ← Add/remove rows in *-lib-table files\r\n├── plugin_install.py ← Copy adom_bridge.py into USER_SITE/usercustomize.py\r\n├── plugin_payload/\r\n│ └── adom_bridge.py ← Reverse-bridge plugin loaded INSIDE every KiCad GUI exe\r\n├── parsers/ ← .kicad_sym, .kicad_mod, .kicad_pcb tokenizers\r\n└── start.bat ← Windows launcher for local dev\r\n```\r\n\r\nThe 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.\r\n\r\n## Reverse-bridge example\r\n\r\n```bash\r\n# From cloud Docker: list every open KiCad GUI exe + which board it has loaded\r\nadom-desktop kicad_open_editors\r\n\r\n# Direct in-process call: ask the running pcbnew.exe what board it has open\r\nadom-desktop kicad_bridge_call '{\"method\":\"get_board_info\"}'\r\n\r\n# Run a DRC IN-PROCESS — no file write, no kicad-cli detour\r\nadom-desktop kicad_bridge_call '{\"method\":\"run_drc\",\"args\":{\"severity\":\"error\"}}'\r\n```\r\n\r\nThe bridge dispatches these to `adom_bridge.py` running inside pcbnew. The handler executes against the live `pcbnew.GetBoard()` and returns JSON over the websocket.\r\n\r\n## Reference: install the source locally to read\r\n\r\n```bash\r\n# Pull the zip (no auth needed — wiki static URL)\r\ncurl -L https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-desktop/kicad-bridge-v0.8.2.zip -o /tmp/kicad-bridge.zip\r\n\r\n# Extract\r\nmkdir -p /tmp/kicad-bridge && cd /tmp/kicad-bridge && python3 -c \"import zipfile; zipfile.ZipFile('/tmp/kicad-bridge.zip').extractall()\"\r\nls -la\r\n```\r\n\r\nYou'll see `server.py`, `bridge.json`, `handlers/`, `plugin_payload/`, etc. — fork the layout for your own bridge.\r\n\r\n## Related\r\n\r\n- **[Bridge SDK guide](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-bridges)** — `bridge.json` schema, packaging recipe, lifecycle\r\n- **[Puppeteer bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-puppeteer-bridge)** — simpler architecture, single-instance, Node + Chrome for Testing\r\n- **[Fusion 360 bridge reference](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop-fusion-bridge)** — passthrough-to-add-in pattern\r\n- **[adom-desktop main page](https://wiki-ufypy5dpx93o.adom.cloud/wiki/apps/adom-desktop)** — install the parent app first\r\n\r\n",
"author": {
"id": "695820315b5f1e4db2fcf602",
"name": "Kyle Bergstedt",
"email": "[email protected]"
},
"visibility": {
"public": true
},
"hero": null,
"metadata": {},
"created_at": "2026-05-28T05:28:43.294Z",
"updated_at": "2026-05-28T05:28:43.294Z",
"skills": []
}