kicad-happy

⚡ kicad-happy

AI-powered design review for KiCad. Analyzes schematics, PCB layouts, and Gerbers. Catches real bugs before you order boards.

Works with Claude Code, OpenAI Codex, GitHub Copilot CLI, Google Antigravity, and opencode, as a GitHub Action for automated PR reviews, or as standalone Python scripts you can run anywhere.

These skills turn your AI coding agent into a full-fledged electronics design assistant that understands your KiCad projects at a deep level: parses schematics and PCB layouts into structured data, cross-references component values against datasheets, detects common design errors, and walks you through the full prototype-to-production workflow.

🔬 What it looks like in practice

Point your agent at a KiCad project and it does the rest — parses your schematic and PCB files, traces the nets, computes rail voltages from the feedback dividers it finds, and tells you what’s wrong before you spend money on boards.

“Analyze my KiCad project at hardware/rev2/”

Here’s a condensed example from an open-source robot controller board. The agent found all of this automatically:

It builds your power tree — tracing each regulator it recognises from input to load, computing output voltages from feedback dividers:

VBUS (USB-C / battery input, fused)
├── AP63357 buck (500kHz switching) → 5V
│   └── Feedback: R8/R9 ratio=0.155 → Vout=3.87V
│       Power dissipation: ~0.15W (85% efficiency assumed)
└── RT9080-3.3 LDO → 3.3V
    └── Decoupling: 16 caps, 10.8µF total

It identifies subcircuits — not just passives, but the functional blocks and how they connect:

It audits connectors for ESD protection — and flags the ones that are exposed:

ESD coverage: 19 connectors audited

  USB-C:     ESD clamp on D+/D-  ✓ (partial — 13 signal pins per ground ⚠️)
  Fuse F1:   2.5A motor input  ✓
  Fuse F2:   0.75A signal input  ✓
  ⚠️ 6-pin header:    no protection (exposed signals)
  ⚠️ Motor outputs:   no protection (exposed to back-EMF)
  ⚠️ Servo connectors: no protection (exposed signals)
  ⚠️ Sensor port:     no protection
  ... 19 of 19 connectors have coverage gaps

It validates your passive networks — computing actual circuit behavior from component values:

It suggests applicable certifications — based on what it detects in the design:

Suggested certifications:
  FCC Part 15 Subpart B (US) — unintentional radiator compliance
  CISPR 32 / CE EMC Directive (EU) — EMC compliance for EU market

It checks production readiness — BOM lock status, connector ground distribution, decoupling adequacy:

BOM lock: 0% — no MPNs assigned (prototype stage)
Decoupling: 5 rails, 34 caps total (132µF motor, 110µF logic, 10.8µF 3.3V)
Connector ground: USB-C has 13:1 signal-to-ground ratio (recommended ≤3:1)

For complete examples with all sections, see:

• Example 1: Robot controller — schematic + PCB + EMC + SPICE, 184 components
• Example 2: GNSS disciplined oscillator — full workflow including datasheet sync, 296 components, 10 power rails, Ethernet + USB + SMA

For the end-to-end walkthrough from S-expression parsing through signal detection and datasheet cross-referencing, see How It Works.

🚀 Install

Claude Code:

/plugin marketplace add aklofas/kicad-happy
/plugin install kicad-happy@kicad-happy

[!NOTE] /plugin update may not detect new versions due to a known Claude Code issue. To get the latest version, clear the cache and reinstall:

rm -rf ~/.claude/plugins/cache/kicad-happy ~/.claude/plugins/marketplaces/kicad-happy
/plugin marketplace add aklofas/kicad-happy
/plugin install kicad-happy@kicad-happy

OpenAI Codex:

Use Codex’s built-in skill installer first:

“Use $skill-installer to install the kicad-happy skills from https://github.com/aklofas/kicad-happy”

If you prefer a manual install, install the skills into ~/.codex/skills/.

Google Antigravity CLI (agy) / Gemini:

Install directly from GitHub as an Antigravity plugin:

agy plugin install https://github.com/aklofas/kicad-happy.git

Or from a local checkout:

git clone https://github.com/aklofas/kicad-happy.git
agy plugin install kicad-happy

Toggle when needed:

agy plugin disable kicad-happy   # Disable when not doing electronics review
agy plugin enable kicad-happy    # Enable when working on KiCad projects

