Cloud (Claude Code) → Adom Relay Server (Docker, WebSocket) → Adom Desktop (Tauri, Windows) → KiCad Plugin → KiCad

{
  "app": "kicad",
  "command": "<command_name>",
  "args": { ... }
}

{ "command": "open_board", "args": { "filePath": "C:\\Users\\john\\project\\board.kicad_pcb" } }

{ "command": "open_schematic", "args": { "filePath": "C:\\Users\\john\\project\\schematic.kicad_sch" } }

{
  "command": "install_library",
  "args": {
    "libraryPath": "C:\\Users\\john\\libs\\adom-test.kicad_sym",
    "libraryType": "symbol",
    "libraryName": "Adom Test Symbols"
  }
}

{ "command": "run_drc", "args": { "filePath": "C:\\Users\\john\\project\\board.kicad_pcb" } }

{
  "success": true,
  "violations": [
    {
      "severity": "error",
      "message": "Clearance violation (0.15mm < 0.2mm)",
      "location": "U1 pad 3"
    }
  ]
}

import pcbnew  # PCB editor API

# Get current board
board = pcbnew.GetBoard()

# Access footprints, tracks, zones, etc.
for footprint in board.GetFootprints():
    ref = footprint.GetReference()
    pos = footprint.GetPosition()

# Run DRC
drc = pcbnew.DRC()
drc.Run()
markers = board.GetMarkers()

POST http://localhost:8772/command
Content-Type: application/json

{
  "command": "open_board",
  "args": { "filePath": "C:\\..." }
}

{ "success": true }

adom-kicad-bridge open_board --file "C:\Users\john\project\board.kicad_pcb"

kicad-cli pcb drc --output report.json board.kicad_pcb
kicad-cli sym export svg --output /tmp/sym.svg symbol.kicad_sym

(kicad_symbol_lib
  (version 20231120)
  (generator "adom")
  (symbol "ADOM_MCU"
    (pin_names (offset 1.016))
    (exclude_from_sim no)
    (in_bom yes)
    (on_board yes)
    (property "Reference" "U"
      (at 0 10.16 0)
      (effects (font (size 1.27 1.27)))
    )
    (property "Value" "ADOM_MCU"
      (at 0 -10.16 0)
      (effects (font (size 1.27 1.27)))
    )
    (property "Footprint" ""
      (at 0 0 0)
      (effects (font (size 1.27 1.27)) hide)
    )
    (property "Datasheet" ""
      (at 0 0 0)
      (effects (font (size 1.27 1.27)) hide)
    )
    (property "Description" "Adom Test MCU Symbol"
      (at 0 0 0)
      (effects (font (size 1.27 1.27)) hide)
    )
    (symbol "ADOM_MCU_0_1"
      (rectangle
        (start -7.62 8.89)
        (end 7.62 -8.89)
        (stroke (width 0.254) (type default))
        (fill (type background))
      )
    )
    (symbol "ADOM_MCU_1_1"
      (pin input line (at -10.16 6.35 0) (length 2.54) (name "VCC") (number "1"))
      (pin input line (at -10.16 3.81 0) (length 2.54) (name "GND") (number "2"))
      (pin bidirectional line (at -10.16 1.27 0) (length 2.54) (name "SDA") (number "3"))
      (pin bidirectional line (at -10.16 -1.27 0) (length 2.54) (name "SCL") (number "4"))
      (pin output line (at 10.16 6.35 180) (length 2.54) (name "TX") (number "5"))
      (pin input line (at 10.16 3.81 180) (length 2.54) (name "RX") (number "6"))
      (pin bidirectional line (at 10.16 1.27 180) (length 2.54) (name "GPIO0") (number "7"))
      (pin bidirectional line (at 10.16 -1.27 180) (length 2.54) (name "GPIO1") (number "8"))
    )
  )
)

# Build the Adom Desktop KiCad Plugin

> **Historical design doc — captured from the original brief that bootstrapped this plugin. Terminology here predates the current naming: what's now called "Adom Desktop" was originally called the "Adom Desktop" (and the WebSocket relay was the "Adom Relay Server"). The implementation has since shipped; this doc is kept as design provenance, not as current API reference. For the live API, see [`SKILL.md`](SKILL.md) and the bridge SDK at <https://wiki.adom.inc/adom/adom-desktop-bridges>.**

## What We're Building

A KiCad plugin (VS Code extension or standalone) that integrates KiCad with the Adom platform. The architecture has three layers:

