{
  "schema_version": 1,
  "type": "app",
  "slug": "adom-desktop-kicad-bridge",
  "title": "Adom Desktop - KiCad Bridge",
  "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.15",
  "tags": [
    "kicad",
    "pcb",
    "schematic",
    "eda",
    "bridge",
    "adom-desktop"
  ],
  "license": "MIT",
  "discovery_triggers": [
    "kicad bridge",
    "open my pcb",
    "open my pcb design",
    "open my board in kicad",
    "open my schematic",
    "open my circuit board",
    "design a circuit board",
    "edit my pcb",
    "edit my schematic",
    "open a kicad board",
    "open a kicad project",
    "run drc",
    "run drc on my board",
    "run erc on my schematic",
    "check my board for errors",
    "export gerbers",
    "export gerber files",
    "export gerbers for jlcpcb",
    "make gerbers for my pcb",
    "export a step file from my board",
    "export bom",
    "export a bom from my schematic",
    "show my board in 3d",
    "open the 3d viewer",
    "view my pcb in 3d",
    "open kicad",
    "launch kicad",
    "install kicad",
    "upgrade kicad",
    "is kicad installed",
    "what kicad versions do i have",
    "install a kicad symbol",
    "install a footprint in kicad",
    "add a library to kicad",
    "open the symbol editor",
    "open the footprint editor",
    "screenshot kicad",
    "take a screenshot of my board",
    "place a footprint",
    "open a kicad_pcb file",
    "open a kicad_sch file"
  ],
  "discovery_pitch": "Drive KiCad on the user's desktop: open boards/schematics/symbols/footprints, run DRC/ERC, export gerbers/STEP/BOM, view in 3D. First run `adom-desktop bridge_list` to confirm the kicad bridge is installed; if so, drive its `kicad_*` verbs (kicad_describe lists them, kicad_readiness checks KiCad is present). If this container lacks the skill, run `adom-wiki pkg install adom/adom-desktop-kicad-bridge` or `adom-desktop sync_skills`.",
  "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 **`maintainers@adom.inc`**. 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": {
    "name": "Kyle Bergstedt",
    "email": "kyle@adom.inc"
  },
  "visibility": "public",
  "hero": {
    "type": "image",
    "path": "adom-desktop-kicad-bridge-hero-v4.png"
  },
  "metadata": {},
  "created_at": "2026-05-28T05:28:43.294Z",
  "updated_at": "2026-06-30T14:50:47.663Z",
  "skills": [],
  "author_name": "John Lauer",
  "source_visibility": "public",
  "description": "Skills for your container so your AI knows how to drive the KiCad bridge. The bridge runtime itself is the release zip — Adom Desktop loads that.",
  "dependencies": {
    "adom/adom-desktop": "^1.9.0"
  },
  "scripts": {
    "install": "./install.sh",
    "uninstall": "./uninstall.sh"
  },
  "files": [
    "README.md",
    "SKILL.md",
    "package.json",
    "install.sh",
    "uninstall.sh",
    "page.json",
    "skills/kicad-interaction/SKILL.md",
    "skills/kicad-3d-models/SKILL.md",
    "skills/kicad-tour/SKILL.md",
    "skills/kicad-tour/tour_runner.py",
    "skills/kicad-tour/hero/README.md",
    "skills/kicad-tour/hero/hero_builder.py"
  ],
  "org": "adom"
}