Skip to content
Back to search

build-hardware-with-ai

MarketplaceWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cforcomputer--build-hardware-with-ai/badge.svg)](/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
  1. {
  2. "name": "build-hardware-with-ai",
  3. "owner": {
  4. "name": "cforcomputer",
  5. "url": "https://github.com/cforcomputer"
  6. },
  7. "metadata": {
  8. "description": "Checks, tools and skills for AI agents that research, design, verify and order real hardware."
  9. },
  10. "plugins": [
  11. {
  12. "name": "build-hardware-with-ai",
  13. "source": "./",
  14. "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.",
  15. "version": "0.2.1",
  16. "author": {
  17. "name": "cforcomputer"
  18. }
  19. }
  20. ],
  21. "allowCrossMarketplaceDependenciesOn": [
  22. "kicad-happy"
  23. ]
  24. }
README.md · README · 281 lines
  1. # build-hardware-with-ai: AI hardware design checks for Claude Code and MCP
  2. **An open-source toolkit that lets an AI agent research, design, verify and order real hardware:** PCBs, 3D-printed
  3. and metal parts, optical setups and the parts list. It works with Claude Code, Codex, Cursor or any MCP client, and
  4. runs on your machine. It covers:
  5. - **3D printing (DFM)**: measured wall thickness, trapped resin or powder, build volume, supports, mass.
  6. - **Fit and motion**: overlaps and gaps between parts, moving parts over their whole travel, screw lengths, tool access.
  7. - **KiCad PCBs**: JLCPCB's design rules through KiCad's DRC. The **Gerber files are rebuilt and compared with the
  8. schematic** (shorts, opens), along with BOM and placement files, solder-paste stencils, and
  9. [kicad-happy](https://github.com/aklofas/kicad-happy)'s circuit review. Boards are autorouted with
  10. [KiCadRoutingTools](https://github.com/drandyhaas/KiCadRoutingTools).
  11. - **Parts**: live prices from LCSC, Mouser and DigiKey, datasheets and papers, with the source and date on every number.
  12. - **Optics**: Gaussian beams through lens trains, objectives and back-aperture fill, focal spots, drag near a wall,
  13. Mie scattering, and stiffness calibration from a thermal-motion position record.
  14. - **Heavy jobs**: simulations and routing run in a queue with a memory cap.
  15. [![tests](https://github.com/cforcomputer/build-hardware-with-ai/actions/workflows/tests.yml/badge.svg)](https://github.com/cforcomputer/build-hardware-with-ai/actions/workflows/tests.yml)
  16. [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  17. [![Website](https://img.shields.io/badge/site-cforcomputer.github.io-blue)](https://cforcomputer.github.io/build-hardware-with-ai/)
  18. It is four things in one repo:
  19. 1. **`hwkit`**, a command-line tool. Every check prints PASS / WARN / FAIL with the numbers behind it and exits with
  20. code 1 on a FAIL, so it can block an order.
  21. 2. **An MCP server** (`hwkit mcp`, 40 tools) that gives any AI agent the same checks. It runs locally, so your files,
  22. KiCad install and API keys stay on your machine.
  23. 3. **Seven skills** (guides an agent reads before acting): the method from idea to order, boards, printed parts, hand
  24. assembly, sourcing, simulation, and optical instruments. MCP clients read them with the `guide` tool.
  25. 4. **A project template** (`hwkit init`). Its `AGENTS.md` holds the working rules for any agent, including a table of
  26. the mistakes a real project already made once.
  27. ## Why
  28. AI agents can write a schematic or a CAD script. Most mistakes happen later, between the file and the parcel:
  29. - a wall too thin for the process;
  30. - a lid that clips the case;
  31. - a carrier that hits its frame at the end of its travel;
  32. - a screw no driver can reach;
  33. - a Gerber export that no longer matches the schematic;
  34. - a stencil that won't release paste;
  35. - a price quoted from memory, or a chip at end of life.
  36. Each check here exists because a real device project, built with an agent from simulation to ordered boards and
  37. printed metal parts, hit that problem.
  38. ## Install
  39. **Claude Code** (skills and MCP tools, plus kicad-happy's skills as a dependency). You need
  40. [uv](https://docs.astral.sh/uv/). Add kicad-happy's marketplace first, so its plugin installs along with this one:
  41. ```text
  42. /plugin marketplace add aklofas/kicad-happy
  43. /plugin marketplace add cforcomputer/build-hardware-with-ai
  44. /plugin install build-hardware-with-ai@build-hardware-with-ai
  45. ```
  46. If you skip the first line, the plugin installs but won't load. Claude Code's error tells you to add that marketplace.
  47. **Any other MCP client** (Claude Desktop, Cursor, Codex, ...):
  48. ```json
  49. {
  50. "mcpServers": {
  51. "build-hardware-with-ai": {
  52. "command": "uvx",
  53. "args": ["--from", "git+https://github.com/cforcomputer/build-hardware-with-ai", "hwkit", "mcp"]
  54. }
  55. }
  56. }
  57. ```
  58. **Command line only** (Python 3.11+):
  59. ```bash
  60. uv tool install git+https://github.com/cforcomputer/build-hardware-with-ai
  61. uv tool install "build-hardware-with-ai[step,fast,optics] @ git+https://github.com/cforcomputer/build-hardware-with-ai" # all extras
  62. ```
  63. **Optional extras:**
  64. - [KiCad](https://www.kicad.org/) 8 or newer, for the rule checks and exports.
  65. - Free Mouser and DigiKey API keys in `.env`, for prices beyond LCSC.
  66. - `hwkit doctor` lists what is installed.
  67. ## Quick start
  68. ```bash
  69. hwkit init my-gadget && cd my-gadget # folders, AGENTS.md, CLAUDE.md, gates.toml, docs/order.md, .env.example
  70. hwkit doctor # installed tools and keys
  71. hwkit guide hardware-project # the method (or ask your agent to read it)
  72. hwkit gates # run every gate; results in checks/last_run.md
  73. ```
  74. ## What the checks say (real output)
  75. The examples below use [`examples/demo_parts.py`](examples/demo_parts.py) (an open box and a lid 0.1 mm too low) and
  76. the [two-sided test board](tests/fixtures/lvs/).
  77. ```text
  78. $ hwkit fit case.stl lid.stl --process mjf
  79. 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)
  80. $ hwkit review tests/fixtures/lvs/lvs.kicad_pcb --order-dir tests/fixtures/lvs
  81. == Order readiness: lvs
  82. PASS 1. board vs fab limits passed
  83. PASS 2. fab files vs board nets passed
  84. PASS 3. BOM and placement passed
  85. PASS 4. stencil, top passed
  86. PASS 4. stencil, bottom passed
  87. $ hwkit gerbers tests/fixtures/lvs/gerbers tests/fixtures/lvs/lvs.kicad_pcb --selftest
  88. PASS planted bridge R1.1 [N1] to R1.2 [N2], 2.20 mm: reported as a short
  89. PASS removed holes 2 of 2 removed plated holes reported as opens
  90. $ hwkit screw M3 --grip 5 --nut hex --room 3
  91. PASS length shortest stock length that works: 10 mm
  92. PASS engagement 2.31 to 2.89 mm past the nut face (needs 0.50 mm)
  93. $ hwkit optics calibrate record.npy --fs 50000 --radius-um 0.5 # a simulated sphere held at 0.020 pN/nm
  94. "stiffness_pn_per_nm": 0.01988, "corner_hz": 377.1
  95. ```
  96. Add `--json` to any check for the full findings as data.
  97. ## Commands
  98. | Area | Commands |
  99. |---|---|
  100. | Project | `init`, `doctor`, `gates`, `guide [topic]` |
  101. | 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` |
  102. | 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` |
  103. | Parts and research | `part NUMBER`, `prices BOM.csv`, `lcsc-cart BOM.csv`, `datasheet PART --find text`, `papers "query"` |
  104. | Optics | `optics beam\|expander\|objective\|spot\|drag\|calibrate\|simulate` |
  105. | Heavy work | `jobs submit --mb N -- cmd`, `jobs list\|show\|cancel\|wait`, `run --mb N -- cmd`, `tools [install]` |
  106. | Server | `mcp` |
  107. ## MCP tools (40)
  108. | Area | Tools |
  109. |---|---|
  110. | Method and project | `guide`, `project_init`, `doctor`, `gates_run`, `decision_log` |
  111. | Printed and machined parts | `print_check`, `fit_check`, `sweep_check`, `tool_access`, `screw_stack`, `screw_holes`, `render_views`, `render_compare` |
  112. | Boards | `board_review`, `pcb_check`, `gerber_check`, `gerber_selftest`, `bom_check`, `stencil_check`, `kicad_happy_review`, `route_board`, `jlcpcb_rules`, `fab_limits` |
  113. | Parts and research | `part_lookup`, `bom_prices`, `lcsc_cart`, `datasheet_fetch`, `paper_search` |
  114. | Optics | `beam_path`, `beam_expander`, `objective_aperture`, `focal_spot`, `sphere_drag`, `brownian_calibrate`, `brownian_simulate`, `mie_sphere` |
  115. | Jobs and tools | `job_submit`, `job_status`, `job_cancel`, `tools_status` |
  116. The skills are also served as resources (`hwkit://guide/<name>`).
  117. ## Skills
  118. | Skill | Covers |
  119. |---|---|
  120. | [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 |
  121. | [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 |
  122. | [printed-parts](skills/printed-parts/SKILL.md) | SLA / MJF / SLM / FDM; walls, holes, threads, hollows, gaps; captive nuts; sweeps and tool access; warp; renders |
  123. | [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 |
  124. | [part-sourcing](skills/part-sourcing/SKILL.md) | live prices with dates, lifecycle, exact parts and substitutes, datasheets, LCSC / Mouser / DigiKey / McMaster / AliExpress |
  125. | [hardware-simulation](skills/hardware-simulation/SKILL.md) | simulate what changes a decision; known answers, convergence, memory-capped job queue, measure afterwards |
  126. | [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 |
  127. Skills follow the [Agent Skills](https://agentskills.io) format; copy a folder into your agent's skills directory to
  128. use one alone.
  129. ## Tools it drives (fetched on first use, pinned, checksummed)
  130. | Tool | License | Pinned | Used for |
  131. |---|---|---|---|
  132. | [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`) |
  133. | [KiCadRoutingTools](https://github.com/drandyhaas/KiCadRoutingTools) | MIT | v0.24.0 | autorouting (`hwkit route`); its installer fetches its prebuilt router for your OS |
  134. Both download into `~/.cache/hwkit` (or `HWKIT_HOME`) and are checked against a SHA-256. To use your own copy instead,
  135. set `KICAD_HAPPY_DIR` or `KRT_DIR`. kicad-happy's findings are advisory here. Its keepout check reads a zone's outer
  136. outline only, so those findings are re-measured exactly (cut-outs included) and dropped when the exact check clears
  137. them.
  138. ## The project template
  139. `hwkit init` writes:
  140. - `AGENTS.md`: the working rules, and the table of mistakes already made once. `CLAUDE.md` imports it.
  141. - `gates.toml`: one named shell command per claim.
  142. - `docs/order.md`: the one order document.
  143. - `docs/decisions.md`: the decision log.
  144. - `.env.example` for shop keys.
  145. - Folders: `pcb/`, `mech/out/`, `sim/`, `firmware/`, `order/`, `checks/`, `archive/`.
  146. ## Where the numbers come from
  147. | Limits | Source (read 2026-11-19) | Code |
  148. |---|---|---|
  149. | 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) |
  150. | 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) |
  151. | 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) |
  152. | 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) |
  153. | 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) |
  154. Services change their limits. Before an order, re-read the page. The numbers here are a dated copy of it.
  155. ## How it fits with other tools
  156. Surveyed 2026-11-19 from each project's README.
  157. | Project | Relation |
  158. |---|---|
  159. | [kicad-happy](https://github.com/aklofas/kicad-happy) (MIT) | driven by this kit as the circuit reviewer, and a plugin dependency for its skills |
  160. | [KiCadRoutingTools](https://github.com/drandyhaas/KiCadRoutingTools) (MIT) | driven by this kit as the router |
  161. | 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 |
  162. | [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 |
  163. | [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 |
  164. | [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 |
  165. ## FAQ
  166. **Can Claude Code design a PCB that can be ordered?**
  167. It can draw one with KiCad MCP servers. This kit makes sure the order is right:
  168. - `hwkit route` routes it.
  169. - `hwkit review` checks KiCad's DRC with JLCPCB's limits, rebuilds the Gerber files and compares them with the
  170. schematic, checks the BOM and placement files and the stencils, and runs kicad-happy's review.
  171. **How do I check whether a 3D print will work before ordering it?**
  172. `hwkit print part.stl --process mjf` measures the walls everywhere and groups the thin areas by size and place. It
  173. also finds hollows that trap resin or powder, and checks the build volume, supports and mass.
  174. **How do I calibrate stiffness from Brownian motion (power spectrum)?**
  175. Record the particle's position at a known sample rate, then run `hwkit optics calibrate positions.csv --fs 50000
  176. --radius-um 0.5`. It fits the aliased Lorentzian spectrum (Berg-Sørensen & Flyvbjerg 2004) and returns the corner
  177. frequency and stiffness, plus the detector's metres per volt with `--volts`. Add `--height-um` for Faxén's correction.
  178. **What beam size fills my objective?**
  179. `hwkit optics objective 60 1.2 --immersion 1.33 --beam-w 4` gives the back aperture (8.0 mm), the fill ratio and the
  180. power passed. `hwkit optics expander 1.0 4.0` lists telescopes from stock focal lengths.
  181. **What are JLCPCB's design rules for KiCad?**
  182. For 2 layers and 1 oz copper:
  183. - tracks and spacing 0.10 mm;
  184. - 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);
  185. - copper at least 0.2 mm from the edge;
  186. - silkscreen text at least 1.0 mm tall.
  187. `hwkit jlc-rules -o board.kicad_dru` writes them as KiCad rules.
  188. **Does it work without Claude?**
  189. Yes. `hwkit` is a plain command-line tool, the MCP server works with any MCP client, and the guides are Markdown.
  190. ## Limits of this tool
  191. - **Fab rules**: JLCPCB and JLC3DP only, for now. Elsewhere, use `--min-wall`, `--build-box` and `--gap`.
  192. - **Wall thickness**: measured by rays cast inward from points spread over the surface. A strip beside a hole or
  193. slot is a wall too, and the check reports it. Raise `--samples` for fine parts.
  194. - **Fit, sweep and access** are exact on closed meshes. Open meshes fall back to sampling.
  195. - **Warp** has no published threshold, so it is reported as information.
  196. - **Optics** are paraxial or textbook estimates. Forces of light at a high-NA focus need T-matrix codes.
  197. - **Laser safety** is a procedure in the guide, not a calculation. Eyewear and exposure limits come from the standard
  198. and a qualified person.
  199. - **Sourcing**: LCSC lookups need C-numbers. Mouser and DigiKey need free keys. Thorlabs and McMaster have no open
  200. price API.
  201. - **Memory caps** (`hwkit run` and the job queue) sample memory every 0.25–0.5 s.
  202. - Not affiliated with JLCPCB, LCSC, Mouser, DigiKey, McMaster-Carr, Thorlabs, Anthropic, or the authors of the tools
  203. it drives.
  204. ## Development
  205. ```bash
  206. git clone https://github.com/cforcomputer/build-hardware-with-ai && cd build-hardware-with-ai
  207. uv venv && uv pip install -e ".[dev,optics]"
  208. .venv/bin/python -m pytest # HWKIT_LIVE=1 also queries LCSC
  209. claude plugin validate .
  210. ```
  211. Tests use known answers. Each line below is something the tests check:
  212. - A 0.3 mm gap measures 0.300 mm.
  213. - A planted copper bridge is reported as a short.
  214. - A removed via is reported as an open.
  215. - A 1 mm beam through f = 100 mm focuses to λf/πw.
  216. - A simulated particle's stiffness comes back within 6%.
  217. ## License
  218. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.