KiCad - the KiCad Bridge

Written by Claude (Claude Code in Hydrogen) after a real session on 2026-09-01, driving this bridge cold as an agent that had never used it. John asked me to write up the experience. Everything below is from that one session; every claim was re-verified before filing.

The task, given in four steps: open KiCad; find a recent component Ray posted on the wiki and open it in a wv tab; import that component into KiCad and show it; then send a Cloud Library (lib_747xcc48ar) to KiCad. All four eventually worked. It took far longer than it should have, and almost every wrong turn traces to one thing.

Environment: ab 2.0.95 (2970c72e), kicad-bridge 0.9.271, plugin payload v0.9.2, KiCad 10.0.5 (10.0.6 available), Windows host AdomLapper, agent in a Linux container.

---

1. HEADLINE: adom-bridge help kicad shows 27 of 75 verbs, and the 48 it hides are the ones I needed

This is the root cause of nearly everything else in this report.

I did what the CLI tells you to do. adom-bridge --help says "adom-bridge help <namespace> for details", so I ran adom-bridge help kicad and treated the result as the catalog. It listed 27 verbs. kicad_describe reports 75. Diffed:

verbs in kicad_describe: 75
verbs in `help kicad`:   27
missing from help:       48

The 48 invisible verbs include every single one that would have solved my problems:

Verb I needed	What I did instead
kicad_launch	Hand-rolled launch_process with a hardcoded absolute path
kicad_show_symbol	kicad_open_symbol_editor, the lower-level verb
kicad_install_library_bundle	Hand-rolled clone → send_files → two install_library calls
kicad_plugin_diagnose	Guessed for ~40 minutes at why the plugin was dead
kicad_readiness	kicad_window_info + process_list
kicad_rescan_libraries	Full KiCad restart, twice
kicad_verb_times	Got killed by a 120s timeout because I couldn't predict a 55s verb

adom-bridge help kicad_launch → No help available for 'kicad_launch'. The verb dispatches perfectly when called. It is simply invisible to the CLI's own discovery surface.

Issue #19 ("kicad_open_editors doesn't cold-launch KiCad (no launch verb)") was closed by adding kicad_launch. That fix is undiscoverable to any agent that trusts help, so I reproduced #19's exact user experience with the fix already shipped and sitting on the machine.

Suggested fix: generate help <namespace> from the same catalog kicad_describe returns, so they cannot drift. If that's an ab-core limitation rather than a bridge one, the bridge's _hints should point at kicad_describe explicitly — right now nothing in the help output mentions that a fuller catalog exists.

2. The reverse-bridge plugin never bound, and the diagnostic contradicts its own log

kicad_bridge_status returned alive: 0, total: 0 for the entire session. Consequence: every symbol load fell back to keystroke navigation at ~55s per call (54.7s, 54.4s, 59.1s measured), each needing a focus grab on John's screen.

kicad_plugin_diagnose (once I found it) gives the real answer:

• pluginDirs[0].importedByKiCad: true, __pycache__ present — KiCad did import the loader.
• The loader then cannot import the payload, 25 log entries, all identical: attempt N in python.exe: payload not importable yet (No module named 'adom_bridge')
• Final line: gave up waiting for the payload to become importable in python.exe
• adom_bridge.py (144990 bytes) exists in both …/Documents/KiCad/10.0/3rdparty/Python311/site-packages and …/AppData/Roaming/Python/Python311/site-packages.

So: file present, loader imported, payload unimportable, loader gave up.

A possible lead: the payload is ~1.5 days older than the loader beside it (adom_bridge.py ageMin 6972 vs adom_bridge_boot.pth/.py ageMin 4864). Version skew between loader and payload would fit the symptom.

Bug in the diagnostic itself: verdict reads

"IMPORTED, no log yet: the loader arms a background thread and retries the payload import for ~60s. Re-run shortly."

while loaderLog in the same response holds 25 entries ending in "gave up". The verdict tells the agent to wait and retry something that has permanently failed. That verdict should key off the log's terminal state.

Note kicad_install_plugin reports already-current and is a no-op here, so the obvious remedy doesn't clear it.

3. kicad_close returns status: ok while closing nothing — and that poisons everything downstream

This cost me the single largest block of wasted time, and it is a clean causal chain:

1. Plugin is dead, so kicad_window_info reports editors: [].
2. kicad_close appears to drive off that same inventory. It found no editors, closed nothing, and returned status: ok, error: "".
3. A Symbol Editor (hwnd 9376012) survived the "close" — verified by hwnd identity: the same hwnd was present in desktop_list_windows before and after kicad_close, across a full project-manager relaunch.
4. That orphan still held the pre-install sym-lib-table. So every subsequent symbol load failed against a stale table.
5. The failure hint said: "check that the symbol really exists in this library."

That hint sent me the wrong way for a long time. I verified the .kicad_sym on disk, verified the sym-lib-table entry, verified the symbol name inside the file, re-ran kicad_install_plugin, and restarted KiCad twice. The actual fix was kicad_close_symbol_editor on one orphaned window.

Suggested fixes:

• kicad_close should enumerate windows by OS handle (desktop_list_windows sees them fine) rather than trusting a plugin inventory that can be empty, and should report what it actually closed: {closed: [...], survived: [...]}. Silently closing zero things must not be status: ok.
• When a load fails and an editor window is open whose lib-table mtime predates the most recent install_library, say that. "Symbol not found" and "your editor predates the install" need different hints.

4. open_symbol_editor leaves its search text in the Libraries filter — John thought the install had failed

After the ps-navigate path runs, the Libraries filter box still contains <library> <symbol> (e.g. UTA_Longhorn_Racing_Demo_Lib TLV9002QDGKRQ1). The tree therefore shows exactly one symbol.

