claude-kicad-helper/README.md

# claude-kicad-helper

A command-line query tool for KiCad project files, designed to extract
focused, readable information from files that are otherwise too large to
work with directly.

## Why this exists

KiCad stores schematics (`.kicad_sch`) and PCB layouts (`.kicad_pcb`) as
S-expression trees that easily run to thousands of lines. Most of that bulk
is graphical metadata — line coordinates, font sizes, courtyard polygons —
that is irrelevant when you want to answer questions like:

- What components are on this board and what are their values?
- Which nets exist in this schematic?
- What copper traces physically connect to pin 1 of R5?

`kicad-query.mjs` parses the file, extracts structured data, and prints
only what was asked for — either as a human-readable table or as JSON for
programmatic/LLM consumption.

## Architecture

```mermaid
flowchart TD
    A["tokenize(text)"] --> B["parse_sexp(text)\n{ tag, items[] } tree"]
    B --> C["run_query(ext, query, root, args)\nfile-type + query dispatch"]
    C --> D["plain data object"]
    D --> E["render_human(ext, query, data)\nformatted tables for terminal"]
    D --> F["render_json(data)\nJSON.stringify for LLM / scripts"]
```

Query functions are pure data transformers — no I/O, no format awareness.
Adding a new output format only requires a new renderer.

## Installation

```
npm install -g git+https://gitea.efforting.tech/mikael-lovqvists-claude-agent/claude-kicad-helper.git
```

If you don't have write access to the global `node_modules` (e.g. in a
container or without sudo), install to your home directory instead:

```
npm install -g --prefix ~/.local git+https://gitea.efforting.tech/mikael-lovqvists-claude-agent/claude-kicad-helper.git
```

Make sure `~/.local/bin` is on your `PATH`. Requires Node.js 18+, no other
dependencies.

## Usage

```
kicad-query [--format=json] <file> <query> [args...]
```

Or without installing, directly via node:

```
node kicad-query.mjs [--format=json] <file> <query> [args...]
```

## Queries

### Schematic (`.kicad_sch`)

| Query | Description |
|-------|-------------|
| `summary` | Component counts, wire count, libraries used |
| `components` | Table of all placed components (ref, value, footprint) |
| `components ref=U*` | Filter by reference glob |
| `components value=100nF` | Filter by value glob |
| `component U1` | All properties and pins of one component |
| `nets` | All net names (local labels, global labels, power nets) |

### PCB (`.kicad_pcb`)

| Query | Description |
|-------|-------------|
| `summary` | Net, footprint, segment, via, zone counts |
| `nets` | All nets with their numeric IDs |
| `net GND` | Which pads are connected to a named net |
| `footprints` | Table of all footprints |
| `footprint R5` | Position, layer, value, pad→net table for one footprint |
| `traces R5 1` | BFS through segments and vias from pad 1 of R5 |

### Project (`.kicad_pro`)

| Query | Description |
|-------|-------------|
| `summary` | Filename, version, min clearance, section list |

### Generic (any file)

| Query | Description |
|-------|-------------|
| `tags` | All S-expression tag names sorted by frequency — useful for exploration |
| `raw <tag>` | Dump all nodes with a given tag name |

---

## Examples — human output

```
$ node kicad-query.mjs sketch.kicad_sch summary
=== Schematic Summary ===
Components   : 26
Power symbols: 14
Net labels   : 0
Global labels: 16
Wires        : 102

Libraries:
  Amplifier_Operational: 1
  Connector: 4
  Device: 16
  Mechanical: 4
```

```
$ node kicad-query.mjs sketch.kicad_sch components
Reference  Value             Library:Symbol               Footprint
---------  -----             --------------               ---------
C1         100 nF            Device:C                     Capacitor_SMD:C_0603_1608Metric
C5         100 µF            Device:C_Polarized           Capacitor_SMD:CP_Elec_6.3x4.5
R4         100 mΩ            Device:R                     Resistor_SMD:R_1206_3216Metric
U1         LM358             Amplifier_Operational:LM358  Package_SO:SO-8_3.9x4.9mm_P1.27mm
...
```

```
$ node kicad-query.mjs sketch.kicad_sch nets
=== Net Names (10 total) ===
  BIAS  [global]
  Current Measurement  [global]
  GND  [power]
  SUPPLY  [global]
  VDD  [power]
  Voltage Reference  [global]
  ...
```

```
$ node kicad-query.mjs sketch.kicad_pcb traces R5 1
=== Traces from R5 pad 1 ===
Net        : Current Reference (id=12)
Position   : (148.645, 64.350)
Pad layers : F.Cu

Layer B.Cu — 2 segment(s):
  From (x, y)           To (x, y)             Width
  (153.162,  74.168)  → (153.670,  73.660)    0.4mm
  (153.162,  81.026)  → (153.162,  74.168)    0.4mm

Layer F.Cu — 9 segment(s):
  ...

Vias (2):
  (153.670, 73.660)  F.Cu ↔ B.Cu
  (153.162, 81.026)  F.Cu ↔ B.Cu
```

---

## Examples — JSON / LLM output

Add `--format=json` before the filename. All queries produce the same data;
only the presentation changes.

```
$ node kicad-query.mjs --format=json sketch.kicad_sch components
{
  "components": [
    {
      "ref": "C1",
      "value": "100 nF",
      "footprint": "Capacitor_SMD:C_0603_1608Metric",
      "lib_id": "Device:C",
      "datasheet": "~",
      "dnp": false
    },
    ...
  ]
}
```

```
$ node kicad-query.mjs --format=json sketch.kicad_pcb traces R5 1
{
  "ref": "R5",
  "pad": "1",
  "net": { "id": 12, "name": "Current Reference" },
  "position": { "x": 148.645, "y": 64.35 },
  "pad_layers": ["F.Cu"],
  "traces": [
    { "layer": "F.Cu", "start": { "x": 149.225, "y": 64.35 }, "end": { "x": 148.645, "y": 64.35 }, "width": 0.4 },
    ...
  ],
  "vias": [
    { "position": { "x": 153.670, "y": 73.660 }, "layers": ["F.Cu", "B.Cu"] }
  ]
}
```

When feeding KiCad data to an LLM, prefer `--format=json` with targeted
queries over pasting raw file contents. A 6000-line schematic collapses to
a few hundred bytes of component and net data.