# KiCad wishlist: automation without the foreground

The KiCad Bridge drives KiCad on the user's own Windows desktop while they keep working. KiCad offers no first-class way to do some of that in the background, so the bridge falls back to UI automation, posted keystrokes, real mouse input or the foreground. This page lists every such place, ranked worst first, with the KiCad feature that would remove each workaround. It is written to be posted to the KiCad forum as feature requests.

Measured on KiCad 10.0.5, Windows 11, October 2026. Every entry was checked against the KiCad 11 nightlies (the `master` API protos, 2026-10-04) and the KiCad GitLab issues, so it says what 11 already fixes and which existing issues ask for the same thing.

**Most of the API gaps close in KiCad 11.** `kicad-cli api-server` runs the IPC API headless (no windows at all), and 11 adds `OpenDocument`, `CloseDocument`, `CloseAllDocuments`, `SaveDocument`, `GetDocumentModifiedState`, `OpenLibraryItem`, library table editing with `ReloadLibrary`, `RefillZones` by zone id, `RunBoardJobExportRender`, and a schematic API. What stays open: focus when KiCad is on screen, a stable action API, live 3D viewer control, first-run dialogs, PCM, settings, live DRC, several instances on Windows, and errors reaching the API (entry 18).

We drive KiCad 10.0.5 on Windows from an AI agent: opening boards and editors, editing through the IPC API, taking screenshots and recording demos. The agent runs while the user keeps working, so every time KiCad needs the foreground or real input, the user loses their screen. Below is every place we have to fall back to UI automation, posted keystrokes, real mouse input or the foreground, ranked worst first, with the feature that would remove each workaround.

