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 — klt mcp serve exposes every verb to agent frameworks over stdio, generated from the CLI registry (pip install 'klayout-tools[mcp]'; see the guide)
• LLM reasoning interface (planned) — purpose-built module for layout decisions, with geometric execution handled by tools, not tokens

Status

Early alpha — v0.5.0 is on PyPI (44 verbs at release; see docs/cli/ for the set). 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

klt yield (and its yield-campaign/yield-sensitivity siblings) need the yield extra. Both install commands above ship the pure-Python package only — klt yield's statistics run in a Rust extension (klt_yield_native), published as the prebuilt klt-yield-native wheel (Linux x86_64, macOS arm64). Install it with pip install 'klayout-tools[yield]' (or uv tool install 'klayout-tools[yield]'). The git-pinned form, other platforms, and any release that predates the first klt-yield-native publication still need a full repo checkout plus a Rust toolchain; see docs/cli/yield.md#building-the-native-extension. klt mom and klt synthesize --restructure-timing have the same from-source gap for their own Rust extensions; every other verb works from the commands above alone.

Container image (klt + the analog sim toolchain)

For CI or a worker node that needs the whole analog flow — klt plus ngspice, xschem and a PDK — this repo also publishes an overlay image:

docker run --rm ghcr.io/2amlogic/eda-sim klt --version

The toolchain is baked; the PDK is fetched at runtime (eda-sim-fetch-pdk sky130), never baked. See docker/eda-sim/README.md for the version pins and the full contract.

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 keepout-check design.gds --forbidden '[[67,20]]' --margin 10 --cells SPIRAL  # nothing on the forbidden layers within a margin of a cell
klt tap-distance design.gds --subject '65/20' --taps '65/44' --max-distance-um 15  # every diffusion point within a Euclidean distance of a tap
klt components design.gds --conductors '[{"name":"m1","layer":[68,20]}]'  # connected components, no deck
klt clip design.gds --cell SUBCELL -o subcell.gds  # write a bbox region or named cell's subtree out as its own stream
klt stats design.gds --per-layer         # densities, bbox, polygon counts
klt economy design.gds                   # utilization, whitespace map, bbox tightness, area-budget check
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 size request.json                    # gm/Id sizing (single device or coupled diff-pair+mirror+tail), ngspice-scored
klt yield mc.json --limits spec.json     # MC sample set + spec limits -> yield estimate with CIs, Cpk, sample-size verdict (Rust core)
klt yield-samples mc.json --negative-control bad.json --format json  # two MC sim reports -> yield sample set carrying a negative control
klt yield-csv trials.csv --group-by metric --value result --format json  # per-draw MC CSV -> yield sample set (hash-citable)
klt yield-campaign spec.json             # launch + manage the MC campaign itself, sharded via klt sim, then yield's own pipeline unmodified
klt yield-sensitivity campaign.json      # campaign parameter draws + output values -> ranked contribution to the spread (Rust core)
klt yield-threshold records.json         # comparator/latch (stimulus, binary outcome) records -> probit threshold mu/sigma with CIs, per corner
klt design-centering request.json        # yield-sensitivity ranking + sized device -> re-centering candidates
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 netlist block.sch -o block.spice     # xschem schematic -> SPICE netlist, headless (always -x, SIGKILL-bounded); --check gates a committed netlist against drift
klt extract design.gds --deck sky130     # layout -> schematic-equivalent netlist
klt pex design.gds request.json --deck sky130  # extracted (parasitic-annotated) netlist + schematic-vs-extracted delta report
klt mom design.gds stackup.json          # quasi-static capacitance matrix (Method of Moments, Rust core)
klt lvs request.json                     # compare extracted vs reference netlist
klt synthesize request.json              # RTL -> gate-level netlist (Yosys), JSON out
klt arith-gen --width 16 --arch kogge-stone  # parallel-prefix adder RTL from a cell map (+ testbench, techmap rules, equiv request)
klt place-and-route request.json         # netlist -> placed+routed DEF/GDS (OpenROAD), JSON out
klt sta request.json                     # standalone timing/power analysis of an already-routed DEF (OpenSTA), no re-implementation
klt characterize request.json            # standard cell(s) + one PVT corner + a slew x load grid -> NLDM Liberty (.lib) delay/transition/power/leakage model (ngspice)
klt power routed.gds power.json          # routed power/ground nets -> resistive network + static IR-drop map
klt erc routed.gds erc.json --pdk sky130 # per-gate connectivity model + antenna-ratio verdict + core ERC findings (floating gate, unconnected/shorted net, missing tie)
klt functional-verification verify.json  # cocotb regression (Icarus/Verilator) -> pass/fail + coverage
klt equiv request.json                   # combinational equivalence (Yosys miter/SAT) -> proof or counterexample
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 interface-check a.gds b.gds --place=-10,100 --pins 'OUT\[\d+\]'  # do block A's pins land on block B's pads?
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 signoff drc.json lvs.json            # aggregate drc/lvs/extract/sim JSON into one pass/fail verdict
klt trajectory run.jsonl --plot t.svg    # optimization trajectory -> milestone table + plot
klt deck resolve --content-hash sha256:... # pinned deck hash -> klayout-tools tag/version that shipped it
klt deck hash --deck sky130              # the deck content hash this build will use, no layout needed
klt deck info --deck gf180mcu            # this install's own deck hash, device coverage, release status -- no input layout needed
klt deck rules --deck sky130 --rule poly.width.1  # the numbers a deck enforces (rule id -> value in um), pinned to its content hash
klt deck devices --deck gf180mcu --class diode_pd2nw_06v0  # what a layout must DRAW for a device class to be recognised (marker + requires/excludes)
klt deck path --deck asap7              # installed path of the ASAP7 DRC-DSL script, for `klt drc --engine klayout --deck-file`
klt env-provenance emit                  # committable environment provenance: repo-relative paths, pseudonymous host id, no login
klt env-provenance scan records/*.md     # flag home-directory absolute paths leaked into committed evidence records
klt env-provenance lint-envelope r.json  # flag ANY absolute host path in a committed JSON envelope, by field
klt version --format json                # which build is this: version, commit, release or not

Every verb is documented in docs/cli/ (klt yield-campaign shares the yield.md / yield-sensitivity.md pages). PyPI 0.5.0 shipped with 44 verbs; 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.
• The klt mcp serve MCP server — stdio bridge generating one tool per verb from the CLI registry; client config, exit-code mapping, safety defaults (#2830).
• Tagged remote compute — provisioning and operating a tagged EC2 box for heavy agent workloads (sim sweeps, renders, evidence runs) while git/forge operations stay local (#2277).

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, extraction, and signoff's drc/lvs/extract/sim aggregation (klt signoff, #309) now run against shipped klt verbs; the skill still hand-assembles the parts klt signoff can't yet: the S3 spec diff and design-hygiene checklist items).
• economy-review — judge a layout's silicon economy like a human reviewer: renders at multiple zooms plus quantitative density numbers (utilization, whitespace grid, bbox tightness), graded against a rubric that distinguishes analog-legitimate spacing (guard rings, matching, isolation) from genuine waste; pass / revise verdict with coordinate-level targets.

Design notes

Spikes and engine surveys — proposals and findings, not commitments. Full index: docs/design/. What those surveys (and every other mined resource — papers, courses, upstream repos) actually changed here, one entry per resource with impact links, is indexed in the resource library.

• 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.