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 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:

Subcircuit	Details
Motor drive	9x P-MOSFET switches (DMG2305UX), transistor-driven H-bridges
Filters	RC signal conditioning at 16Hz, 169Hz, and 1.03kHz (input filtering and debounce)
Lighting	WS2812B addressable LED chain on GPIO, 60mA estimated draw
Sensors	Onboard sensor interface, crystal oscillator with load cap validation
Protection	ESD clamp on USB D+/D-, dual input fuses (0.75A signal, 2.5A motor)

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:

Detection	Components	Computed Value	What It Means
RC filter	R21/C31	fc = 15.9 Hz	Low-pass for slow analog signal
RC filter	R1/C13	fc = 169 Hz	Debounce / noise rejection
RC filter	R2/C14	fc = 1.03 kHz	Signal conditioning
Feedback	R8/R9	ratio = 0.155	Buck converter output voltage set
Divider	R42/R43	ratio = 0.500	Voltage sensing (half)
Crystal	Y1	CL = 14.0 pF	Load cap status: ok (target: 18 pF, -22%)

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.

Claude Code (macOS / Linux):

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

OpenAI Codex — global install (macOS / Linux):

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

Windows PowerShell (Codex):

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
}

Note: Windows symlinks may require Developer Mode or elevated privileges.

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

Skill	What it does
kicad	⚡ Parse and analyze KiCad schematics, PCB layouts, Gerbers, and PDF reference designs. Automated subcircuit detection, design review, DFM.
spice	🔬 SPICE simulation — generates testbenches for detected subcircuits, validates filter frequencies, opamp gains, divider ratios. Monte Carlo tolerance analysis. ngspice, LTspice, Xyce.
emc	📡 EMC pre-compliance — 44 rule checks for radiated emission risks, PDN impedance, diff pair skew, ESD paths. FCC/CISPR/automotive/military.
datasheets	📄 Extract structured specs from datasheet PDFs — pinouts, electrical characteristics, peripherals, topology. Per-MPN caching with quality scoring. Consumed by kicad/emc/spice/thermal.
bom	📋 Full BOM lifecycle — analyze, source, price, export tracking CSVs, generate per-supplier order files.
digikey	🔎 Search DigiKey for components and download datasheets via API.
mouser	🔎 Search Mouser for components and download datasheets.