Trace Plugin for KiCad

Trace Plugin connects to KiCad 10 with live PCB editing and a separate saved-file schematic workflow.

Before connecting

Install KiCad 10, including its command-line tools, and obtain the companion through the Trace Plugin setup guide. Open a saved .kicad_pro project. Open its board in the PCB Editor before requesting live board edits.

Recorded live checks used KiCad 10.0.6. Companion distribution and platform acceptance are separate: Windows and macOS have automatic schematic save/reload paths in source; Linux requires manual schematic refresh and is not a verified packaged workflow here. See product availability.

Keep a separate project backup before the first AI edit. A read of the saved schematic cannot see unsaved changes still in the Schematic Editor.

Enable KiCad's API

1. In the main KiCad window, open Preferences → Preferences… on Windows or KiCad → Settings… on macOS.
2. Select Plugins.
3. Enable Enable KiCad API, then choose OK.
4. Save intended editor work, close any PCB or Schematic Editor windows opened before the API was enabled, and reopen them.
5. Return to Trace Plugin and choose Connect.

If KiCad is fully closed, the companion's setup screen can offer Turn it on and start KiCad instead. Review that choice: it changes KiCad's API preference and starts KiCad.

macOS permissions are separate

For automatic schematic save/reload, enable Trace Plugin under System Settings → Privacy & Security → Accessibility.

For editor screenshots, allow Trace Plugin under Screen & System Audio Recording in the same settings area; older macOS versions call this Screen Recording. Keep the editor open and non-minimized.

Accessibility does not grant screenshot permission. Screenshot permission does not grant automatic schematic save/reload.

Select and check the project

1. Launch Trace Plugin and choose Sign in with your browser. Finish sign-in and return.
2. Under Design tools, choose KiCad and complete the API setup if shown.
3. Select the project under Open projects, or use Open a project… to select its .kicad_pro.
4. Verify the chat header's project, document picker and connection message.
5. Save the intended schematic in KiCad, choose a supported model and Ask, and request a read-only summary of a named sheet.

Back to projects does not stop the reply. Switching projects while busy asks for Stop and switch or Cancel. The document picker waits while Trace works.

On macOS, the current automatic opener handles the PCB Editor through the Schematic Editor's menu. It does not generally open the Schematic Editor or raise either editor window. Open or bring the required editor forward yourself if needed.

Board edits: live PCB Editor

With the board open, supported component and copper edits are applied through KiCad's API. An individual item-edit batch can be undone with Ctrl+Z on Windows or ⌘Z on macOS; additional board-preparation changes can use another undo step.

Start with one named change in Agent, inspect the live board, then save it in KiCad. Verify pad/net links, placement and DRC. A finished chat turn is not a guarantee that every change shares one undo step or that the board has been saved.

KiCad 10's API does not safely expose all Board Setup operations. The companion uses project custom rules for supported net-class and minimum-rule changes; this is not full parity with KiCad's native net-class or constraint editor. Layer-count changes, teardrops and some renaming operations require the host's own controls.

Advanced layout and autorouting are present in source but their KiCad live-result paths have not been verified for this guide. Do not use a shared chat card as evidence that a run or its application succeeded.

Schematic edits: save first, reload afterward

KiCad 10's schematic path reads and parses the saved .kicad_sch, writes supported changes to that file, then attempts to reload the Schematic Editor. It is not a live schematic-editing API.

On supported Windows/macOS automation paths, the companion attempts to save unsaved editor work before preparing an edit and uses File → Revert afterward. On macOS this requires Accessibility permission. A save error can refuse the edit; a reload error can occur after the new file was written.

For your first schematic change:

1. Save in KiCad and confirm the intended sheet.
2. In Agent, request one explicit component or value change.
3. Read the tool result, including any “written, but did not reload” warning.
4. If necessary, use File → Revert in the Schematic Editor. Revert discards unsaved buffer changes; if you made further manual edits meanwhile, preserve them separately before proceeding.
5. Inspect the actual components, wires and labels, then run ERC and review connectivity before updating the PCB.