Severity: **real input** (the foreground and the user's mouse are taken), **KiCad takes the foreground** (we can only push it back afterwards), **UI automation** (posted window messages or UI Automation because no API exists), **API gap** (no foreground needed, but we must edit files or restart).

### 1. Clicking anything that has no command behind it (real input)
- **Want:** Press a canvas control or a toolbar button that is not in a menu, for example a toggle in the 3D viewer's toolbar.
- **KiCad today:** Nothing. Posted `WM_LBUTTONDOWN`/`UP` messages to the window are often ignored by the wx canvas.
- **Workaround:** Real mouse input with `SendInput`: KiCad must be the foreground window and the user's cursor moves. The user loses their screen for a few seconds.
- **Ask:** Every `TOOL_ACTION` invocable by name through the IPC API, aimed at a specific frame, so no action ever needs a click.

### 2. Opening the Footprint Editor when no PCB Editor is open (real input)
- **Want:** Open the Footprint Editor, optionally at `Library:Footprint`.
- **KiCad today:** No CLI argument and no API. The editor is launched from a host frame's menu (the PCB Editor or the Project Manager).
- **Workaround:** Fire the host frame's menu item, then UI Automation on the launcher. When neither works, the last resort is a real click on the launcher button, which needs the foreground.
- **Ask:** A command line argument and an IPC call that open the Symbol or Footprint Editor at a given library item.

### 3. Opening the Symbol Editor or Footprint Editor takes the user's focus (KiCad takes the foreground)
- **Want:** Open an editor without disturbing what the user is doing.
- **KiCad today:** Measured on KiCad 10.0.5 with the user's Notepad focused and maximized, our own push-back switched off, and the foreground sampled every 20 ms:

  | Action | What the user gets |
  | --- | --- |
  | Open a board (a new `pcbnew.exe`) | Nothing. The PCB Editor opens behind the user's window. |
  | Open the 3D Viewer (menu command in the PCB Editor) | Nothing. It opens behind. |
  | Open the Symbol Editor at `Device:R` | *Loading Symbol Libraries*, then the Symbol Editor, come to the front over the user's window and take keyboard focus. |
  | Open the Footprint Editor | The user's window stays on screen, but keyboard focus moves to an invisible KiCad window. The user's typing goes nowhere until they click back. |

  So KiCad can open frames quietly; these two editors are the ones that do not.

  Videos (full desktop, recorded live on that machine, with Hydrogen in front and a user typing to their AI):
  - [Today: the Symbol Editor jumps in front, and the user's typing lands in KiCad's search box](videos/kicad-today-symbol-editor.mp4)
  - [Wanted: a board opens behind the user and reports only on the taskbar (Adom badge and progress bar)](videos/kicad-wanted-background.mp4)

  The board opens behind *the foreground window*. When another window was in front of the user's app, the new PCB Editor landed between the two, so "behind" means behind whatever has focus.
- **Workaround:** Push the window back after it activates. The user still sees it jump forward and loses keyboard focus for a moment.
- **Ask:** Open the Symbol and Footprint Editors (and their progress dialogs) without activating, the way a board opens today, or a flag or IPC option that guarantees no activation.
- **KiCad 11 nightlies (checked 2026-10-04):** nothing changes this. No issue asks for it. Opt-in only: #17479 and #15015 ask for the opposite when a user opens an editor themselves. Related: #21464 (a read-only project warning that steals focus).

### 4. Startup dialogs that block automation (KiCad takes the foreground)
- **Want:** Start an editor on a fresh or headless machine and get straight to work.
- **KiCad today:** KiCad 10's *Welcome to KiCad* setup wizard appears in every editor start until `kicad.json` has `system.first_run_shown: true`, and cancelling it does not set that flag. On a machine without a usable GPU, *Could not use OpenGL, falling back to software rendering* appears at every start.
- **Workaround:** Find each dialog and press its button (`BM_CLICK`), or edit `kicad.json` before launch while no KiCad is running.
- **Ask:** Cancelling the wizard should count as answered, and a documented headless or automation flag that suppresses first-run and informational dialogs.
- **KiCad 11 nightlies (checked 2026-10-04):** unchanged. Related: #18698 (first-run update check prompt), #20386 (OpenGL warning at every start). The headless `kicad-cli api-server` shows no dialogs.

### 5. Save, lock and recovery prompts block closing (KiCad takes the foreground)
- **Want:** Close an editor the automation opened, or reopen a file.
- **KiCad today:** *Save changes?*, file-locked and auto-save-recovery prompts are modal and are the only way to answer.
- **Workaround:** `WM_CLOSE`, then find the modal dialog and press a button. A force kill loses unsaved work and leaves stale `.lck` files behind.
- **Ask:** An IPC call to close a document or frame with an explicit choice (save, discard, cancel), and to report which documents have unsaved changes.
- **KiCad 11 nightlies (checked 2026-10-04):** `CloseDocument`, `CloseAllDocuments {force}` and `GetDocumentModifiedState` (#19604), but the open and close commands are "currently only supported in CLI api-server mode", so a GUI editor still raises its prompts.

### 6. Opening the Symbol or Footprint Editor at one part (UI automation)
- **Want:** Show `Device:R` in the Symbol Editor.
- **KiCad today:** No way to pass a library item to a running editor.
- **Workaround:** Type the name into the library tree's search box with UI Automation (or `WM_SETTEXT`), post `VK_DOWN` and `VK_RETURN`, then poll the window title until it shows the part. If the tree pane is hidden, toggle it from the View menu first. On a slow machine the editor does not answer while it loads its libraries, and the attempt fails.
- **Ask:** An IPC call to load a given `Library:Item` into the Symbol or Footprint Editor.
- **KiCad 11 nightlies (checked 2026-10-04):** `OpenLibraryItem` (symbol and footprint editors). Not yet confirmed whether it opens the editor when it is closed, or whether it activates it.

### 7. Driving the 3D viewer (UI automation)
- **Want:** Rotate, zoom, pan, and frame one part (for example a connector) for a screenshot.
- **KiCad today:** No 3D viewer API at all.
- **Workaround:** Read the viewer's menu bar and post `WM_COMMAND` with the discovered ids (they differ between versions): Zoom, Rotate, Move Board, view presets. There is no way to set a camera pose or frame a reference designator.
- **Ask:** A 3D viewer API: set and read the camera, frame an item or a bounding box, and render a view to an image off-screen.
- **KiCad 11 nightlies (checked 2026-10-04):** `RunBoardJobExportRender` renders a still off-screen with camera rotation, pan and zoom. Controlling the open viewer is still not possible.

### 8. Any menu command (UI automation)
- **Want:** Zoom to Selection, View > Refresh, open the Plugin and Content Manager, and similar.
- **KiCad today:** These exist as actions but are not reachable through IPC.
- **Workaround:** Enumerate the native menu with `GetMenu`, match the label (labels vary by version and language), post `WM_COMMAND` to the right frame.
- **Ask:** Run any action by name through IPC (the same ask as the first entry).
- **KiCad 11 nightlies (checked 2026-10-04):** `RunAction {action}` already exists in 10.0, but its own comment says TOOL_ACTIONs are "specifically *not* an API" and are for prototyping only, and on master it is registered only in the board editor. The ask is a stable action API with per-frame targeting.

### 9. Libraries added while KiCad runs (UI automation)
- **Want:** Install a library, then open one of its parts.
- **KiCad today:** A running KiCad never re-reads `sym-lib-table` or `fp-lib-table`. The only refresh is the user pressing OK in Manage Libraries, or a restart.
- **Workaround:** Fire the library tree's refresh through the menu, or close and restart KiCad, which loses the user's window state unless it is saved and restored by hand.
- **Ask:** An IPC call to reload the library tables (and the library tree) in a running KiCad.
- **KiCad 11 nightlies (checked 2026-10-04):** `GetLibraryTable`, `AddLibraryTableEntry`, `UpdateLibraryTableEntry`, `DeleteLibraryTableEntry`, `ReloadLibrary`, `LoadAllLibraries`, `GetLibraryStatuses` (answers kicad-python #83).

### 10. Plugin and Content Manager (UI automation)
- **Want:** Add a repository and install or update a package.
- **KiCad today:** No CLI and no API. Repositories are read from `kicad.json` only at start.
- **Workaround:** Write `pcm.repositories` into `kicad.json`, extract packages into the third-party folder and edit `installed_packages.json` by hand, then ask the user to restart. The PCM dialog itself can only be opened through the menu.
- **Ask:** PCM commands in `kicad-cli` and the IPC API: list, add repository, install, update, remove, with an event when the library tables change.
- **KiCad 11 nightlies (checked 2026-10-04):** unchanged. Existing issues: #23491 (kicad-cli PCM), #24822.

### 11. Settings that KiCad overwrites on exit (UI automation)
- **Want:** Turn on the IPC API server, or change 3D viewer model visibility.
- **KiCad today:** Only through the preferences dialogs, or by editing the JSON files.
- **Workaround:** Edit `kicad_common.json` or `3d_viewer.json` while no KiCad is running, because a running KiCad writes its in-memory settings back on exit.
- **Ask:** Read and write settings through the API, applied live.
- **KiCad 11 nightlies (checked 2026-10-04):** unchanged. Related: kicad-python #71, #137.

### 12. Footprint reference and value fields (API gap)
- **Want:** Move or resize a footprint's reference text.
- **KiCad today:** `UpdateItems` on a `PCB_FIELD_T` answers `ISC_INVALID_TYPE` on 10.0.5.
- **Workaround:** Close the editor, edit the saved board file, reopen it.
- **Ask:** Field updates through `UpdateItems`.
- **KiCad 11 nightlies (checked 2026-10-04):** kicad-python #138 (field add and remove) is closed; not yet confirmed on a live board.

### 13. 3D model binding per footprint (corrected: already in the API)
- **Want:** Change a footprint's model path, offset, rotation or scale.
- **KiCad today:** Exposed since 10.0 (`Footprint3DModel`, kipy `Footprint.models`). An earlier version of this page said otherwise; that was our mistake.
- **Workaround:** None needed. The bridge still edits files here and should move to the API.

### 14. Zone refill (API gap)
- **Want:** Refill specific zones and know when it is done.
- **KiCad today:** `RefillZones` with a list of zone ids answers `AS_UNIMPLEMENTED`; an empty list (all zones) works but runs asynchronously with no completion signal.
- **Workaround:** Poll the board until its serialized form stops changing.
- **Ask:** Refill by id, and a completion event or a revision that changes only when the fill lands.
- **KiCad 11 nightlies (checked 2026-10-04):** `RefillZones` by zone id is implemented, and runs synchronously in headless sessions. In 10.0 the all-zones fill does signal completion: KiCad answers `AS_BUSY` until it lands.

### 15. DRC on the live board (API gap)
- **Want:** Check a proposed edit before committing it.
- **KiCad today:** No DRC over IPC.
- **Workaround:** Serialize the board, run `kicad-cli pcb drc` on a copy. The report stops at about 199 markers per violation type (499 for clearance), so large boards come back incomplete.
- **Ask:** DRC through the API on the live board, with complete results.
- **KiCad 11 nightlies (checked 2026-10-04):** still no DRC run over IPC (only `InjectDrcError`). Existing issues: kicad-python #14, #25285.

### 16. One API server for several editors (API gap)
- **Want:** Work with two boards open at once.
- **KiCad today:** One IPC server per machine; with two PCB Editors open, calls reach only one of them.
- **Workaround:** Detect the mismatch and refuse, or close the other editor.
- **Ask:** Address a specific document or frame in every IPC call.
- **KiCad 11 nightlies (checked 2026-10-04):** unchanged. Existing issues: #23994, #25503, kicad-python #67.

### 17. Schematics (API gap)
- **Want:** Edit a schematic live.
- **KiCad today:** The IPC API covers the board editor; the schematic editor has none.
- **Workaround:** Edit the `.kicad_sch` file, run ERC with `kicad-cli`, and reload.
- **Ask:** Schematic coverage in the IPC API.
- **KiCad 11 nightlies (checked 2026-10-04):** the schematic API is in (#2077), including symbols, labels, wires, netlist and ERC types.

### 18. Finding out that something went wrong (no API)
- **Want:** Know that an action failed, and why.
- **KiCad today:** In the GUI, `wxLogError` becomes a message box and nothing reaches stderr. A board that failed to parse showed *"Expecting thru_hole, smd, connect, or np_thru_hole"* in a dialog, while stderr for that launch (with `KICAD_ENABLE_WXTRACE=1`) was 0 bytes. There is no log file.
- **Workaround:** After every action, enumerate every top-level window KiCad owns plus a global sweep for `#32770` dialogs. Read each dialog's text; KiCad 10's TaskDialogs need UI Automation for that, and the read races the dialog closing. As the floor, screenshot each KiCad window together with its owned child popups. Dismiss the harmless ones (OpenGL notice, setup wizard) and report the rest.
- **Ask:** Errors and warnings that reach the API caller: the error text in the response of the call that caused it, or a message log readable over IPC (`GetMessages` since a cursor, or events as in kicad-python #38). A log file option would also help.
- **KiCad 11 nightlies (checked 2026-10-04):** no event, log or message channel in the API.

### Recording in the background
Recording KiCad in the background mostly works today. Windows Graphics Capture records a KiCad window that is covered by other windows, including the PCB canvas and the 3D viewer, so demo videos do not need KiCad in front. Three things break it:
- A minimized window does not paint, so it records nothing.
- On a machine with no GPU, the 3D viewer shows "Your OpenGL version is not supported" over a black canvas unless a software OpenGL is installed.
- Every entry above that needs the foreground or real input interrupts the recording and the user at the same moment.

So the problem is less about capture than about KiCad taking the foreground and needing real input. The first three asks below would let an automated KiCad session run, and be recorded, without the user ever seeing it.

### The short version (what is still missing after KiCad 11)
1. Open the Symbol and Footprint Editors (and their progress dialogs) without activating, as an opt-in, the way boards already open.
2. Errors and warnings that reach the API caller instead of only a modal dialog.
3. A stable action API with per-frame targeting (`RunAction` is explicitly not one).
4. Control of the open 3D Viewer (still renders are covered by `RunBoardJobExportRender`).
5. Suppress first-run and informational dialogs for unattended use; cancelling the setup wizard should count as answered.
6. PCM from the CLI and the API; settings read and write through the API.
7. DRC on the live board over IPC; several KiCad instances on Windows.