See install-guidance.md for workspace-scope installs, slash commands, and upgrade notes.

opencode:

git clone https://github.com/aklofas/kicad-happy.git
cd kicad-happy
opencode

The repo ships .opencode/opencode.json, which opencode auto-discovers and uses to load all 11 skills from ./skills/. For global availability across all projects, see install-guidance.md.

git clone https://github.com/aklofas/kicad-happy.git
cd kicad-happy
mkdir -p ~/.claude/skills
for skill in kicad spice emc datasheets bom digikey mouser lcsc element14 jlcpcb pcbway; do
  ln -sf "$(pwd)/skills/$skill" ~/.claude/skills/$skill
done

git clone https://github.com/aklofas/kicad-happy.git
cd kicad-happy
mkdir -p ~/.codex/skills
for skill in kicad spice emc datasheets bom digikey mouser lcsc element14 jlcpcb pcbway; do
  ln -sf "$(pwd)/skills/$skill" ~/.codex/skills/$skill
done

git clone https://github.com/aklofas/kicad-happy.git
cd kicad-happy
New-Item -ItemType Directory -Force "$HOME\.codex\skills" | Out-Null
"kicad","spice","emc","datasheets","bom","digikey","mouser","lcsc","element14","jlcpcb","pcbway" | ForEach-Object {
  New-Item -ItemType SymbolicLink -Path "$HOME\.codex\skills\$_" -Target "$(Get-Location)\skills\$_" -Force | Out-Null
}

The analysis scripts are pure Python 3.10+ with zero required dependencies. No pip install, no Docker, no KiCad installation needed.

Release candidates

The stable install commands above always resolve to the latest stable release on main. When a release candidate is active, opt in by appending #<tag> to the marketplace ref:

Claude Code:

/plugin marketplace add aklofas/kicad-happy#vX.Y.Z-rc.N
/plugin install kicad-happy@kicad-happy

This pins to the RC tag. Stable users on the un-suffixed marketplace are unaffected. To switch back to stable, remove the marketplace and re-add it without the # suffix.

Codex / Gemini CLI / opencode: clone the repo and check out the RC tag before running the install above:

git clone https://github.com/aklofas/kicad-happy.git
cd kicad-happy
git checkout vX.Y.Z-rc.N
# then run the symlink install for your agent

⚙️ GitHub Action

Also available as a GitHub Action for automated PR reviews. Every push and PR that touches KiCad files gets a commit status check and a structured review comment — power tree, SPICE results, EMC risk, thermal analysis, and more. Optionally chain with Claude for AI-powered natural-language reviews.

See the GitHub Action setup guide for workflow examples, diff-based PR reviews, and AI-powered review configuration.

📦 Skills

🖐️ Ask about specific circuits

You don’t have to ask for a full design review — just point the agent at whatever you’re working on:

“Check the two capacitive touch buttons on my PCB for routing or placement issues”

“Is my boost converter loop area going to cause EMI problems?”

“Trace the enable chain for my power sequencing — is the order correct?”

“Are the differential pairs on my USB routed correctly?”

The agent runs the analysis scripts, then autonomously digs deeper — tracing nets, analyzing zone fills, calculating clearances, reading datasheets.

What the analysis covers

🔬 SPICE simulation

“Sweep my LC matching network and show me where it actually resonates vs where I designed it”

“What’s the actual phase margin on my opamp filter stage with this TL072?”

“Run SPICE on everything the analyzer detected and tell me what doesn’t look right”

The spice skill goes beyond static analysis. It automatically generates SPICE testbenches for detected subcircuits — RC/LC filters, voltage dividers, opamp stages, feedback networks, transistor switches, crystal oscillators — runs them, and reports whether simulated behavior matches calculated values.

For op-amps it can resolve (49 in the built-in table, more through distributor APIs), it uses per-part behavioral models with the real GBW, slew rate, and output swing from distributor APIs or a built-in lookup table. When both schematic and PCB exist, it inserts PCB trace parasitics into low-pass RC-filter simulations.

Simulation: 14 pass, 1 warn, 0 fail
  RC filter R5/C3 (fc=15.9kHz): confirmed, <0.3% error
  Opamp U4A (inverting, gain=-10): 20.0dB confirmed
    Bandwidth 98.8kHz (LM324 behavioral, GBW=1.0MHz)
    Note: signal frequency should stay below 85kHz for <1dB gain error

