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.

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

🎯 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.

Related MCP server: KiCad MCP SEA

⚡ 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]"

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.

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:

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

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
    deactivate Inspector

    alt Violations Found (e.g. Decoupling too far, DRC clearance)
        Agent->>Konnect: Move C3 closer (< 3.5mm), dry run first, reroute track
        Note over Agent,Inspector: Agent automatically iterates until 🟢 PASS
    else All Checks Pass (🟢 PASS)
        Agent->>Fab: Export Gerbers & send to production!
    end

Konnect edits the board in the running KiCad; the file on disk changes only when someone saves. The audit step therefore reads the open board with live=true (or --live on the CLI), unsaved edits included, through KiCad's API. It needs pip install 'pcb-inspector[live]' and Preferences → Plugins → Enable KiCad API in KiCad 10. Konnect's own plans are worth auditing before they are applied: on a real board its place_decoupling_caps dry run for one op-amp gathered every capacitor sharing ground, scoring itself 70 → 10.

🛠️ Exposed MCP Tools

When launched with pcb-inspector mcp, the server provides:

• inspect_project(project_path: str = "", live: bool = False): Runs the complete 3-layer audit (DRC, Heuristics, Vision) and returns prioritized findings. Every tool takes live=true in place of a path.

• check_decoupling(pcb_path: str, max_distance_mm: float = 3.5): Rapid spatial analysis of IC power pins and decoupling bypass capacitors.

• run_drc(pcb_path: str): Fast deterministic DRC check returning structured clearance and connectivity violations.

• get_actionable_fixes(project_path: str): Machine-readable $(X, Y)$ coordinate patches and step-by-step remediation commands for agents.

🏗️ Design Philosophy

pcb-inspector enforces a strict separation of concerns across its verification tiers:

🚀 Use Cases

• 🤖 AI-Generated PCB Designs: Autonomous validation for LLM/agent-designed boards.

• ⚡ Mixed-Signal & Audio: Protecting analog front-ends from noisy digital microcontrollers.

• 🔋 Power Electronics: Verifying DC/DC buck/boost switching loops and thermal copper pours.

• 📡 RF & High-Speed Digital: Return paths, differential pair continuity, and keepout verification.

• ⏱️ Pre-Fabrication Sanity Check: Catching Silkscreen, footprint, and assembly bugs before purchasing silicon.

• 🔄 CI/CD for Hardware: Automated regression testing on every Git pull request.

🛠️ Roadmap & Progress

v0.1.0 (Released)

• Three-tier verification architecture design & domain data models

• KiCad 8 / 9 / 10 CLI automation wrappers (kicad-cli) & DRC/ERC JSON parsers

• Programmatic spatial & physical heuristics (decoupling, DC/DC loops, return paths, diff pairs, power traces)

• Multimodal vision inspection engine (Gemini Flash 3.8, Fable 5, GPT-6 Astra)

• Board renderer for vision review (superseded — see Unreleased)

• Built-in Model Context Protocol (MCP) Server (pcb-inspector mcp) for autonomous agent loops

• Konnect agentic closed-loop integration & ActionableFix auto-repair coordinates

• Continuous watch mode (--watch) for real-time iterative layout reviews

• Multi-format reporting: Interactive HTML5 (zero CDN), Markdown, JSON, and Terminal Rich

• Reusable GitHub Action (.github/actions/pcb-inspector) for CI/CD pipelines

• Golden Sample reference benchmark boards (clean_board & flawed_board)

Unreleased — reliability and accuracy

• Live audits of the board open in KiCad 10 (--live, MCP live=true), so a repair loop driven through Konnect sees its own unsaved edits

• Vision reads its API key from .env too, accepts GOOGLE_API_KEY as Google's own tools do, and stops retrying once a daily quota is spent (verified against the live Gemini API)

• Checked against a real KiCad 10 analog board: the CLI no longer crashes on ERC titles such as ERC [/]:, supply rails are recognised the same way by every rule (+3.3V was missed, BIAS_1.65V was taken for one), and DRC checks schematic parity

• A target holding no board or schematic is a usage error (exit 2), no longer a PASSED audit with a 100/100 health score; the MCP tools return an error for it too

• Never report a clean board for work not done: failed or missing kicad-cli is a finding, every run records which layers executed, and the GitHub Action installs KiCad

• Parser reads the KiCad 10 file format (nets named inline), curved (arc) tracks, multi-layer zones, net classes, the layer stack and pad pin names; pad positions match pcbnew exactly

• Heuristics fixed for false positives on connectors, SWD/PHY nets and matched pairs, with repair actions keyed to the rule that produced them

• Vision review works with hosted models: raytraced PNG per side via kicad-cli pcb render, Claude through the Anthropic SDK with refusal fallbacks, Gemini requests reach the configured model instead of being rewritten to gemini-2.0-flash

• Findings correlation, ground-reference check and watch mode made fast enough for 26,000-track boards

• HTML report search and category filtering; smoke tests over KiCad's own demo boards

Future Enhancements (v0.2.0+)

• Thermal rule: heat-sensitive parts near power dissipation hot spots

• Analog/digital separation: analog traces crossing digital buses or plane splits

• Via current capacity and copper-weight-aware trace width

• Star-routing and ground-split checks

• Direct Gerber (RS-274X) & Excellon drill file fabrication inspection

• Automated IPC-2221 conductor spacing & current-carrying capacity calculator

• Differential TDR waveform simulation for transmission lines

⚠️ Engineering Disclaimer

pcb-inspector is an automated design-review tool, not a substitute for professional engineering certification. Vision models and heuristic checks may yield false positives or overlook specific corner-case failure modes. Final sign-off and safety-critical decisions remain the sole responsibility of the engineer.

📄 License & Author

This project is licensed under the MIT License — see the LICENSE file for complete details.

Author & Maintainer:
👤 Krzysztof Pika (@takzen)
📫 Contact: takzen.app@gmail.com