1. **Adom Relay Server** — a WebSocket server running in a remote Docker container (already built, you don't touch this)
2. **Adom Desktop** — a Tauri app running on this Windows desktop (already built, this is the bridge)
3. **KiCad Plugin** — what you're building. It receives commands from the Adom Desktop and controls KiCad

The flow is:
```
Cloud (Claude Code) → Adom Relay Server (Docker, WebSocket) → Adom Desktop (Tauri, Windows) → KiCad Plugin → KiCad
```

## How Commands Reach the Plugin

The Adom Desktop (Tauri app, already running) receives `command` messages from the WebSocket server with `"app": "kicad"`. Currently, the Adom Desktop doesn't know how to execute KiCad commands — it needs your plugin to handle them.

There are two architecture options for how the Adom Desktop talks to the KiCad Plugin:

### Option A: KiCad Action Plugin (Python, runs inside KiCad)
- A Python plugin that registers as a KiCad "Action Plugin"
- Runs a local HTTP or WebSocket server inside KiCad's Python environment
- The Adom Desktop connects to this local server to send commands
- Has full access to KiCad's Python scripting API (pcbnew, eeschema)
- KiCad 9 also has an IPC API (JSON-RPC over Unix socket / named pipe)

### Option B: External automation via KiCad CLI + IPC
- A standalone program (Node.js, Python, or Rust) that the Adom Desktop invokes
- Uses `kicad-cli` for file operations and KiCad 9's IPC API for controlling the running instance
- Doesn't require a plugin installed in KiCad itself
- May have less control over the running KiCad UI

### Recommended: Hybrid approach
Use KiCad 9's IPC API when KiCad is running (for interactive control like opening files, navigating), and fall back to `kicad-cli` for batch operations (DRC, export, library management).

## KiCad Commands to Support

These are the commands the Adom Desktop will forward to your plugin. Each arrives as a JSON message:

```json
{
  "app": "kicad",
  "command": "<command_name>",
  "args": { ... }
}
```

### 1. `open_board`
Open a PCB board file in KiCad's PCB editor.
```json
{ "command": "open_board", "args": { "filePath": "C:\\Users\\john\\project\\board.kicad_pcb" } }
```
Expected response: `{ "success": true }` or `{ "success": false, "error": "File not found" }`

### 2. `open_schematic`
Open a schematic file in KiCad's schematic editor.
```json
{ "command": "open_schematic", "args": { "filePath": "C:\\Users\\john\\project\\schematic.kicad_sch" } }
```

### 3. `install_library`
Install a symbol, footprint, or 3D model library into KiCad.
```json
{
  "command": "install_library",
  "args": {
    "libraryPath": "C:\\Users\\john\\libs\\adom-test.kicad_sym",
    "libraryType": "symbol",
    "libraryName": "Adom Test Symbols"
  }
}
```
`libraryType` is one of: `"symbol"`, `"footprint"`, `"3dmodel"`
`libraryName` is optional — use the filename if not provided.

For symbol libraries, add to KiCad's symbol library table (`sym-lib-table`).
For footprint libraries, add to the footprint library table (`fp-lib-table`).

### 4. `run_drc`
Run a Design Rule Check on a PCB board file.
```json
{ "command": "run_drc", "args": { "filePath": "C:\\Users\\john\\project\\board.kicad_pcb" } }
```
If `filePath` is omitted, run DRC on the currently open board.

Expected response includes violations:
```json
{
  "success": true,
  "violations": [
    {
      "severity": "error",
      "message": "Clearance violation (0.15mm < 0.2mm)",
      "location": "U1 pad 3"
    }
  ]
}
```

## File Transfer Context

Before KiCad commands arrive, the Adom Desktop may receive `send_files` messages containing KiCad files (symbols, footprints, board files). These are base64-decoded and saved to a local directory. The subsequent `open_board`, `open_schematic`, or `install_library` command will reference the saved file path.

The Adom Desktop handles file saving — your plugin just needs to work with local file paths.

## KiCad 9 IPC API Reference

KiCad 9 introduced a JSON-RPC IPC API for external control:

- **Transport**: Unix domain socket (Linux/macOS) or named pipe (Windows)
- **Socket path (Windows)**: `\\.\pipe\kicad-<pid>` or discoverable via KiCad's lock files
- **Protocol**: JSON-RPC 2.0
- **Available when**: KiCad is running with an open project

Key IPC capabilities:
- Open/close documents
- Get board/schematic data
- Run DRC/ERC
- Place components, draw traces
- Export files (Gerber, PDF, SVG)

Check KiCad's developer documentation for the full IPC API reference:
https://dev-docs.kicad.org/en/apis-and-binding/ipc/

## KiCad Python Scripting API

If building a KiCad Action Plugin, you have access to:

```python
import pcbnew  # PCB editor API

# Get current board
board = pcbnew.GetBoard()

# Access footprints, tracks, zones, etc.
for footprint in board.GetFootprints():
    ref = footprint.GetReference()
    pos = footprint.GetPosition()

# Run DRC
drc = pcbnew.DRC()
drc.Run()
markers = board.GetMarkers()
```

For the schematic editor, KiCad 9 has `eeschema` Python bindings, though they're more limited.

## Integration with the Adom Desktop

The Adom Desktop (Tauri app) needs a way to call your plugin. Define a clear interface:

### Option 1: Local HTTP Server (recommended for Action Plugin)
Your KiCad plugin starts a local HTTP server (e.g., port 8772) that accepts POST requests:

```
POST http://localhost:8772/command
Content-Type: application/json

{
  "command": "open_board",
  "args": { "filePath": "C:\\..." }
}
```

Response:
```json
{ "success": true }
```

The Adom Desktop would be updated to forward KiCad commands to `http://localhost:8772/command`.

### Option 2: CLI Wrapper
A command-line tool that the Adom Desktop invokes:
```
adom-kicad-bridge open_board --file "C:\Users\john\project\board.kicad_pcb"
```

### Option 3: Direct KiCad CLI
For some operations, use `kicad-cli` directly:
```
kicad-cli pcb drc --output report.json board.kicad_pcb
kicad-cli sym export svg --output /tmp/sym.svg symbol.kicad_sym
```

## What to Build First (MVP)

1. **Detect KiCad installation** — find the KiCad executable and version on Windows
2. **Open files** — implement `open_board` and `open_schematic` by launching KiCad with the file path, or via IPC if KiCad is already running
3. **Install library** — modify KiCad's `sym-lib-table` or `fp-lib-table` to add new libraries
4. **Run DRC** — use `kicad-cli pcb drc` to run DRC and parse results, or use IPC API

## Environment Details

- **OS**: Windows (the desktop machine is "AdomLapper", Windows, x86_64)
- **KiCad version**: Should detect automatically, but targeting KiCad 9.x
- **Adom Desktop**: Tauri 2.10 app, already connects to the cloud relay server
- **This VS Code instance**: Running on the Windows desktop alongside KiCad

## Sample KiCad Symbol for Testing

Here's a simple test symbol (ADOM_MCU, 8-pin) you can use to test library installation:

```
(kicad_symbol_lib
  (version 20231120)
  (generator "adom")
  (symbol "ADOM_MCU"
    (pin_names (offset 1.016))
    (exclude_from_sim no)
    (in_bom yes)
    (on_board yes)
    (property "Reference" "U"
      (at 0 10.16 0)
      (effects (font (size 1.27 1.27)))
    )
    (property "Value" "ADOM_MCU"
      (at 0 -10.16 0)
      (effects (font (size 1.27 1.27)))
    )
    (property "Footprint" ""
      (at 0 0 0)
      (effects (font (size 1.27 1.27)) hide)
    )
    (property "Datasheet" ""
      (at 0 0 0)
      (effects (font (size 1.27 1.27)) hide)
    )
    (property "Description" "Adom Test MCU Symbol"
      (at 0 0 0)
      (effects (font (size 1.27 1.27)) hide)
    )
    (symbol "ADOM_MCU_0_1"
      (rectangle
        (start -7.62 8.89)
        (end 7.62 -8.89)
        (stroke (width 0.254) (type default))
        (fill (type background))
      )
    )
    (symbol "ADOM_MCU_1_1"
      (pin input line (at -10.16 6.35 0) (length 2.54) (name "VCC") (number "1"))
      (pin input line (at -10.16 3.81 0) (length 2.54) (name "GND") (number "2"))
      (pin bidirectional line (at -10.16 1.27 0) (length 2.54) (name "SDA") (number "3"))
      (pin bidirectional line (at -10.16 -1.27 0) (length 2.54) (name "SCL") (number "4"))
      (pin output line (at 10.16 6.35 180) (length 2.54) (name "TX") (number "5"))
      (pin input line (at 10.16 3.81 180) (length 2.54) (name "RX") (number "6"))
      (pin bidirectional line (at 10.16 1.27 180) (length 2.54) (name "GPIO0") (number "7"))
      (pin bidirectional line (at 10.16 -1.27 180) (length 2.54) (name "GPIO1") (number "8"))
    )
  )
)
```

## Success Criteria

When done, the cloud Claude Code should be able to:
1. Call `kicad_open_board` via MCP → Adom Relay Server → Adom Desktop → your plugin → KiCad opens the file
2. Call `kicad_install_library` → a new symbol library appears in KiCad's library manager
3. Call `kicad_run_drc` → DRC results come back to Claude Code in the cloud

Start by figuring out the best way to detect and communicate with KiCad on this Windows machine, then build up from there.