build-hardware-with-ai
AI hardware design toolkit for Claude Code and MCP: 3D-print DFM checks, part fit and screw lengths, KiCad PCB checks against JLCPCB design rules, solder-paste stencils, live LCSC/Mouser/DigiKey part prices. Agent skills for PCBs, 3D printing, reflow and sourcing.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/cforcomputer--build-hardware-with-ai)HTML
<a href="/listings/cforcomputer--build-hardware-with-ai"><img src="/api/listings/cforcomputer--build-hardware-with-ai/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**Claude Code** (skills and MCP tools, plus kicad-happy's skills as a dependency). You need [uv](https://docs.astral.sh/uv/). Add kicad-happy's marketplace first, so its plugin installs along with this one:
/plugin marketplace add aklofas/kicad-happy /plugin marketplace add cforcomputer/build-hardware-with-ai /plugin install build-hardware-with-ai@build-hardware-with-ai
If you skip the first line, the plugin installs but won't load. Claude Code's error tells you to add that marketplace.
**Any other MCP client** (Claude Desktop, Cursor, Codex, ...):
{
"mcpServers": {
"build-hardware-with-ai": {
"command": "uvx",
"args": ["--from", "git+https://github.com/cforcomputer/build-hardware-with-ai", "hwkit", "mcp"]
}
}
}**Command line only** (Python 3.11+):
uv tool install git+https://github.com/cforcomputer/build-hardware-with-ai uv tool install "build-hardware-with-ai[step,fast,optics] @ git+https://github.com/cforcomputer/build-hardware-with-ai" # all extras
**Optional extras:**
- [KiCad](https://www.kicad.org/) 8 or newer, for the rule checks and exports. - Free Mouser and DigiKey API keys in `.env`, for prices beyond LCSC. - `hwkit doctor` lists what is installed.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 24 lines
- {
- "name": "build-hardware-with-ai",
- "owner": {
- "name": "cforcomputer",
- "url": "https://github.com/cforcomputer"
- },
- "metadata": {
- "description": "Checks, tools and skills for AI agents that research, design, verify and order real hardware."
- },
- "plugins": [
- {
- "name": "build-hardware-with-ai",
- "source": "./",
- "description": "Research, design, verify and order hardware with an AI agent: 3D-print DFM, fit, motion and screw checks; KiCad boards vs JLCPCB rules, Gerbers rebuilt and compared with the schematic, BOM/placement, stencils, kicad-happy review, autorouting; optics, focal spots and calibration from thermal motion; papers, datasheets and live part prices; a memory-capped job queue.",
- "version": "0.2.1",
- "author": {
- "name": "cforcomputer"
- }
- }
- ],
- "allowCrossMarketplaceDependenciesOn": [
- "kicad-happy"
- ]
- }
README.md · README · 281 lines
- # build-hardware-with-ai: AI hardware design checks for Claude Code and MCP
- **An open-source toolkit that lets an AI agent research, design, verify and order real hardware:** PCBs, 3D-printed
- and metal parts, optical setups and the parts list. It works with Claude Code, Codex, Cursor or any MCP client, and
- runs on your machine. It covers:
- - **3D printing (DFM)**: measured wall thickness, trapped resin or powder, build volume, supports, mass.
- - **Fit and motion**: overlaps and gaps between parts, moving parts over their whole travel, screw lengths, tool access.
- - **KiCad PCBs**: JLCPCB's design rules through KiCad's DRC. The **Gerber files are rebuilt and compared with the
- schematic** (shorts, opens), along with BOM and placement files, solder-paste stencils, and
- [kicad-happy](https://github.com/aklofas/kicad-happy)'s circuit review. Boards are autorouted with
- [KiCadRoutingTools](https://github.com/drandyhaas/KiCadRoutingTools).
- - **Parts**: live prices from LCSC, Mouser and DigiKey, datasheets and papers, with the source and date on every number.
- - **Optics**: Gaussian beams through lens trains, objectives and back-aperture fill, focal spots, drag near a wall,
- Mie scattering, and stiffness calibration from a thermal-motion position record.
- - **Heavy jobs**: simulations and routing run in a queue with a memory cap.
- [](https://github.com/cforcomputer/build-hardware-with-ai/actions/workflows/tests.yml)
- [](LICENSE)
- [](https://cforcomputer.github.io/build-hardware-with-ai/)
- It is four things in one repo:
- 1. **`hwkit`**, a command-line tool. Every check prints PASS / WARN / FAIL with the numbers behind it and exits with
- code 1 on a FAIL, so it can block an order.
- 2. **An MCP server** (`hwkit mcp`, 40 tools) that gives any AI agent the same checks. It runs locally, so your files,
- KiCad install and API keys stay on your machine.
- 3. **Seven skills** (guides an agent reads before acting): the method from idea to order, boards, printed parts, hand
- assembly, sourcing, simulation, and optical instruments. MCP clients read them with the `guide` tool.
- 4. **A project template** (`hwkit init`). Its `AGENTS.md` holds the working rules for any agent, including a table of
- the mistakes a real project already made once.
- ## Why
- AI agents can write a schematic or a CAD script. Most mistakes happen later, between the file and the parcel:
- - a wall too thin for the process;
- - a lid that clips the case;
- - a carrier that hits its frame at the end of its travel;
- - a screw no driver can reach;
- - a Gerber export that no longer matches the schematic;
- - a stencil that won't release paste;
- - a price quoted from memory, or a chip at end of life.
- Each check here exists because a real device project, built with an agent from simulation to ordered boards and
- printed metal parts, hit that problem.
- ## Install
- **Claude Code** (skills and MCP tools, plus kicad-happy's skills as a dependency). You need
- [uv](https://docs.astral.sh/uv/). Add kicad-happy's marketplace first, so its plugin installs along with this one:
- ```text
- /plugin marketplace add aklofas/kicad-happy
- /plugin marketplace add cforcomputer/build-hardware-with-ai
- /plugin install build-hardware-with-ai@build-hardware-with-ai
- ```
- If you skip the first line, the plugin installs but won't load. Claude Code's error tells you to add that marketplace.
- **Any other MCP client** (Claude Desktop, Cursor, Codex, ...):
- ```json
- {
- "mcpServers": {
- "build-hardware-with-ai": {
- "command": "uvx",
- "args": ["--from", "git+https://github.com/cforcomputer/build-hardware-with-ai", "hwkit", "mcp"]
- }
- }
- }
- ```
- **Command line only** (Python 3.11+):
- ```bash
- uv tool install git+https://github.com/cforcomputer/build-hardware-with-ai
- uv tool install "build-hardware-with-ai[step,fast,optics] @ git+https://github.com/cforcomputer/build-hardware-with-ai" # all extras
- ```
- **Optional extras:**
- - [KiCad](https://www.kicad.org/) 8 or newer, for the rule checks and exports.
- - Free Mouser and DigiKey API keys in `.env`, for prices beyond LCSC.
- - `hwkit doctor` lists what is installed.
- ## Quick start
- ```bash
- hwkit init my-gadget && cd my-gadget # folders, AGENTS.md, CLAUDE.md, gates.toml, docs/order.md, .env.example
- hwkit doctor # installed tools and keys
- hwkit guide hardware-project # the method (or ask your agent to read it)
- hwkit gates # run every gate; results in checks/last_run.md
- ```
- ## What the checks say (real output)
- The examples below use [`examples/demo_parts.py`](examples/demo_parts.py) (an open box and a lid 0.1 mm too low) and
- the [two-sided test board](tests/fixtures/lvs/).
- ```text
- $ hwkit fit case.stl lid.stl --process mjf
- FAIL case.stl / lid.stl overlap 38.40 mm3, 60.00 x 40.00 x 0.10 mm around (0.0, 0.0, 19.9)
- $ hwkit review tests/fixtures/lvs/lvs.kicad_pcb --order-dir tests/fixtures/lvs
- == Order readiness: lvs
- PASS 1. board vs fab limits passed
- PASS 2. fab files vs board nets passed
- PASS 3. BOM and placement passed
- PASS 4. stencil, top passed
- PASS 4. stencil, bottom passed
- $ hwkit gerbers tests/fixtures/lvs/gerbers tests/fixtures/lvs/lvs.kicad_pcb --selftest
- PASS planted bridge R1.1 [N1] to R1.2 [N2], 2.20 mm: reported as a short
- PASS removed holes 2 of 2 removed plated holes reported as opens
- $ hwkit screw M3 --grip 5 --nut hex --room 3
- PASS length shortest stock length that works: 10 mm
- PASS engagement 2.31 to 2.89 mm past the nut face (needs 0.50 mm)
- $ hwkit optics calibrate record.npy --fs 50000 --radius-um 0.5 # a simulated sphere held at 0.020 pN/nm
- "stiffness_pn_per_nm": 0.01988, "corner_hz": 377.1
- ```
- Add `--json` to any check for the full findings as data.
- ## Commands
- | Area | Commands |
- |---|---|
- | Project | `init`, `doctor`, `gates`, `guide [topic]` |
- | Printed and machined parts | `print FILE --process sla\|mjf\|sls\|slm\|bj\|fdm`, `fit A B ...`, `sweep MOVING FIXED... --slide x,y,z --travel a,b` (or `--pivot --axis --angles`), `access PARTS... --start --direction`, `screw M3 --grip ...`, `holes M3 --process mjf`, `render FILES -o x.png`, `compare --before ... --after ... -o sheet.png` |
- | Boards | `review BOARD [--order-dir]` (everything), `pcb`, `gerbers GERBERS BOARD [--schematic] [--selftest]`, `bom BOARD BOM CPL`, `stencil`, `happy PROJECT`, `route BOARD --tries 3`, `jlc-rules`, `limits print\|pcb` |
- | Parts and research | `part NUMBER`, `prices BOM.csv`, `lcsc-cart BOM.csv`, `datasheet PART --find text`, `papers "query"` |
- | Optics | `optics beam\|expander\|objective\|spot\|drag\|calibrate\|simulate` |
- | Heavy work | `jobs submit --mb N -- cmd`, `jobs list\|show\|cancel\|wait`, `run --mb N -- cmd`, `tools [install]` |
- | Server | `mcp` |
- ## MCP tools (40)
- | Area | Tools |
- |---|---|
- | Method and project | `guide`, `project_init`, `doctor`, `gates_run`, `decision_log` |
- | Printed and machined parts | `print_check`, `fit_check`, `sweep_check`, `tool_access`, `screw_stack`, `screw_holes`, `render_views`, `render_compare` |
- | Boards | `board_review`, `pcb_check`, `gerber_check`, `gerber_selftest`, `bom_check`, `stencil_check`, `kicad_happy_review`, `route_board`, `jlcpcb_rules`, `fab_limits` |
- | Parts and research | `part_lookup`, `bom_prices`, `lcsc_cart`, `datasheet_fetch`, `paper_search` |
- | Optics | `beam_path`, `beam_expander`, `objective_aperture`, `focal_spot`, `sphere_drag`, `brownian_calibrate`, `brownian_simulate`, `mie_sphere` |
- | Jobs and tools | `job_submit`, `job_status`, `job_cancel`, `tools_status` |
- The skills are also served as resources (`hwkit://guide/<name>`).
- ## Skills
- | Skill | Covers |
- |---|---|
- | [hardware-project](skills/hardware-project/SKILL.md) | idea to verified order: stages, the gates to have, order day, the tools in and alongside the kit |
- | [pcb-fab](skills/pcb-fab/SKILL.md) | JLCPCB rules in KiCad, routing in the loop, `hwkit review`, exact `kicad-cli` exports, every order-form field, stencils, assembly by the fab |
- | [printed-parts](skills/printed-parts/SKILL.md) | SLA / MJF / SLM / FDM; walls, holes, threads, hollows, gaps; captive nuts; sweeps and tool access; warp; renders |
- | [hand-assembly](skills/hand-assembly/SKILL.md) | hand assembly or fab assembly; hot plate, oven, hot air; lead-free paste and profile; part heat limits; first power-up |
- | [part-sourcing](skills/part-sourcing/SKILL.md) | live prices with dates, lifecycle, exact parts and substitutes, datasheets, LCSC / Mouser / DigiKey / McMaster / AliExpress |
- | [hardware-simulation](skills/hardware-simulation/SKILL.md) | simulate what changes a decision; known answers, convergence, memory-capped job queue, measure afterwards |
- | [optical-instruments](skills/optical-instruments/SKILL.md) | microscopes and laser instruments: laser safety, objectives and filling, conjugate planes, back-focal-plane detection, thermal-motion calibration, heating, drift, parts |
- Skills follow the [Agent Skills](https://agentskills.io) format; copy a folder into your agent's skills directory to
- use one alone.
- ## Tools it drives (fetched on first use, pinned, checksummed)
- | Tool | License | Pinned | Used for |
- |---|---|---|---|
- | [kicad-happy](https://github.com/aklofas/kicad-happy) | MIT | v3.0.1 | schematic, layout, Gerber, EMC and thermal review; release gate (`hwkit happy`, part of `review`) |
- | [KiCadRoutingTools](https://github.com/drandyhaas/KiCadRoutingTools) | MIT | v0.24.0 | autorouting (`hwkit route`); its installer fetches its prebuilt router for your OS |
- Both download into `~/.cache/hwkit` (or `HWKIT_HOME`) and are checked against a SHA-256. To use your own copy instead,
- set `KICAD_HAPPY_DIR` or `KRT_DIR`. kicad-happy's findings are advisory here. Its keepout check reads a zone's outer
- outline only, so those findings are re-measured exactly (cut-outs included) and dropped when the exact check clears
- them.
- ## The project template
- `hwkit init` writes:
- - `AGENTS.md`: the working rules, and the table of mistakes already made once. `CLAUDE.md` imports it.
- - `gates.toml`: one named shell command per claim.
- - `docs/order.md`: the one order document.
- - `docs/decisions.md`: the decision log.
- - `.env.example` for shop keys.
- - Folders: `pcb/`, `mech/out/`, `sim/`, `firmware/`, `order/`, `checks/`, `archive/`.
- ## Where the numbers come from
- | Limits | Source (read 2026-11-19) | Code |
- |---|---|---|
- | 3D printing: walls by part size, clearances, holes, escape holes, text, tolerances, build boxes | [JLC3DP design guideline](https://jlc3dp.com/help/article/3D-Printing-Design-Guideline) | [`rules/jlc3dp.py`](src/hwkit/rules/jlc3dp.py) |
- | Boards: tracks, spacing, vias, holes, rings, edges, silkscreen, sizes, thicknesses | [JLCPCB capabilities](https://jlcpcb.com/capabilities/pcb-capabilities) | [`rules/jlcpcb.py`](src/hwkit/rules/jlcpcb.py) |
- | Stencils: area ratio 0.66, aspect ratio 1.5; electropolishing at 0.5 mm pitch | IPC-7525; JLCPCB's stencil form | [`stencil.py`](src/hwkit/stencil.py) |
- | Screws, nuts, washers, holes, length tolerance | ISO 262, 4762, 7380-1, 10642, 4032, 4035, 7089, 273, 4759-1; DIN 985 | [`fasteners.py`](src/hwkit/fasteners.py) |
- | Gaussian beams, drag, Faxén, power-spectrum calibration | Siegman (1986); Neuman & Block, RSI 75, 2787 (2004); Berg-Sørensen & Flyvbjerg, RSI 75, 594 (2004) | [`optics.py`](src/hwkit/optics.py) |
- Services change their limits. Before an order, re-read the page. The numbers here are a dated copy of it.
- ## How it fits with other tools
- Surveyed 2026-11-19 from each project's README.
- | Project | Relation |
- |---|---|
- | [kicad-happy](https://github.com/aklofas/kicad-happy) (MIT) | driven by this kit as the circuit reviewer, and a plugin dependency for its skills |
- | [KiCadRoutingTools](https://github.com/drandyhaas/KiCadRoutingTools) (MIT) | driven by this kit as the router |
- | KiCad MCP servers ([KiCAD-MCP-Server](https://github.com/mixelpixx/KiCAD-MCP-Server), [Copperpour](https://github.com/Copperpour/Copperpour)) | they let an agent draw boards; this kit checks and orders them. Use together |
- | [build123d-mcp](https://pypi.org/project/build123d-mcp/), [cad-skill](https://github.com/flowful-ai/cad-skill) | they draw parts; `print`, `fit`, `sweep` and `access` check them |
- | [claude-hardware-in-the-loop](https://github.com/Kemerd/claude-hardware-in-the-loop) (source-available) | a larger framework on the same idea of gates. Its README doesn't mention print checks, screw stacks or prices |
- | [CircuitPilot](https://github.com/Abdelhayali/CircuitPilot) (PolyForm Strict) | an all-in-one app, licensed for use only. This kit is MIT and made to compose |
- ## FAQ
- **Can Claude Code design a PCB that can be ordered?**
- It can draw one with KiCad MCP servers. This kit makes sure the order is right:
- - `hwkit route` routes it.
- - `hwkit review` checks KiCad's DRC with JLCPCB's limits, rebuilds the Gerber files and compares them with the
- schematic, checks the BOM and placement files and the stencils, and runs kicad-happy's review.
- **How do I check whether a 3D print will work before ordering it?**
- `hwkit print part.stl --process mjf` measures the walls everywhere and groups the thin areas by size and place. It
- also finds hollows that trap resin or powder, and checks the build volume, supports and mass.
- **How do I calibrate stiffness from Brownian motion (power spectrum)?**
- Record the particle's position at a known sample rate, then run `hwkit optics calibrate positions.csv --fs 50000
- --radius-um 0.5`. It fits the aliased Lorentzian spectrum (Berg-Sørensen & Flyvbjerg 2004) and returns the corner
- frequency and stiffness, plus the detector's metres per volt with `--volts`. Add `--height-um` for Faxén's correction.
- **What beam size fills my objective?**
- `hwkit optics objective 60 1.2 --immersion 1.33 --beam-w 4` gives the back aperture (8.0 mm), the fill ratio and the
- power passed. `hwkit optics expander 1.0 4.0` lists telescopes from stock focal lengths.
- **What are JLCPCB's design rules for KiCad?**
- For 2 layers and 1 oz copper:
- - tracks and spacing 0.10 mm;
- - vias from a 0.15 mm hole with 0.25 mm diameter (a hole under 0.3 mm with a diameter of 0.4 mm or less costs extra);
- - copper at least 0.2 mm from the edge;
- - silkscreen text at least 1.0 mm tall.
- `hwkit jlc-rules -o board.kicad_dru` writes them as KiCad rules.
- **Does it work without Claude?**
- Yes. `hwkit` is a plain command-line tool, the MCP server works with any MCP client, and the guides are Markdown.
- ## Limits of this tool
- - **Fab rules**: JLCPCB and JLC3DP only, for now. Elsewhere, use `--min-wall`, `--build-box` and `--gap`.
- - **Wall thickness**: measured by rays cast inward from points spread over the surface. A strip beside a hole or
- slot is a wall too, and the check reports it. Raise `--samples` for fine parts.
- - **Fit, sweep and access** are exact on closed meshes. Open meshes fall back to sampling.
- - **Warp** has no published threshold, so it is reported as information.
- - **Optics** are paraxial or textbook estimates. Forces of light at a high-NA focus need T-matrix codes.
- - **Laser safety** is a procedure in the guide, not a calculation. Eyewear and exposure limits come from the standard
- and a qualified person.
- - **Sourcing**: LCSC lookups need C-numbers. Mouser and DigiKey need free keys. Thorlabs and McMaster have no open
- price API.
- - **Memory caps** (`hwkit run` and the job queue) sample memory every 0.25–0.5 s.
- - Not affiliated with JLCPCB, LCSC, Mouser, DigiKey, McMaster-Carr, Thorlabs, Anthropic, or the authors of the tools
- it drives.
- ## Development
- ```bash
- git clone https://github.com/cforcomputer/build-hardware-with-ai && cd build-hardware-with-ai
- uv venv && uv pip install -e ".[dev,optics]"
- .venv/bin/python -m pytest # HWKIT_LIVE=1 also queries LCSC
- claude plugin validate .
- ```
- Tests use known answers. Each line below is something the tests check:
- - A 0.3 mm gap measures 0.300 mm.
- - A planted copper bridge is reported as a short.
- - A removed via is reported as an open.
- - A 1 mm beam through f = 100 mm focuses to λf/πw.
- - A simulated particle's stiffness comes back within 6%.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.