Monte Carlo tolerance analysis — run N simulations per subcircuit with randomized component values within tolerance bands. Shows which component dominates output variation:

Monte Carlo (N=100): RC filter R5/C3
  fc: 15.9kHz ± 1.8kHz (3σ), spread 22.6%
  Sensitivity: C3 (10%) contributes 68%, R5 (5%) contributes 32%

What-if parameter sweep — instantly see the impact of component changes without editing the schematic:

> "What happens if I change R5 from 10k to 4.7k?"

  RC filter R5/C3: cutoff 1.59kHz → 3.39kHz (+112.8%)
  Voltage divider R5/R6: ratio 0.32 → 0.50 (+56.4%)

Requires ngspice, LTspice, or Xyce (auto-detected; PSpice is available only through the explicit run_external_deck.py runner for complete external decks). Without one, simulation is skipped — the rest of the analysis still works. For the full methodology — see SPICE Integration Guide.

📡 EMC pre-compliance

“Will my board pass FCC Class B? Check for EMC issues.”

“Analyze my switching regulator layout for EMI problems”

“Check my differential pairs for skew-induced common-mode radiation”

The emc skill predicts the most common causes of EMC test failures — ground plane voids, insufficient decoupling, unfiltered I/O cables, switching regulator harmonics, differential pair skew, and more. It operates on the schematic and PCB analyzer output using geometric rule checks and analytical emission formulas (Ott, Paul, Bogatin). With --spice-enhanced and a simulator, PDN impedance and EMI filter checks run an AC sweep of the same network (PDN findings stay heuristic) — otherwise analytical models are used.

EMC risk score: 68.5/100
  error:    3 — SPI_CLK crosses ground plane void on In1.Cu,
                USB diff pair 5.2mm skew (exceeds 25ps limit),
                no ground via near TVS U5
  warning:  3 — decoupling cap 7mm from U3, clock on outer layer,
                via stitching gap near J2
  info:     4 — cavity resonance at 715 MHz, switching harmonics
                in 30-88 MHz band

Pre-compliance test plan:
  Focus band: 30-88 MHz (12 switching harmonics from U1, U4)
  Highest risk interface: J1 (USB-C, unfiltered, 480 Mbps)
  Probe points: L1 (45.2, 32.1)mm, Y1 (62.0, 18.5)mm

44 rule checks across power integrity, signal integrity, and radiation. Includes full-board PDN impedance with power tree analysis — traces impedance from regulator output through PCB traces to IC load points, and detects cross-rail coupling when a downstream switching regulator injects transients onto the upstream rail. Supports FCC, CISPR, automotive (CISPR 25), and military (MIL-STD-461G) standards. Generates a pre-compliance test plan with frequency band priorities, interface risk rankings, and near-field probe points. For the full methodology — see EMC Pre-Compliance Guide.

📄 Datasheets — sync and extract

“Sync datasheets for my board at hardware/rev2/”

“What’s the EN-pin threshold on the LDO I’m using?”

Datasheets flow through kicad-happy in two stages:

Sync (download). Pulls PDFs for every component with an MPN from DigiKey, LCSC, element14, or Mouser into a local datasheets/ directory. 96% success rate across 240+ manufacturers. Each PDF is verified against the expected part number.

Extract (parse). The datasheets skill turns those PDFs into structured JSON — pinouts, voltage ratings, electrical characteristics, peripherals, topology, SPICE model coefficients. Extractions are cached per-MPN under <project>/datasheets/extracted/ and scored (typed extractions on a 0–100 pinout/base/category rubric; legacy caches on the older five-dimension rubric). Analyzer skills (kicad, emc, spice, thermal) consume the cache through a shared helper API with trust gates — so a schematic finding tagged confidence: datasheet-backed means a scored extraction produced the underlying fact, not a keyword match on the part number.

For the full pipeline — page selection, the quality rubric, the consumer API, and what it deliberately doesn’t do — see Datasheet Extraction Guide.

📋 BOM management — from schematic to order

“Source all the parts for my board, I’m building 5 prototypes”

The BOM skill manages the full lifecycle of your bill of materials — using your KiCad schematic as the single source of truth. No separate spreadsheets to keep in sync, no copy-pasting between tabs.

The agent analyzes your schematic to detect which distributor fields are populated (and which naming convention you’re using — it handles dozens of variants like Digi-Key_PN, DigiKey Part Number, DK, etc.), identifies gaps, searches distributors to fill them, validates every match, and exports per-supplier order files in the exact upload format each distributor expects.

