<div align="center"> <img src="assets/icon.svg" width="90" height="90" alt="pcb-inspector icon" />

pcb-inspector

Automated Multimodal Design Reviewer & Linter for KiCad Projects

Catch placement flaws, decoupling issues, routing problems, and mixed-signal design risks before sending your board to fabrication.

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT"></a> <a href="https://github.com/takzen/pcb-inspector/releases/tag/v0.1.0"><img src="https://img.shields.io/badge/Release-v0.1.0-blue?style=flat-square" alt="Release: v0.1.0"></a> <a href="#"><img src="https://img.shields.io/badge/Tests-422%20passed%20%7C%2090%25-brightgreen?style=flat-square" alt="Tests: 422 passed"></a> <a href="https://kicad.org"><img src="https://img.shields.io/badge/KiCad-8.0%2B%20%7C%209.0%20%7C%2010-314CB6?style=flat-square&logo=kicad&logoColor=white" alt="KiCad Support"></a> <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a> <a href="#-mcp-server--agentic-integration"><img src="https://img.shields.io/badge/MCP%20Server-Supported-5B5EA6?style=flat-square" alt="MCP Server"></a> <a href="#-3-multimodal-visual-review"><img src="https://img.shields.io/badge/AI-Multimodal%20Vision-8A2BE2?style=flat-square&logo=openai&logoColor=white" alt="Multimodal AI"></a> <a href="https://github.com/takzen/pcb-inspector/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome"></a> </p>

🎯 What is it? • ⚡ Quickstart • 📖 User Manual • 🧠 Verification Pipeline • 🤖 MCP Server & Agent Loop • 🏗️ Architecture • 🚀 Use Cases • 🛠️ Roadmap • 📄 License

---

</div>

[!NOTE] pcb-inspector v0.1.0 is now live!
The 3-layer verification engine, built-in MCP server, interactive HTML reporting, and GitHub Action are fully functional. Check out the 📖 User Manual & Configuration Guide (MANUAL.md) for practical examples, rule catalog, and per-project override guides.

🎯 What is it?

pcb-inspector is a multi-layer hardware verification and design-review pipeline for KiCad projects.

Traditional DRC/ERC tools are essential, but they primarily verify explicit electrical and geometric rules. pcb-inspector adds higher-level layout analysis, engineering heuristics, and multimodal visual review to identify potential design issues that may pass standard CAD checks.

It can run standalone as a CLI or GitHub Action on manually designed boards, or integrate with agentic PCB workflows such as Konnect to create a closed-loop design → audit → fix → verify workflow.

[!TIP] Don't just generate a PCB. Independently inspect it before you manufacture it.
Design. Inspect. Fix. Verify.

---

⚡ Quickstart & Installation

Installation

# Using uv (recommended)
uv pip install pcb-inspector

# Or install from source
uv pip install "git+https://github.com/takzen/pcb-inspector.git"

# Optional: Claude (Fable / Opus) as the vision model
uv pip install "pcb-inspector[claude]"

[!IMPORTANT] Layer 1 (DRC/ERC) and hosted vision renders both need KiCad 8+ with kicad-cli on PATH (or kicad_cli_path in the config). Without it, Layer 1 is reported as not run rather than silently skipped; pass --require-kicad-cli to make that a failure, as the bundled GitHub Action does.

Essential CLI Commands

# 1. Full 3-layer audit (DRC + Heuristics + Vision) with interactive HTML report
pcb-inspector check path/to/board.kicad_pcb -o report.html -f html

# 2. Fast deterministic DRC/ERC only (native KiCad)
pcb-inspector drc path/to/board.kicad_pcb

# 3. Spatial & physical engineering heuristics only
pcb-inspector analyze path/to/board.kicad_pcb

# 4. Dedicated Multimodal AI Vision Review (Gemini Flash 3.8, Fable 5, GPT-6 Astra)
pcb-inspector vision path/to/board.kicad_pcb --model gemini-3.8-flash

# 5. Continuous Watch Mode (automatically re-checks on board save)
pcb-inspector check path/to/board.kicad_pcb --watch

# 6. Launch Model Context Protocol (MCP) server for AI agents
pcb-inspector mcp --transport stdio

---

🧠 Multi-Layer Verification Pipeline

pcb-inspector approaches design verification through three complementary layers of defense:

flowchart TD
    subgraph Input ["📥 Design Input"]
        SCH["📄 Schematic Files (.kicad_sch)"]
        PCB["📐 PCB Layout (.kicad_pcb)"]
    end

    subgraph Pipeline ["🔍 pcb-inspector Verification Engine"]
        direction TB
        L1["1️⃣ Deterministic Ground Truth<br/><code>kicad-cli</code> (ERC & DRC checks)"]
        L2["2️⃣ Programmatic Engineering Heuristics<br/>(Decoupling, loop areas, return paths)"]
        L3["3️⃣ Multimodal Visual Review<br/>(Vision LLM on 2D/3D renders)"]
        
        L1 --> Aggregator
        L2 --> Aggregator
        L3 --> Aggregator
        Aggregator["⚡ Findings Aggregator & Prioritizer"]
    end

    subgraph Output ["📋 Actionable Report"]
        Report["🔴 CRITICAL • 🟠 WARNING • 🟡 SUGGESTION • 🟢 PASS<br/>Coordinates • Net Names • Evidence • Fix Instructions"]
    end

    Input --> Pipeline
    Aggregator --> Output

1. Deterministic Ground Truth

Runs KiCad's native verification tools through kicad-cli:

• ERC — Electrical Rules Check
• DRC — Design Rules Check
• Connectivity & netlist verification, including schematic parity: footprints missing from or extra on the board and pads on the wrong net, grouped by kind
• Clearance and short-circuit detection
• Unconnected pins and nets
• Manufacturing and fabrication constraint violations