John's words, looking at the result of a successful 3-part Cloud Library install:

"i'm not seeing the full library yet?"

Nothing was wrong — 3 symbols, 3 footprints, 3 models, both tables registered. He was looking at leftover filter text hiding the other two parts. This turns a correct install into an apparent failure, on screen, in front of the user.

Suggested fix: clear the filter box after navigation completes. The navigation is a means, not a state the user should inherit. If the residue is load-bearing for verification, clear it in a finally.

5. Two 10.0 installs both report default: true

kicad_list_versions returns three entries, two of which are indistinguishable by the field used to select them:

ver=10.0 default=True  base=C:/Users/john/AppData/Local/Programs/KiCad/10.0
ver=10.0 default=True  base=C:/Program Files/KiCad/10.0
ver=9.0  default=False base=C:/Program Files/KiCad/9.0

kicadVersion: "10.0" cannot disambiguate these, and two entries claiming default: true means "the default" is not well defined. This is a state the bridge itself can create: per this page's own skill, kicad_upgrade installs to %LOCALAPPDATA%\Programs\KiCad under /currentuser when unelevated, alongside a pre-existing all-users install.

Related contradiction in the same data: every version reports adomPluginInstalled: false while pluginAutoInstall.perVersion reports already-current for all three. Two fields on one response disagreeing about the same fact.

Suggested fix: make the version key unique (10.0-user / 10.0-machine, or expose installId), guarantee exactly one default: true, and reconcile adomPluginInstalled with pluginAutoInstall.

6. Cost of the missing rescan, from the outside

Issue #51 already covers this, so just a data point confirming it from a real session: installing libraries required a full KiCad restart to become visible, and I paid it twice. Combined with the 55s symbol loads and the dead plugin, "import this part and show me" ran about 25 minutes of wall clock for work that is a few file writes and a table entry.

7. Smaller things

• find_exe cannot locate kicad.exe at all. adom-bridge launch '{"path":"C:/Program Files/KiCad/10.0/bin/kicad.exe"}' → find_exe: could not locate … Searched: extra paths, PATH, Windows Start Menu. The file is demonstrably there (desktop_list_files lists kicad.exe and kicad-cli.exe in that exact directory), and launch_process with the same absolute path works every time. Both install paths fail identically. This is ab-core, not this bridge, but it's what pushed me to hand-roll a launch — and kicad_launch was hidden, so I had no good option. Happy to refile against ab if you'd rather.
• send_files with dest ending in .pretty creates a FILE, not a directory — I got a 5181-byte file named AL8860MP-13.pretty. Also ab-core. Worth noting because .pretty is a directory by definition in KiCad, so this path is a trap specifically for KiCad work. (kicad_install_library handles a bare .kicad_mod and wraps it into a proper .pretty itself — that behavior is good and undocumented.)
• A non-benign dialog was auto-clicked. kicad_plugin_diagnose returned _autoDialogs with action: "clicked-button", benign: false, title "RemoteApp security warning" — body text warning that a RemoteApp "could harm your local or remote computer." Auto-expiring KiCad's own OpenGL nag is one thing; auto-clicking an OS security prompt is another. Worth confirming that's intended and scoped.

---

The question John actually asked: were the skills there?

Mostly yes — and I should own my part in this. I did not read kicad-bridge/SKILL.md before starting. I went straight to adom-bridge help kicad because the CLI presents itself as self-describing. That was my mistake and I'd make a different call next time.

But the skill is genuinely good, and it already contains the answers to items 1, 2 and 6:

• kicad_launch is documented with the exact note I needed: "use kicad_launch for 'open KiCad'."
• The show_* family has a heading that says "START HERE for 'show me X'" — with the honest admission that it "was missing from this skill entirely until 2026-08-27."
• kicad_plugin_diagnose is listed as "Why is the reverse-bridge plugin not loading? One call, every artifact."
• kicad_install_library_bundle is right there as the one-call Cloud Library path.

So the documentation was correct and I was the one who didn't read it. The structural problem is that the CLI and the skill disagree, and the CLI is the surface an agent hits first. An agent that trusts help gets a 27-verb worldview that is missing the entire show_* family and every diagnostic. The skill can't fix that, because by the time you know to read the skill you've usually already gone down the wrong path.

Two things would have saved this whole session:

1. Make help complete (item 1). Single highest-value fix on this list by a wide margin.
2. Have the low-level verbs point up. When kicad_open_symbol_editor succeeds, its _hint could say "for user-facing 'show me' requests prefer kicad_show_symbol." When kicad_install_library succeeds, it could say "installing a wiki Cloud Library? kicad_install_library_bundle does symbols + footprints + 3D model rewiring in one call." I'd have found the better path mid-task instead of after.

One concrete consequence of not knowing #2: my hand-rolled kicad_install_library import left the symbol's Footprint field empty and no 3D model link, while adom-wiki library install (which uses the bundle path) wired all three properly — modelRefsRewritten: 3. Same part, two lanes, silently different quality. The bundle lane is better and nothing in the CLI surface says so.

What went well

Worth saying, since the above is all complaints:

• Every _hint I did receive was genuinely useful and written for an agent rather than a human skimming docs. The kicadUpdate block telling me 10.0.6 exists with "never update mid-design-work" is exactly right.
• The caller_identity_required refusal taught me the --ai-thread contract in one shot, with a correct fix in the error body.
• kicad_lint_library caught the pre-KiCad-7 format on Ray's symbol (20211014) before install and told me what would happen on first save. That's the kind of pre-flight that prevents a support thread.
• kicad_install_library accepting a bare .kicad_mod and building the .pretty itself is a genuinely nice affordance.
• adom-wiki library install is excellent — one command, correct result, honest restartNeeded warning, and it does not close a running KiCad.