aklofas/kicad-happy

kicad‑happy – AI‑powered design review for KiCad projects

What it is

• A Python‑only tool that analyses KiCad schematics, PCB layouts and Gerber files and produces a detailed design‑review report. It can run locally, as a GitHub Action, or as a plug‑in for several AI coding assistants (Claude Code, OpenAI Codex, Google Antigravity, opencode).

Core capabilities

Area	What the tool does
Parsing	Reads KiCad project files, builds a netlist, extracts component values and creates a structured representation of the power tree and sub‑circuits.
Design audit	Detects common errors (missing ESD protection, inadequate decoupling, bad trace widths, improper voltage‑divider ratios, etc.) and flags them with severity icons.
SPICE simulation	Auto‑generates test‑benches for detected sub‑circuits, runs them with ngspice/LTspice/Xyce, and reports measured vs. calculated behaviour. Supports Monte‑Carlo tolerance sweeps and quick what‑if parameter changes.
EMC pre‑compliance	Runs 44 rule checks (ground‑plane voids, differential‑pair skew, PDN impedance, switching‑regulator harmonics, etc.) and produces an EMC risk score with suggested mitigation steps.
Datasheet cross‑reference	Pulls key specs from component PDFs, caches them per‑MPN, and uses the data for voltage‑regulator feedback, filter calculations, and part‑life‑cycle alerts.
BOM & sourcing	Generates a full Bill‑of‑Materials, can query DigiKey, Mouser, LCSC, Element14 and export supplier‑specific order files (JLCPCB, PCBWay).
Certification hints	Suggests relevant regulatory standards (FCC Part 15 B, CISPR 32, automotive, military) based on detected circuitry.

How it is used

• Standalone: Clone the repo and run the Python scripts directly (python -m kicad_happy <project‑path>). No external dependencies other than a Python 3.10+ interpreter.
• GitHub Action: Add the provided workflow file; on every PR that touches KiCad files the action runs the analysis and posts a structured comment with the power tree, SPICE results, EMC risk, etc.
• AI‑agent plug‑ins: The repository ships 11 “skills” (kicad, spice, emc, datasheets, bom, digikey, mouser, lcsc, element14, jlcpcb, pcbway). Installing the plug‑in makes an AI assistant capable of answering natural‑language queries such as “Check the boost‑converter loop for EMI” or “Generate a SPICE sweep for my LC network”.

Installation highlights

• Pure‑Python, zero pip packages; works without a local KiCad installation.
• Multiple install paths are documented (Claude Code marketplace, Codex skill installer, Google Antigravity CLI, manual symlink setup, or simple git clone for opencode).
• Release candidates are available via tag‑specific marketplace references.

Typical workflow

1. Point the tool (or your AI assistant) at a KiCad project directory.
2. It parses schematics and PCB files, builds a power‑tree diagram and identifies sub‑circuits.
3. Runs optional SPICE simulations and EMC rule checks.
4. Produces a markdown report containing:
   • Power‑rail hierarchy with calculated voltages.
   • Sub‑circuit table (motor drive, filters, etc.).
   • Connector ESD coverage list.
   • Passive‑network calculations (filter cut‑offs, divider ratios, crystal load caps).
   • Certification suggestions and BOM readiness status.
5. The report can be read by a human or posted automatically by the GitHub Action.

Limitations & requirements

• SPICE simulation requires an external simulator (ngspice, LTspice or Xyce) to be installed; otherwise the tool skips the simulation step.
• AI integration depends on the host agent’s plug‑in system; the README notes a known Claude Code caching bug that may require manual cache clearing.
• The analysis is rule‑based and relies on the accuracy of component datasheets; it does not replace a full physical prototype or formal verification.

Why it matters kicad‑happy brings large‑language‑model‑driven reasoning to electronic‑design automation. By turning a KiCad project into structured data that an AI can query, it lets engineers get instant design‑review feedback, run quick SPICE checks, and catch costly mistakes before ordering PCBs—bridging the gap between software‑centric AI assistants and hardware design workflows.