“I need a 3.3V LDO that can do 500mA in SOT-223, under $1”

AZ1117CH-3.3TRG1 — Arizona Microdevices
  3.3V Fixed, 1A, SOT-223-3
  $0.45 @ qty 1, $0.32 @ qty 100
  In stock: 15,000+

AP2114H-3.3TRG1 — Diodes Incorporated
  3.3V Fixed, 1A, SOT-223
  $0.38 @ qty 1, $0.28 @ qty 100
  In stock: 42,000+

🏭 Manufacturing

“Is this board ready to order?”

“Generate the BOM for JLCPCB assembly”

Fab release gate — an automated pre-order checklist that cross-references your schematic, PCB, and Gerber data:

Fabrication Release Gate — 8 check categories

  Routing completeness     ✓ PASS  All 240 nets routed
  BOM readiness            ⚠ WARN  3 components missing MPN
  DFM compliance           ✓ PASS  No spacing violations, standard tier compatible
  Documentation            ✓ PASS  Title block, revision, fab notes present
  Schematic ↔ PCB match    ✓ PASS  296 components matched, 0 orphans
  Gerber verification      ✓ PASS  All layers present, drill file valid
  Thermal analysis         ⚠ WARN  U3 junction temp 92°C (margin: 18°C)
  EMC pre-compliance       ⚠ WARN  Score 68.5/100 — 3 error findings

  Result: CONDITIONAL PASS (3 warnings to review before ordering)

BOM export — cross-references LCSC part numbers, formats to JLCPCB’s exact spec, flags basic vs extended parts. Per-supplier upload files — DigiKey bulk-add CSV, Mouser cart format, LCSC BOM — with quantities already computed for your board count + spares.

🗺️ Workflow

1. Design your schematic and lay out the PCB in KiCad
2. Sync datasheets — the agent downloads PDFs and extracts structured specs for every MPN
3. Design review — the agent runs schematic, PCB, cross-analysis, EMC, SPICE, and thermal analyzers, cross-references against datasheets, and writes a structured report with findings ranked by severity
4. Iterate — fix issues, re-run the review, compare against the previous run with built-in diff analysis
5. Source components from DigiKey/Mouser (prototype) or LCSC (production)
6. Export BOM + per-supplier order files for your assembler
7. Order from JLCPCB or PCBWay with generated BOM/CPL files

Or set up the GitHub Action and get automated analysis on every PR.

Optional setup

SPICE simulator (for the spice skill): apt install ngspice or LTspice or Xyce. Auto-detected.

API keys (for distributor skills — falls back to web search without them):

Optional: Python packages requests (better HTTP) and playwright (JS-heavy datasheet sites); the pdftotext executable (poppler-utils) for PDF text extraction.

✅ KiCad version support

🎯 Release notes