These results form the deterministic baseline for the entire audit.

---

2. Programmatic Design Analysis

Five rules computed directly from the layout, reading the design intent KiCad records: net classes from the .kicad_pro, the copper stack order, and each pad's schematic pin name.

• Decoupling capacitor placement (HEUR-DEC-001) — distance from every IC supply pin to its nearest bypass capacitor, adding the board thickness for capacitors on the opposite side. Supply pins are recognised by their schematic pin name (VDD, VCC, 3.3V, +VS…) as well as the net name; a bias or reference net such as BIAS_1.65V is not mistaken for a rail.
• Power rail trace width (HEUR-PWR-001) — one finding per net and layer. A trace narrower than its own net class is a warning; one that matches its net class but sits below the configured power-rail guideline is a suggestion, since KiCad treats net class widths as defaults.
• Differential pair skew (HEUR-DIFF-001) — length mismatch across _P/_N, +/-, _DP/_DM and H/L pairs, counting curved (arc) routing and via transitions. Only pairs named as a fast interface (USB, HDMI, PCIe, LVDS, Ethernet, clocks…) can be critical; a CAN bus or an analog sensor pair is a suggestion, since millimetres of skew are picoseconds.
• Switching regulator loop area (HEUR-DCDC-001) — switching nodes confirmed by a declared SW/LX pin or by inductor-to-converter topology, never by net name alone.
• Ground reference (HEUR-GND-001) — the share of each signal segment lying over a ground plane on an adjacent copper layer, read from the board's physical stack order.

[!NOTE] Thresholds are configurable globally and per rule via custom_rules in YAML; any rule can be disabled there. See MANUAL.md for every key.

Not yet implemented, and listed in the Roadmap: thermal proximity of heat-sensitive parts to hot spots, analog/digital separation, copper-weight and via current capacity, and star-routing checks.

---

3. Multimodal Visual Review

Each side of the board is raytraced to PNG with kicad-cli pcb render and reviewed in its own request by Gemini, OpenAI or Claude (Fable/Opus). The API key is read from the chosen provider's own variable — GOOGLE_API_KEY or GEMINI_API_KEY, OPENAI_API_KEY or ANTHROPIC_API_KEY — exported or kept in a .env file in the directory you run from; use --vision-model mock to run offline. A spent daily quota is reported at once rather than retried. Hosted models need the kicad-cli render; the tool refuses to send them anything else rather than fail at the provider. Vision models catch layout anti-patterns that resist formulation into rigid CAD rules:

• Component placement: Clustering balance, awkward orientations, and assembly congestion.
• Routing aesthetics & quality: Unnecessary detours, awkward acute angles, and excessive vias.
• Silkscreen & DFM: Overlapping silkscreens, unreadable reference designators, and obstructed testpoints.
• Polarity & Pin 1: Missing or ambiguous diode/electrolytic polarity and IC Pin 1 indicators.
• Mechanical fit: Edge clearance, mounting hole keepouts, and connector access clearances.
• Schematic intent vs. PCB: Visual cross-check ensuring physical layout reflects functional schematic grouping.

Vision review acts as an automated "peer engineer over your shoulder" — probabilistic guidance backed by deterministic verification.

---

4. Structured, Actionable Feedback

Produces a clean, prioritized report tailored for both human review and automated agent consumption:

| Severity | Meaning | Example | | :--- | :--- | :--- | | 🔴 CRITICAL | Functional failure or manufacturing blocker | DRC short, bypass capacitor on wrong side of via | | 🟠 WARNING | Signal integrity, thermal, or EMI hazard | High-speed trace crossing ground slot, undersized power trace | | 🟡 SUGGESTION | DFM, readability, or best-practice refinement | Obscured silkscreen, sub-optimal component rotation | | 🟢 PASS | Clean verification | All power rails decoupled within target metrics |

Each finding includes:

• Component designators (e.g., U1, C14, L2)
• Affected nets & physical PCB coordinates $(X, Y)$
• Measured values vs. expected thresholds
• Visual snapshots / highlighted bounding boxes
• Concrete, actionable remediation instructions

---

🤖 MCP Server & Agentic Integration

pcb-inspector provides a native Model Context Protocol (MCP) server, making it a drop-in verification tool for AI coding and design agents (Claude Desktop, Cursor, Antigravity).

🤝 The Dual-MCP Synergy: Konnect + pcb-inspector

In modern autonomous hardware workflows, agents need both actuators (to edit KiCad designs) and sensors/auditors (to verify physical correctness):

| Role | MCP Server | Function | | :--- | :--- | :--- | | The Hands (Actuator) | Konnect (by mixelpixx) | Adds components, connects pins, routes traces, modifies footprints in KiCad. | | The Brain & Eyes (Auditor) | pcb-inspector (this project) | Validates DRC/ERC, decoupling proximity, switching loops, ground cuts, and silkscreen DFM. |

Together, they enable a closed-loop autonomous self-correction loop:

sequenceDiagram
    autonumber
    participant Agent as 🤖 Autonomous Agent (Claude / Cursor)
    participant Konnect as 🖐️ Konnect MCP (KiCad Actuator)
    participant Project as 📁 KiCad Project (.kicad_pcb)
    participant Inspector as 👁️ pcb-inspector MCP (Auditor)
    participant Fab as 🏭 Fabrication (JLCPCB / PCBWay)

    Agent->>Konnect: place_component / route_track
    Konnect->>Project: Edits the board live in KiCad (IPC API, undoable)
    Agent->>Inspector: call tool `inspect_project(live=true)`
    activate Inspector
    Inspector->>Project: Snapshot of the open board, then DRC + Heuristics + Vision
    Inspector-->>Agent: Returns structured JSON findings + coordinates