kajiya

KiCad schematic manipulation toolkit. Parse, convert, render, and generate KiCad schematics through a format-agnostic intermediate representation (IR).

Quick Start

go install git.lan.thwap.org/thwap/kajiya/cmd/kajiya@latest
kajiya version

Features

• Parse KiCad .kicad_sch files to an intermediate IR
• Convert between IR formats: YAML, JSON, TOML
• Generate KiCad schematics from IR documents
• Render schematics to console (ANSI/UTF-8 text) or SVG
• Diff two schematics for version control workflows
• Validate IR documents for structural correctness
• Annotate auto-assign reference designators

Commands

Command	Description
convert	KiCad schematic → YAML/JSON/TOML
generate	YAML/JSON/TOML → KiCad schematic
render	Schematic → console/SVG output
diff	Compare two schematics
validate	Validate IR document
completion	Generate shell completions

Installation

go install

go install git.lan.thwap.org/thwap/kajiya/cmd/kajiya@latest

From source

git clone https://git.lan.thwap.org/thwap/kajiya.git
cd kajiya
go build ./cmd/kajiya

Pre-built binaries

See releases for Linux, macOS, and Windows binaries.

Docker

docker run --rm -v "$PWD:/work" ghcr.io/thwap/kajiya render -i /work/schematic.kicad_sch

Tutorial: Convert, Edit, Regenerate

1. Convert KiCad schematic to YAML

kajiya convert -i schematic.kicad_sch -o design.yaml
kajiya convert -i schematic.kicad_sch -o design.json
kajiya convert -i schematic.kicad_sch -o design.toml

2. Edit the YAML

Modify component values, footprints, net names, or add components. Example: change a resistor value from 10k to 47k.

components:
  - reference: R1
    value: 47k

3. Regenerate the KiCad schematic

kajiya generate -i design.yaml -o updated.kicad_sch

4. Round-trip verification

kajiya convert -i updated.kicad_sch -o roundtrip.yaml
kajiya diff --left design.yaml --right roundtrip.yaml

Tutorial: Render to Console

Quickly inspect a schematic without launching KiCad:

kajiya render -i schematic.kicad_sch -f console
kajiya render -i schematic.kicad_sch -f console --no-color | less
kajiya render -i schematic.kicad_sch -f console --width 120 --height 60

Render to SVG

kajiya render -i schematic.kicad_sch -f svg -o schematic.svg
kajiya render -i design.yaml -f svg --width 1024 --height 768

CI/CD Integration

Lint schematics in CI

kajiya validate -i schematic.kicad_sch
kajiya validate -i design.yaml
if ! kajiya validate -i schematic.kicad_sch --quiet; then
    echo "Schematic validation failed"
    exit 1
fi

Auto-annotate in CI

kajiya generate -i design.yaml -o annotated.kicad_sch
kajiya diff --left design.yaml --right annotated.kicad_sch

Git diff for schematics

Add to .gitattributes:

*.kicad_sch diff=kicad

Add to .git/config or ~/.gitconfig:

[diff "kicad"]
    textconv = kajiya convert -i

Now git diff for .kicad_sch files shows human-readable YAML diffs.

Shell Completions

# Bash
source <(kajiya completion bash)

# Zsh
source <(kajiya completion zsh)

# Fish
kajiya completion fish | source

Project Structure

cmd/kajiya/         CLI entry point
internal/ir/        IR model types and serialization
internal/parser/    KiCad schematic parser and writer
internal/render/    Console and SVG renderers
internal/sexpr/     S-expression scanner and parser
internal/errors/    Centralized error handling
schema/             JSON Schema for IR
testdata/           Test fixtures

Performance

Typical performance on a mid-range machine:

• Parse 100-component schematic: ~50ms
• Convert to YAML/JSON: ~10ms
• Generate KiCad output: ~20ms
• Console render: ~5ms
• SVG render: ~15ms

License

GPL-3.0