klayout-tools 0.2.0

Tools for AI agents to work with IC layout (GDSII/OASIS via KLayout)

klayout-tools

Tools for AI agents to work with IC layout.

🌐 klayout-tools.org — project site.

The kicad-tools playbook, one layer down the stack: standalone Python tools that let AI agents (LLMs, autonomous coding assistants) parse, analyze, and manipulate chip layouts — GDSII/OASIS streams, DRC decks, LVS — programmatically, headless, with machine-readable JSON everywhere. Built on KLayout's Python API the way kicad-tools builds on KiCad's file formats: the heavy lifting stays in the proven engine; the agent-native surface is ours.

The target capability: an agent can take a spec through one of three peer paths on an open PDK, unaided, with every step headless and JSON-contracted — analog (spec → schematic/generator → sized circuit → layout → DRC/LVS clean → extracted netlist → simulation-verified), digital (spec → RTL → synthesis → place-and-route → DRC/LVS clean → timing-closed), and mixed-signal (both paths plus the signoff seam between them). ROADMAP.md holds the build order, docs/ARCHITECTURE.md how the pieces fit; the work itself is tracked in GitHub issues.

Built in the open by 2AM Logic.

Why agent-focused?

Chip design tooling assumes a human at a GUI. klayout-tools provides what an agent needs instead:

• Structured data access — layouts parsed into clean Python objects
• Machine-readable output — every CLI command supports --format json
• Programmatic layout writing — generate and edit layouts without a GUI (klt gen, klt gen-compose, klt draw)
• MCP server (planned) — expose the toolkit directly to agent frameworks
• LLM reasoning interface (planned) — purpose-built module for layout decisions, with geometric execution handled by tools, not tokens

Status

Early alpha — v0.2.0 is on PyPI with all 24 verbs — see docs/cli/. The pattern is proven (see the kicad-tools gallery of boards designed end-to-end by agents); this repo is where it meets silicon. See ROADMAP.md for the build order and CLAUDE.md if you are an agent working here.

Install

uv tool install klayout-tools

Or with pip:

pip install klayout-tools

klt is now on PATH. For the latest development version, install from source instead:

uv tool install git+https://github.com/2AMLogic/klayout-tools

Quick start

klt layers design.gds                    # enumerate layers, JSON out
klt cells design.gds --top               # cell hierarchy
klt drc design.gds --deck sky130        # run a DRC deck, structured results
klt precheck design.gds --grid-um 0.005  # off-grid/zero-area/naming hygiene checks
klt ring-check design.gds --layers '[[22,0],[34,0]]'  # guard/tap ring is a closed annulus
klt stats design.gds --per-layer         # densities, bbox, polygon counts
klt pdk find --pdk sky130A               # locate an installed PDK, JSON out
klt render design.gds                    # per-layer PNGs, headless
klt sim request.json                     # SPICE PVT corner sweep (ngspice), JSON out
klt layout-metrics design.gds            # normalized layout.json per block
klt kb search bandgap                    # query the circuit-design knowledge base
klt gen resistor_strip --pdk sky130A     # generate a parametrized cell (headless PCell)
klt draw --params shapes.json -o out.gds # write a primitive stream (no rule checking)
klt extract design.gds --deck sky130     # layout -> schematic-equivalent netlist
klt lvs request.json                     # compare extracted vs reference netlist
klt synthesize request.json              # RTL -> gate-level netlist (Yosys), JSON out
klt place-and-route request.json         # netlist -> placed+routed DEF/GDS (OpenROAD), JSON out
klt functional-verification verify.json  # cocotb regression (Icarus/Verilator) -> pass/fail + coverage
klt eval descriptor.json --candidate '{"layout": "..."}'  # score a candidate: valid + one objective
klt gen-compose plan.json                # place + wire generated blocks into one circuit
klt socket-check design.gds --socket socket.json  # pins/outline/budgets vs a socket descriptor
klt lef-abstract design.gds --socket socket.json --macro-name m --cell-library sky130_fd_sc_hd  # layout+socket -> LEF MACRO abstract
klt report result.json                   # render a klt JSON report as markdown summary
klt trajectory run.jsonl --plot t.svg    # optimization trajectory -> milestone table + plot

Every verb is documented in docs/cli/, one page per verb. All 24 verbs ship in PyPI 0.2.0; the from-source install above tracks main, which may be ahead of the latest release.

Development

Dependencies are managed with uv; the klayout pip wheel provides the headless Python API (no GUI, no source build needed).

uv sync --locked --extra dev    # create/refresh .venv from uv.lock

uv run --extra dev ruff check .     # lint
uv run --extra dev pytest           # tests

npm run check:ci                    # lint + tests — the same gate CI runs

.github/workflows/ci.yml runs ruff check plus pytest on Python 3.10–3.13 for every pull request and every push to main, so a red check is the signal that a PR is not mergeable.

GitHub Action

Run klt in a downstream block repo's CI with a few lines of workflow YAML — action.yml at this repo's root installs klt, runs the verbs you choose against your layout, and publishes a step summary + JSON/render artifacts, exactly like a local klt invocation:

- uses: 2AMLogic/klayout-tools@v0.2.0
  with:
    layout: layout/my_block.gds
    verbs: drc,layout-metrics
    deck: sky130

See docs/guides/github-action.md for the full inputs/outputs reference and a complete worked example.

Guides

• Building KLayout from source on macOS — full walkthrough (Homebrew Qt6/Python/Ruby, build4mac.py, deploy, headless verification), tested on Apple Silicon with KLayout v0.30.10.
• The klt verify GitHub Action — reusable composite Action wrapping klt for downstream block repo CI: inputs, outputs, and a worked example.

Agent skills

Curated procedures (with reference data) that agents working in this repo load on demand:

• spec-review — expert-EE opinion on a block's draft target spec: per-line achievability against published best practice (open literature, cited), evidence checks against the repo's device characterization, block-class completeness and corner-binding checks, and a ratify / ratify-with-amendments / defer verdict. Worked example: examples/spec-review/.
• Staged design pipeline (S1–S6 + back-end) — one skill per stage of the design pipeline, from proposal intake through architecture partition, block spec, topology selection, sizing, and netlist authoring, plus the back-end stages (DRC/LVS, layout generation, extraction, and signoff — layout generation and extraction now run against shipped klt verbs; signoff remains a declared stub gated on the #309 aggregation tool).

Design notes

Spikes and engine surveys — proposals and findings, not commitments. Full index: docs/design/.

• Staged agent design pipeline — the spec-to-simulation-verified stage graph, per-stage input/output contracts, a vendor-neutral model-class matrix, and a gap map against today's klt verbs.
• SPICE PVT corner runner — ngspice vs. Xyce, a proposed JSON contract for sweeping a netlist across a corner matrix, and the wrap/build call.
• sc-leflib evaluation — whether siliconcompiler's LEF parser fills a gap that KLayout's own LEF/DEF reader leaves. Verdict: use pya, no new dependency.
• Mixed-signal co-simulation approach — RNM vs. ngspice XSPICE d_process vs. Verilog-AMS/VHDL-AMS, a proposed co-simulation JSON contract with an additive backend selector, and the recommendation: RNM for v1.

License

MIT. © 2026 Two AM Logic, Inc.