# @bacnh85/pi-kicad

KiCad CAD-design extension for the [Pi coding agent](https://github.com/earendil-works/pi).
Design schematics and PCB layouts by driving the [**Konnect**](https://github.com/mixelpixx/Konnect)
binary — **no MCP SDK, no generic MCP client**. Konnect is launched once in its
built-in HTTP mode as a managed local daemon, and each tool call is a single
stateless `POST /mcp` JSON-RPC request.

## Install

```bash
pi install npm:@bacnh85/pi-kicad
```

## Tools

| Tool | Purpose |
|---|---|
| `kicad_call` | Invoke any of Konnect's 185 tools by name (schematic capture, layout, routing, ERC/DRC, exports, design review, JLCPCB parts, Freerouting, reference circuits). |
| `kicad_batch` | Run multiple Konnect tool calls **sequentially** in one shot (each op awaits the next, avoiding Konnect's same-file atomic-rename race). Returns a per-op summary; full parsed results in `details` (each capped at the same 12k-char output budget as `kicad_call` — oversized results are truncated with a `…(truncated)` marker). |
| `kicad_status` | Resolve the Konnect binary, `kicad-cli`, and IPC socket; start/health-check the daemon; report version + active tool count. Use first when something isn't working. |

Konnect loads only a small toolset starter kit for context economy. Call
`list_toolboxes` → `load_toolset("<name>")` before domain tools; `unload_toolset`
to prune. See the bundled **kicad** skill for the full design workflow.

## Prerequisites

- **KiCad 10** — Konnect's PCB tools use the v10 IPC API. Schematic + export tools
  work without KiCad running.
- **The Konnect binary** — install separately (this package does **not** vendor it):
  - KiCad 10 → Plugin and Content Manager → *Install from File* → the `konnect-pcm-*` zip for your OS, **or**
  - a [GitHub release](https://github.com/mixelpixx/Konnect/releases) tarball.
  - macOS browser download: clear quarantine first — `xattr -d com.apple.quarantine ./konnect`.
- For PCB layout/routing: open KiCad 10 and enable **Preferences → Plugins → "Enable KiCad API"**, with the target board open.

## Configuration

All optional — auto-discovered. Override with environment variables:

| Variable | Default | Meaning |
|---|---|---|
| `KONNECT_BINARY` (or `KICAD_BINARY`) | auto (KiCad 10 PCM path, then release cache) | Path to the `konnect` binary |
| `KICAD_CLI` | auto (app bundle / `/usr/bin` / Program Files) | Path to `kicad-cli` |
| `KICAD_API_SOCKET` | Konnect auto-detect | KiCad IPC socket, e.g. `ipc:///tmp/kicad/api.sock` |
| `KICAD_HTTP_PORT` | `31337` | Preferred daemon port (falls back to a free one) |
| `KICAD_LOG_LEVEL` | `info` | Konnect log level (error/warn/info/debug/trace) |
| `KICAD10_SYMBOL_DIR` | `~/.pi/kicad-symbols` (managed dir) | Overrides the symbol dir Konnect resolves `lib_id`s from |
| `KICAD_SHARED_SUPPORT` | auto (per-OS app paths) | Overrides the KiCad SharedSupport dir used for footprints/templates |
| `KICAD_PROJECT_DIR` | none | KiCad project dir (written to the daemon TOML as `project_dir`) |

## How it works

```
Pi agent ── kicad_call ──► POST http://127.0.0.1:<port>/mcp   ──► Konnect daemon (HTTP mode)
                                                                         │
                                          ┌──────────────────────────────┴───┐
                                          ▼                                   ▼
                              .kicad_sch S-expr engine               KiCad 10 IPC API (NNG)
                              (atomic writes, no UI)                 (PCB edits, undo-aware)
                                                  │
                                                  ▼
                                         kicad-cli subprocess
                                         (ERC, DRC, Gerber, PDF, BOM, 3D…)
```

A fresh daemon is always spawned for this session: `pi-kicad` picks a free port
(preferring `KICAD_HTTP_PORT`), writes a private temp TOML, spawns
`konnect --config <tmp-toml>` (transport=`http`), polls `GET /health`, and kills
it on Pi exit. An already-running daemon found on the port (e.g. left over from
an earlier session) is **never** reused — it may carry a stale environment — so
the spawn skips occupied ports instead.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.

## License

This package is **MIT**. Konnect is **AGPL-3.0** (free for hobbyists/students/OS;
commercial license otherwise). `pi-kicad` communicates with Konnect as a separate
process over a standard local protocol — it does not bundle or link Konnect, so it
is not a derivative work. The Konnect binary remains a user-installed prerequisite.