---
name: kicad-to-markdown
author: Noah
description: Use when the user wants to "parse a KiCad project", "convert KiCad to markdown", "understand a KiCad schematic", "extract netlist", "analyze a .kicad_sch", "what's in this KiCad project", or wants an AI-readable summary of a KiCad project's components, connectivity, and PCB layout.
---

# KiCad to Markdown Parser

Parses KiCad projects into structured markdown documents optimized for AI consumption. Extracts components, netlist connectivity, hierarchical sheets, PCB layout, board outline, traces, vias, zones, design rules, and net classes.

## Service Location

```
/home/adom/project/kicad-to-markdown/
```

## Dependencies

Already installed. If missing, run:

```bash
pip install --break-system-packages -r /home/adom/project/kicad-to-markdown/requirements.txt
```

Requires: `kiutils`, `fastapi`, `uvicorn`, `python-multipart`, `click`.

## Usage

### Option 1: CLI (preferred for local files)

Parse a project directory:

```bash
cd /home/adom/project/kicad-to-markdown
python3 cli.py /path/to/kicad/project/
```

Parse a zip file:

```bash
cd /home/adom/project/kicad-to-markdown
python3 cli.py /path/to/project.zip
```

Save output to a file:

```bash
cd /home/adom/project/kicad-to-markdown
python3 cli.py /path/to/project.zip -o /home/adom/project/output.md
```

### Option 2: HTTP API (for remote uploads)

Start the server:

```bash
cd /home/adom/project/kicad-to-markdown
~/.local/bin/uvicorn server:app --host 0.0.0.0 --port 8000 &
```

Upload a zip and get markdown back:

```bash
curl -F "[email protected]" http://localhost:8000/parse
```

Upload and get JSON response (includes stats):

```bash
curl -F "[email protected]" http://localhost:8000/parse/json
```

Health check:

```bash
curl http://localhost:8000/health
```

## Workflow

### Step 1: Locate the KiCad Project

Find the user's KiCad project. It can be:
- A directory containing `.kicad_pro`, `.kicad_sch`, `.kicad_pcb` files
- A `.zip` archive of such a directory
- A single `.kicad_pro` file (the parser discovers sibling files)

```bash
find /home/adom/project -name "*.kicad_pro" -o -name "*.zip" | head -20
```

### Step 2: Run the Parser

```bash
cd /home/adom/project/kicad-to-markdown
python3 cli.py <INPUT_PATH> -o /home/adom/project/<PROJECT_NAME>.md
```

### Step 3: Review the Output

Read the generated markdown and summarize it for the user. Key sections to highlight:

- **Overview** — component count, net count, board dimensions, layer count
- **Components** — table of all parts with reference, value, footprint, description
- **Connectivity** — the netlist showing which pins connect to which nets
- **Power Nets** — which components connect to each power rail
- **Hierarchical Sheets** — sub-sheet structure and interface pins
- **PCB Layout** — board outline, layer stackup, component placement, routing summary
- **Design Rules** — net classes with clearance and trace width settings

## What Gets Parsed

| File Type | Data Extracted |
|-----------|---------------|
| `.kicad_pro` | Project name, net class definitions, design settings |
| `.kicad_sch` | Components, net labels, power symbols, wires, hierarchical sheets, netlist connectivity |
| `.kicad_pcb` | Footprints, traces, vias, zones, board outline, layer stackup, design rules |

### Netlist Algorithm

The schematic parser builds the netlist by:
1. Tracing wires between component pin positions and endpoints
2. Using a union-find data structure to group connected points
3. Resolving net names from local labels, global labels, hierarchical labels, and power symbols
4. Handling labels that sit on wire segments (not just at endpoints)
5. Transforming library symbol pin coordinates (Y-up) to schematic coordinates (Y-down) with rotation and mirror support

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| 0 components found | Schematic file uses a format kiutils can't parse, or the `.kicad_sch` is corrupted | Check that KiCad 6+ format is used. Open and re-save in KiCad. |
| Deleted components still appear | KiCad leaves ghost symbols in the file after visual deletion | Re-save the schematic in KiCad's editor to purge orphaned symbols |
| Nets show wrong pin assignments | Pin position transformation error (rotation/mirror) | Check if the symbol uses non-standard pin placement. File an issue. |
| Labels not resolving to net names | Label position doesn't sit on a wire endpoint or segment | Move the label in KiCad so it snaps to a wire |
| `kiutils` import error | Package not installed | Run `pip install --break-system-packages kiutils` |
| Zip upload returns 400 | File is not a valid zip, or contains no KiCad files | Verify the zip contains `.kicad_pro`/`.kicad_sch` files |
| HTTP server won't start | Port 8000 already in use | Use a different port: `uvicorn server:app --port 8001` |