{"id":51061823,"url":"https://github.com/bleugreen/ksch","last_synced_at":"2026-06-23T03:01:08.178Z","repository":{"id":356013329,"uuid":"1230427836","full_name":"bleugreen/ksch","owner":"bleugreen","description":"text-first schematic compiler for KiCad","archived":false,"fork":false,"pushed_at":"2026-05-22T01:54:37.000Z","size":1570,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T10:01:26.616Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bleugreen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T01:45:25.000Z","updated_at":"2026-05-22T00:45:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bleugreen/ksch","commit_stats":null,"previous_names":["bleugreen/ksch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bleugreen/ksch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bleugreen%2Fksch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bleugreen%2Fksch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bleugreen%2Fksch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bleugreen%2Fksch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bleugreen","download_url":"https://codeload.github.com/bleugreen/ksch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bleugreen%2Fksch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34673437,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-23T03:01:07.216Z","updated_at":"2026-06-23T03:01:08.162Z","avatar_url":"https://github.com/bleugreen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ksch\n\nText-first schematic compiler for KiCad projects.\n\n`ksch` turns canonical YAML schematic schemas into deterministic KiCad\nprojects. The schema owns symbols, refs, values, fields, footprints, pins, nets,\nno-connects, power flags, sheet interfaces, and hierarchy. KiCad `.kicad_sch`\nfiles are generated output.\n\nThe package includes:\n\n- a CLI for local authoring and generation\n- a schema importer for existing KiCad projects\n- KiCad symbol and footprint library indexing\n- project-aware library discovery and diagnostics\n- endpoint resolution and schema validation\n- generated-file drift checks, KiCad ERC checks, and netlist parity checks\n- a layout/compiler pipeline that emits KiCad schematic files\n- a thin MCP adapter for agent-assisted workflows\n- a bundled Codex skill for using the tool in other projects\n\n## Install\n\nFrom a checkout:\n\n```bash\nuv sync\nuv run ksch --help\n```\n\nAs a local CLI tool:\n\n```bash\nuv tool install .\nksch --help\n```\n\nSome operations, including KiCad import and netlist-based roundtrip checks,\nrequire `kicad-cli` on `PATH`.\n\n## Quick Start\n\nCreate a new schema-owned KiCad project:\n\n```bash\nksch init my-board\ncd my-board\nksch gen\n```\n\nThis creates:\n\n```text\nmy-board/\n  ksch.toml\n  schematic/project.ksch.yaml\n  schematic/lib/Starter.kicad_sym\n  scripts/gen-schematic.sh\n  kicad/\n```\n\n`ksch.toml` records the project contract:\n\n```toml\nschema = \"schematic/project.ksch.yaml\"\nout = \"kicad\"\n```\n\nGenerate from the project root with `ksch gen`. Verify the generated KiCad\nproject with `ksch verify`.\n\n## Import Existing KiCad\n\nRun `ksch init` inside an existing KiCad project:\n\n```bash\ncd existing-board\nksch init\nksch gen\n```\n\nIf the directory contains one KiCad root schematic, `ksch init` offers to import\nit. The imported schema is written to `ksch/project.ksch.yaml`; generation\ntargets the existing KiCad project directory:\n\n```toml\nschema = \"ksch/project.ksch.yaml\"\nout = \".\"\n```\n\nThat means `ksch gen` updates the actual schematic project. There is no separate\ngenerated copy to hand-copy back into KiCad.\n\n`ksch init` also detects the common repo shape where the current directory has\none immediate child KiCad project. In that case `out` points at that child\nproject directory.\n\n## CLI\n\nCommon commands:\n\n```bash\nksch init\nksch gen\nksch verify\nksch doctor\nksch check\nksch validate schematic/project.ksch.yaml\nksch fmt schematic/project.ksch.yaml\nksch schema show\nksch explain U1.USBDP_UP\nksch compile schematic/project.ksch.yaml --out kicad\nksch import board.kicad_sch --out ksch\nksch symbols search USB\nksch symbol info Device:R\nksch pin-search Connector:USB_C_Receptacle_USB2.0 D+\nksch skill show\n```\n\n`ksch gen`, bare `ksch verify`, bare `ksch check`, `ksch doctor`, and the\nauthoring lookup commands read `ksch.toml`. Explicit `compile` and `import`\ncommands are still available for scripts and one-off conversions.\n\nSee [docs/cli.md](docs/cli.md) for command details.\n\n## Schema\n\nThe schema is YAML. A root document has `project`; child sheets have `sheet`.\n\n```yaml\nksch: 1\nproject:\n  name: usb-demo\n\nlibraries:\n  symbols:\n    project:\n      Local: lib/Local.kicad_sym\n\nsymbols:\n  J1:\n    lib: Connector:USB_C_Receptacle_USB2.0_16P\n    value: USB_IN\n    connects:\n      D+@A6: USB_D_P\n      D+@B6: USB_D_P\n      GND/all: GND\n  U1:\n    lib: Interface_USB:USB2514B\n    value: USB2514B\n    footprint: Package_QFN:QFN-36-1EP_6x6mm_P0.5mm\n    connects:\n      USBDP_UP: USB_D_P\n      GND/all: GND\n```\n\nSymbol-local connection keys use pin names. Use `@pin_number` when a symbol has\nduplicate pin names and only one physical pin is connected. Use `/all` when all\npins with that name are connected.\n\nProject-local KiCad libraries can be declared in the schema:\n\n```yaml\nlibraries:\n  symbols:\n    project:\n      MyParts: lib/MyParts.kicad_sym\n  footprints:\n    project:\n      MyFootprints: lib/MyFootprints.pretty\n```\n\nSee [docs/schema-v1.md](docs/schema-v1.md) for the schema reference.\n\n## Authoring Workflow\n\nUse the library lookup commands before writing endpoints for unfamiliar parts:\n\n```bash\nksch symbols search USB2514\nksch symbol info Interface_USB:USB2514B\nksch pin-search Interface_USB:USB2514B USBDP\nksch explain U1.USBDP_UP\n```\n\nInside a configured project, lookup commands use schema-declared libraries,\n`ksch.toml` extra libraries, and generated KiCad library tables automatically.\nUse `--library NICK=PATH` only for one-off extra libraries.\n\nUse `ksch schema show` to print the canonical JSON Schema for editor\nconfiguration and external tooling.\n\nThe compiler validates symbol library ids, endpoint references, duplicate pin\ndisambiguation, sheet ports, and no-connect endpoints before writing KiCad\noutput.\n\nEdit `.ksch.yaml` directly as the normal authoring workflow, then validate and\nverify:\n\n```bash\nksch validate schematic/project.ksch.yaml\nksch gen\nksch verify\n```\n\nThe package also contains a structured edit core for tool, agent, and future\nsemantic refactor operations. That layer validates candidate changes before\nwriting, resolves aggregate endpoint expressions such as `/all` to physical pin\nkeys, and rejects connected no-connect endpoints. It is not the primary human\nauthoring interface.\n\nFor agent environments, print the bundled skill:\n\n```bash\nksch skill show\n```\n\nThat output is a compact `SKILL.md` covering the project workflow, schema\nconventions, and common fixes.\n\n## Generated Layout\n\n`ksch` emits complete KiCad schematic files, including symbols, labels, wires,\njunctions, hierarchical sheets, power flags, no-connects, library tables, and\nproject files.\n\nThe layout pipeline uses KiCad symbol geometry, pin positions, net graph\nstructure, component refs, local two-pin topology, and sheet structure. It keeps\nlocal support passives near the pins they support, routes compact local nets\ndirectly, uses labels for long-range connectivity, and checks for avoidable\nsymbol/text/wire overlaps before emission.\n\nThe generated schematic is meant to be usable and deterministic. Manual cleanup\nin KiCad becomes drift unless it is imported back into schema.\n\n## Verification\n\nUseful verification commands:\n\n```bash\nksch doctor\nksch verify\nksch verify --against path/to/original.kicad_sch --artifacts .ksch-verify\nuv run pre-commit install\nuv run pre-commit run --all-files\n./scripts/test.sh\n./scripts/check.sh\n```\n\n`ksch verify` compiles the configured schema, runs KiCad ERC on the generated\nroot schematic, and compares generated files against the configured output. Use\n`--against` to compare generated netlist connectivity against an existing KiCad\nroot schematic. Use `--artifacts` to keep the generated verification project,\nERC report, and netlists for inspection.\n\nThe pre-commit hooks run `ruff`, `mypy`, and a fast CLI/package test slice.\n`./scripts/test.sh` runs the full test suite. `./scripts/check.sh` runs the\nfull local gate: lint, typecheck, tests, and package build.\n\nThe test suite includes KiCad CLI integration tests where `kicad-cli` is\navailable, importer roundtrip smoke tests, layout tests, and package build\ncoverage. Run `ksch validate`, `ksch gen`, and `ksch verify` inside generated\nprojects while dogfooding schemas.\n\n## Examples And Docs\n\n- [Basic board example](examples/basic-board)\n- [CLI reference](docs/cli.md)\n- [Schema v1 reference](docs/schema-v1.md)\n- [Compiler design spec](docs/superpowers/specs/2026-04-27-kicad-schema-compiler-design.md)\n\n## Architecture\n\nThe implementation is split into compiler stages:\n\n```text\nschema loader -\u003e source model -\u003e project IR -\u003e resolver\n  -\u003e placement/routing/layout validation -\u003e KiCad emitter\n```\n\nImportant modules:\n\n- `ksch.schema`: YAML loading and formatting\n- `ksch.model`: source and IR models\n- `ksch.kicad`: KiCad library, symbol, footprint, and S-expression helpers\n- `ksch.resolver`: endpoint and net resolution\n- `ksch.graph`, `ksch.edit`: project graph indexing and structured schema edits\n- `ksch.placement`, `ksch.net_routing`, `ksch.layout_problem`: schematic layout\n- `ksch.compiler`: placed-project construction and generation orchestration\n- `ksch.emit`: serialization of placed objects to KiCad files\n- `ksch.importer`: KiCad schematic to schema conversion\n- `ksch.verify`: generated output and netlist comparison\n- `ksch.mcp`: optional agent-facing adapter\n\nThe MCP server is an adapter over the same package used by the CLI. The compiler\nand CLI work without an agent session.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbleugreen%2Fksch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbleugreen%2Fksch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbleugreen%2Fksch/lists"}