Current release: v3.0.1 — audit fixes. The fixes from an independent audit of v3.0.0: datasheet downloads limited to public addresses, no writes through symlinks, and SPICE netlists that cannot pick up simulator commands; net names chosen by KiCad’s driver priority and tie-break, and pins, DNP, values and KiCad 10 variants read as KiCad reads them, and KiCad 5 pins and sheet connections corrected; fewer false signals (rails named like VCC_EN, parallel parts, lifecycle single-source); a new GP-001 check for high-speed traces whose reference plane changes; no-connect-type pins kept on nets of their own, supplies recognised by their pins, net ties joining rail and power-pin audits (#50) and switching hot loops measured from pads (#62); UTF-8 output and LF JSON and reports on Windows; and two contributed tools, a harmonic-limit screen (analyze_harmonic_limits.py, #63) and an explicit-only PSpice external-deck runner (run_external_deck.py, #64), both by janos-varga. Upgrading: findings move on most designs (net names on hierarchical schematics, rail findings, outer-layer impedance_ohm); fab_release_gate.py exits 1 on a FAIL verdict; SW-003 grades a hot loop only when analyze_pcb.py --schematic measured it from pads; translate_bom_pnp.py pnp needs --units when the position file states none.

Previous: v3.0.0 — the v3 refactor. Same analyzers, same CLIs, same rule IDs; the code behind them is now a stdlib-only core plus schematic/, pcb/ and distributor_core/ packages. Output changes are additive except: EMC findings drop their duplicate title, every envelope gains diagnostics, and the datasheet-verification / summary tools use error/warning/info. Scripts that imported kicad_utils, sexp_parser or the analyzer modules’ helpers: see the migration table in the CHANGELOG.

Previous: v2.3.2 — backport. AM-001 now reads the <domain>_max keys datasheet extractions use, so it fires on real extractions; every datasheets script reads and writes UTF-8; PU-001 and PP-001 stop flagging no-connect pins and gate-driver bootstrap pins; RS-001 says when it recognised a rail by name only; cross_analysis.py gives a usage error instead of a traceback on a directory. Upgrading: RS-001 on a name-only rail now carries heuristic confidence.

Previous: v2.3.1 — maintenance batch. One shared, case-insensitive part-number alias set (Manufacturer P/N, Digikey P/N, …) for the schematic analyzer, the PCB analyzer and the BOM manager, with manufacturer-specific names ranked above generic ones; CP-003 and via-in-pad use the real outline of round and oval pads; VM-001 stops flagging a correct GPIO-to-EN connection when an extraction lacks the EN threshold. Upgrading: on symbols with both a manufacturer-specific and a generic part-number field, the manufacturer-specific one now wins.

Previous: v2.3.0 — correctness batch. Eighteen verified fixes plus three community contributions: CP-003 touch-pad clearance is measured against real copper (it reported 0.0 mm on most boards and fired on test points), decoupling-distance findings only pair capacitors that actually share a supply net with the IC, the power budget and sleep-current audit stop dropping loads and rails, PD-001 no longer mistakes feedback feedforward caps for decouplers, and the datasheet-authority gates finally receive the project directory. New: SP-001 catches a two-pin part wired to a single net (invisible to ERC), and search_lcsc.py searches the LCSC/JLCPCB catalog from the terminal. Datasheet sync no longer crashes on Windows when it re-saves its manifest. Upgrading: the EMC PD-001 field transient_amps is now transient_a; everything else is additive.

Previous: v2.2.1 — maintenance batch. Twenty-five verified fixes: the GP-001 via-antipad and power-rail-classification false positives from the field are gone, no-connect markers no longer absorb pins into wires passing beneath them (community-contributed, kicad-cli-verified), internal-oscillator IC descriptions stop triggering false clock findings, and a whole class of output nondeterminism was eliminated with a CI guard to keep it that way. Skipped or degraded analysis is now visible (checks_run manifest, connectivity-error notes, conditional-rule skip counts). Upgrading: GitHub Action users with multi-project repos must set the schematic/pcb inputs explicitly (auto-detect now fails loudly instead of guessing), and analyze_pcb.py --schematic analysis/<run_id>/schematic.json now classifies your declared power rails correctly.

Per-release stories are in release-notes.md; line-level detail in the CHANGELOG.

🧪 Test harness

Everything above was run against a corpus of 5,800+ open-source KiCad projects — the kind of designs real engineers actually build. The corpus spans hobby boards, production hardware, motor controllers, RF frontends, battery management systems, IoT devices, audio amplifiers, and everything in between. KiCad 5 through 10. Single-sheet and multi-sheet hierarchical. 2-layer through 6-layer. The corpus checks stability: a change in analyzer output is caught and has to be declared. It does not prove the output is correct. For full methodology and reproducibility instructions, see VALIDATION.md.

The numbers:

Three-layer regression testing catches drift at every level:

🎨 Why KiCad?

This project exists because KiCad is absolutely incredible. Fully open-source, cross-platform, backed by CERN, with a community that ships features faster than most commercial tools. It’s used everywhere from weekend hobby projects to production hardware at real companies.

But what makes KiCad truly special for AI-assisted design — and the entire reason this project can exist — is its beautifully open file format. Every schematic, PCB layout, symbol, and footprint is stored as clean, human-readable S-expressions. No proprietary binary blobs. No vendor lock-in. No $500 “export plugin” just to read your own data.

This means your AI agent can read your KiCad files directly, understand every component, trace every net, and reason about your design at the same level a human engineer would. No KiCad export plugins, no export steps, no intermediary formats. Just your KiCad project and a terminal.

Try doing that with Altium or OrCAD. 😉

📜 License

MIT — see CHANGELOG.md for release history and CONTRIBUTING.md for development guidelines.

Built with Claude Code and OpenAI Codex. 🤖