Mini biped robot

hw-codesign

Give an AI agent a hardware brief. Get KiCad, firmware, a 3D assembly, and an explicit fabrication-blocker report.

Agentic hardware co-design from brief to KiCad, firmware, 3D review, and explicit fabrication blockers. For 13 supported board families, hw-codesign turns a prompt into a reviewable candidate while keeping missing sourcing, toolchain, manufacturing, and physical evidence visible instead of silently treating it as success.

Explore the interactive 3D review
Rotate and zoom the generated RP2040 USB candidate, then inspect its evidence and unresolved blockers.

Explore the interactive 3D review · Install from PyPI · Watch the 20-second demo · Read the validation contract

The render is a candidate-level CAD preview, not a photo of fabricated or qualified hardware.

Quickstart

Python 3.11 or newer is required. This public install path was smoke-tested in a clean Python 3.11 environment against version 0.1.4.

python3.11 -m pip install "hw-codesign[mcp]==0.1.4"
mkdir my-hardware-workspace && cd my-hardware-workspace
hw --root . create-project my_usb_board --template rp2040_usb_device
hw --root . validate-spec my_usb_board

That creates and validates a typed RP2040 project. Continue to generate the full demo candidate, or run hw --help to inspect the CLI.

The published package has also been independently exercised in a disposable Debian 13 x86-64 container with Python 3.11.15. See the clean-platform reproduction report for the exact environment, commands, and passing output.

The 20-second product loop

hw-codesign is available as a CLI (hw), an MCP server (hw-mcp), and a repository-owned agent plugin. Its design surface is template- and contract-driven. It is not an arbitrary-prompt PCB oracle.

Install

Python 3.11 or newer is required.

python3.11 -m pip install "hw-codesign[mcp]==0.1.4"
hw --help

The v0.1.4 release also publishes a wheel, source distribution, standalone archives for Linux, macOS, and Windows, a self-contained review, and checksums. The public container is ghcr.io/mrcha033/hw-codesign:0.1.4.

Development install

git clone https://github.com/mrcha033/hw-codesign.git
cd hw-codesign
python3.11 -m venv .venv
.venv/bin/pip install '.[mcp]'
export PATH="$PWD/.venv/bin:$PATH"
hw --help

The self-contained review is live at https://mrcha033.github.io/hw-codesign/ and can be inspected without a receiver or cloud account.

Generate the demo candidate

Create the same candidate class used in the demo:

mkdir my-hardware-workspace
cd my-hardware-workspace

hw --root . create-project my_usb_board --template rp2040_usb_device
hw --root . update-requirements my_usb_board \
  "Design a 2-layer RP2040 USB HID and CDC board powered from USB-C. Use Zephyr."
hw --root . design-candidate my_usb_board --brief \
  "Design a 2-layer RP2040 USB HID and CDC board powered from USB-C. Use Zephyr."
hw --root . export-standalone-review my_usb_board

The generated HTML review is self-contained. No receiver or cloud account is required to inspect it.

MCP clients

Claude Desktop configuration:

{
  "mcpServers": {
    "hw-codesign": {
      "command": "/absolute/path/to/hw-codesign/.venv/bin/hw-mcp",
      "args": [],
      "env": {
        "HW_PLATFORM_ROOT": "/absolute/path/to/a/writable/hardware-workspace"
      }
    }
  }
}

Claude Code:

claude mcp add hw-codesign \
  -e HW_PLATFORM_ROOT="$PWD" \
  -- /absolute/path/to/hw-codesign/.venv/bin/hw-mcp

For Codex or Claude plugin use, clone this repository and install the hw-codesign marketplace entry:

codex plugin marketplace add /absolute/path/to/hw-codesign
codex plugin add hw-codesign@hw-codesign

What the statuses mean

Every public tool response carries release_eligible, candidate_only, and release_blocking_failures. Only the release-gate and release-export paths can set release_eligible: true.

Supported board families

All 13 shipped templates conform to the current typed spec schema. Their design and physical maturity are not identical; inspect each candidate's gate report.

Use hw diagnose-environment to inspect the installed native backends, or see Adapting the design system before adding a materially different topology.

Agent workflow

The MCP names use the same lifecycle as the CLI:

hw_get_capabilities
  → hw_create_project
  → hw_update_requirements
  → hw_design_candidate
  → hw_check_cross_domain_consistency
  → hw_generate_physical_qualification_plan
  → hw_record_physical_evidence
  → hw_check_release_gate
  → hw_export_release_bundle

Agents can also author circuit blocks, placement constraints, and firmware modules, explore alternatives, compare candidates, and run adversarial grounding benchmarks. See the MCP tool reference for the complete contract.

Build with us

• Reproduce the PyPI quickstart on a clean platform — the current newcomer task.
• Share a generated candidate — include the prompt, template, environment, and blocker report.
• Help close sourcing or physical-evidence gaps — software-clean is not the end of the hardware lifecycle.

If a new board family or backend is your goal, start with Adapting the design system and preserve the pass/fail/blocked claim boundary in every new tool path.

Repository map

Development

python3.11 -m venv .venv
.venv/bin/pip install '.[dev,mcp]'
npm ci --ignore-scripts
pytest -q
ruff check .

Native gates require their corresponding tools. Diagnose the current machine before interpreting a blocked result:

hw diagnose-environment --target fabrication_release --backend kicad
hw check my_usb_board

See CONTRIBUTING.md for contribution scope, tests, and claim boundaries. Security reports should follow SECURITY.md.

Known limits

• Generated artifacts remain candidates until every configured release gate passes. A Gerber ZIP is not proof that a board is safe or manufacturable.
• Digital checks cannot certify thermal performance, EMI/EMC, vibration, ingress, abuse safety, connector life, assembly quality, or electrical bring-up. Those require traceable physical evidence.
• The RP2040 golden candidate has not yet been fabricated. Its current blocker report is published deliberately, and no bench measurements are claimed.
• Supplier catalog entries identify parts and provenance, but current stock and alternates require fresh supplier evidence.
• The receiver binds only to loopback. Remote use requires an authenticated SSH tunnel or reverse proxy; it is not a multi-tenant hosted service.

License

The project is licensed under Apache-2.0. The vendored KiCad footprint under src/hw_codesign/footprints/ retains its CC-BY-SA 4.0 license with the KiCad libraries exception; see NOTICE for the boundary.