If the Schematic Editor was closed, it reads the new file when opened. A header refresh alone is not a substitute for reloading a stale editor buffer.

Undo and backups

Schematic reload clears KiCad's native undo history and can return to the root sheet. The companion attempts to keep previous schematic files in .trace/kicad/backups beside the project; only a limited number are retained. Verify that the backup exists before relying on it.

These are file backups, not Trace desktop Local History and not guaranteed whole-project rollback. Preserve the current files, inspect the candidate backup and restore only the intended sheet with the editor closed or safely reloaded. If the saved file and open buffer disagree, do not force-save either without checking which contains your intended work.

Ordinary edits aim to amend an existing drawing. Request a full redraw only for a named sheet you intend to replace; review hierarchy and page-overflow warnings as well as pin/net connections.

Install a reviewed part

Accepted or catalog parts are installed into project TraceParts symbol/footprint libraries. Generated parts can install automatically when Home → Components → Auto-approve components that pass every check is on. Eligibility requires drawing verification, no waived checks and an approving independent second look; an existing-name clash returns to manual review.

Turn the setting off if you want Accept & install, Request changes or Reject on every generated review card. Inspect automatic installs under Components. Undo removes an eligible library install, not copies already placed in the circuit; see the companion guide.

The first registration can require closing and reopening the KiCad project once. Follow the install result's notice before placing the part; later additions to already registered libraries normally appear without that first-registration step.

Check pin numbers, electrical types, package and units, pad geometry, footprint assignment and manufacturer dimensions. Installation is not circuit placement or PCB update. Generated 3D models must also be checked for alignment and dimensions; library custom-pad conversion still needs live-host verification.

KiCad stock libraries depend on your own installation. A named stock part may be absent; follow the acquisition/install notice rather than assuming every KiCad package includes it.

Simulate the saved schematic

Compatible companion builds include Trace's simulation engine and a separate Simulation window. Keep KiCad's command-line tools installed: the companion uses them to export the saved schematic hierarchy and pin/net information.

Save intended schematic work first. The companion cannot simulate an unsaved live schematic through KiCad 10's API; even an editor-style simulation request uses saved files and refuses detected unsaved changes. A disk request does not include unsaved edits.

Select a schematic in chat, inspect the experiment's sources, loads and model coverage, then request one run. Ask permits temporary experiments and result viewing; persistent benches and model installation/rebinding require Agent. A missing model or not evaluated result is not a design failure or a pass.

Use the job card's Open or the companion menu's Simulation runs to read saved evidence without starting a solver. Follow plugin simulation for analysis choices, source limits, currentness and recovery.

Exports and unsupported panels

Review Gerbers and drill outputs before fabrication. The fabrication ZIP excludes position and other assembly files, even when separate position-file generation is supported.

This companion has no native Workspaces, Layout Classification panel or Component Editor tab. Compatible builds do have AI Workflows settings and a separate Simulation window. Library Remediation audits Altium library formats; it is not a KiCad-library audit. Component review cards and supported classification tools in chat remain separate from desktop panels. Length matching is a report, not persistent group creation, automatic tuning or propagation-delay matching.

If something does not finish

• API is enabled but the editor is unreachable: reopen windows that predate enabling it, then reconnect.
• Board operations cannot find a document: open the correct board in PCB Editor and verify the companion's project/document selection.
• Schematic was written but looks unchanged: follow the safe File → Revert path above, rather than saving the stale buffer.
• Automatic reload fails: finish any KiCad dialog; on macOS check Accessibility. Unsupported platforms need manual refresh.
• Snapshot fails: check screenshot permission separately, and open the non-minimized editor.
• Part is missing from the chooser: follow the first-install reopen notice and verify the TraceParts libraries.

For an uncertain edit, inspect the saved files and host state before retrying. Preserve backups and contact hello@buildwithtrace.com with the companion/KiCad versions and safe error text.