⚡ 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 every schematic and PCB file, traces every net, computes every voltage, 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 every regulator 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 every subcircuit — not just passives, but the functional blocks and how they connect:

It audits every connector 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

[!TIP] For detailed installation, upgrade, and troubleshooting guidance across all platforms, have your AI agent read install-guidance.md. It covers platform-specific quirks, known bugs, workarounds, and OS-specific issues.

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 (currently v2.1.0). 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

[!IMPORTANT] Release candidates are pre-release builds intended for evaluation and feedback. They have passed the corpus regression gate and contract test suite but haven't completed extended manual validation. File issues on GitHub if you hit problems.

⚙️ 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 recognized opamps (~100 parts), 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 injects PCB trace parasitics into the simulation.

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). 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). When ngspice is available, PDN impedance and EMI filter checks are SPICE-verified for higher accuracy — otherwise analytical models are used as fallback.

EMC risk score: 73/100
  CRITICAL: 1 — SPI_CLK crosses ground plane void on In1.Cu
  HIGH:     2 — USB diff pair 5.2mm skew (exceeds 25ps limit),
                no ground via near TVS U5
  MEDIUM:   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 on a five-dimension quality 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 73/100 — 2 HIGH 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), playwright (JS-heavy datasheet sites), pdftotext (PDF text extraction).

✅ KiCad version support

🎯 Release notes

Current release: v2.2.0 — hierarchical bus connectivity. The schematic analyzer now resolves bus groups, bus entries, and hierarchical bus pins into real member nets, validated against kicad-cli's own netlist export on golden boards (#25). Same-name local labels on different sheets no longer merge into one net, wire union joins every overlapping wire, and unresolvable bus connections are surfaced honestly instead of guessed. Findings no longer over-claim datasheet provenance, and the plugin installs on Google Antigravity. Upgrading: expect net-list corrections on hierarchical and bus-heavy designs (bus-free boards are byte-identical), and review bare net-name suppressions — they now also match hierarchical key tails.

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

🧪 Test harness

Everything above was validated 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. 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. 🤖