klayout-tools
IC layout for AI agents
early alpha · v0.9.1 on PyPIMIT · Python 3.10+
Standalone tools that let AI agents parse, check, generate and verify chip layouts: GDSII and OASIS streams, DRC and LVS, extraction, simulation and a digital flow. Everything runs headless, and every command emits machine-readable JSON. You get a klt command line and an MCP server, built on KLayout's Python API.
It is the kicad-tools playbook one layer down the stack. There, agents take a design from schematic to routed PCB to fabrication package, and a gallery of real boards proves it. Here, the same pattern meets silicon.
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).
Early alpha: 67 verbs exist today, and new verbs and JSON fields land between releases. The roadmap has the build order, and the architecture doc explains how the pieces fit.
Quick start
1. Install
uv tool install klayout-tools
# or: pip install klayout-toolsThis puts klt on your PATH together with KLayout's headless Python module. You do not need a GUI. Optional extras are [mcp] for the MCP server and [yield] for the Monte Carlo yield verbs. Verbs that wrap an external engine (ngspice, xschem, Yosys, OpenROAD) need that engine installed, and klt mom still needs a source build for its Rust core. The README has the details.
2. Run it on a real cell
This site serves the GDS for every gallery block. Here is the open-source SkyWater sky130 inverter:
curl -O https://klayout-tools.org/blocks/sky130_fd_sc_hd__inv_1/sky130_fd_sc_hd__inv_1.gds klt layers sky130_fd_sc_hd__inv_1.gds # layers and shape counts klt cells sky130_fd_sc_hd__inv_1.gds --top # cell hierarchy klt stats sky130_fd_sc_hd__inv_1.gds --per-layer # area, density, polygons klt drc sky130_fd_sc_hd__inv_1.gds --deck sky130 # status: clean, 0 violations klt render sky130_fd_sc_hd__inv_1.gds -o renders # per-layer PNGs, headless # the same commands with --format json emit the JSON contract klt drc sky130_fd_sc_hd__inv_1.gds --deck sky130 --format json
With --format json, every verb answers in one envelope: schema_version, a common error shape and documented exit codes. That envelope is the API (JSON contract).
3. Give it to an agent (MCP)
pip install 'klayout-tools[mcp]'
# MCP client config (Claude Desktop, Claude Code, Cursor, …)
{
"mcpServers": {
"klayout-tools": {
"command": "klt",
"args": ["mcp", "serve", "--workspace-root", "/path/to/your/project"]
}
}
}klt mcp serve generates 92 tools from the CLI registry, one for each leaf verb, named klt_<verb>. It runs each call as a subprocess, so the result is the same JSON the CLI prints. By default, path arguments that resolve outside the workspace root are rejected, and verbs that launch remote compute are hidden (MCP guide).
4. Check layouts in CI
# .github/workflows/layout.yml - uses: 2AMLogic/[email protected] with: layout: layout/my_block.gds verbs: drc,layout-metrics deck: sky130
The composite Action installs klt, runs the verbs you list, and publishes a step summary plus JSON and render artifacts (Action guide).
Capabilities
67 verbs, each headless, each documented, each speaking the same JSON envelope. Built-in rule decks for open PDKs only: asap7, gf180mcu, sg13cmos5l, sg13g2, sky130. This list is generated from the CLI on main, which can be ahead of v0.9.1; klt --help lists what your install has.
Read and inspect layout 9
- klt layersenumerate layers of a GDSII/OASIS stream
- klt cellsreport the cell hierarchy of a GDSII/OASIS stream
- klt statsreport area, density, and polygon/vertex counts of a GDSII/OASIS stream
- klt diffcompare two GDSII/OASIS streams for equal geometry, labels and hierarchy
- klt clipwrite a bbox region or a named cell's subtree out as its own stream
- klt componentsreport connected components across a caller-selected conductor/via stack
- klt renderrender per-layer PNG images from a GDSII/OASIS stream
- klt economyquantitative layout-density report
- klt layout-metricsemit a normalized layout.json per block from existing klt output
Physical checks 10
- klt drcrun a headless DRC deck against a GDSII/OASIS stream
- klt precheckrun a named battery of layout-hygiene checks
- klt ercbuild a per-gate layer-by-layer connectivity model and antenna-ratio verdict (antenna/ERC signoff)
- klt socket-checkcheck a GDSII/OASIS stream against a socket/template descriptor
- klt interface-checkcheck that block A's labelled pins land on block B's pads at a placement
- klt ring-checkassert a layer set forms a single closed annulus (guard/tap ring)
- klt seam-checkcheck abutting-cell tiling and conductor continuity across seams
- klt keepout-checkassert no forbidden-layer shape lies within a margin of a cell/region
- klt array-checkassert mirror/translation symmetry and pitch abutment of a cell array
- klt tap-distanceassert every subject point is within a Euclidean distance of a tap
Generate and compose layout 5
- klt gengenerate a parametrized layout cell (headless PCell harness)
- klt gen-composeplace already-generated blocks and library cells into one composed cell
- klt layout-planexecute a netlist-driven klt.layout_plan.request/1 document
- klt drawwrite a primitive GDSII/OASIS stream from a JSON shape description
- klt lef-abstractemit a LEF abstract (MACRO/PIN/OBS) from a layout + socket descriptor
Netlist, extraction and LVS 6
- klt netlistexport an xschem schematic to a SPICE netlist (headless)
- klt extractextract a schematic-equivalent netlist from a GDSII/OASIS stream
- klt lvscompare an extracted/reference netlist pair and report mismatches
- klt pexextract a parasitic-annotated netlist and re-sim the schematic testbenches against it
- klt momquasi-static capacitance extraction (Method of Moments)
- klt powerextract a routed layout's power grid as a resistive network, solve it for static IR drop, and emit a per-net EM current-density verdict
Simulation and sizing 6
- klt simrun a headless SPICE PVT corner matrix (ngspice)
- klt sim-plansplit a klt sim request into per-process shards and a sim-merge manifest
- klt sim-mergemerge per-request klt sim reports of one split corner grid
- klt corner-matrixcheck a klt sim request or report against a declared corner matrix
- klt sizesolve a single device's operating point from a gm/Id target (ngspice)
- klt characterizecharacterize standard cells into one NLDM Liberty (.lib) model
Monte Carlo yield 7
- klt yieldMonte Carlo sample set + spec limits -> yield estimate with CIs (needs the klt-yield-native extension)
- klt yield-samplestwo klt sim MC reports (nominal + known-bad) -> a klt yield sample-set document carrying a negative control
- klt yield-csvper-draw Monte Carlo CSV -> a klt yield sample-set document
- klt yield-campaignlaunch + analyse a Monte Carlo yield campaign from a spec (needs the klt-yield-native extension)
- klt yield-sensitivitycampaign parameter draws + output values -> ranked contribution to the spread (needs the klt-yield-native extension)
- klt yield-thresholdper-sample (stimulus, binary outcome) records -> probit threshold mean/sigma with profile-likelihood CIs, per corner
- klt design-centeringyield-sensitivity ranking + sized device -> re-centering candidates
Digital flow 11
- klt synthesizesynthesize RTL against a standard-cell liberty via Yosys
- klt arith-gengenerate a parallel-prefix adder (Verilog) from a cell map
- klt techmapLiberty-driven technology mapping of a generic netlist (native Rust)
- klt equivprove/refute combinational equivalence of two RTL/gate netlists (Yosys)
- klt formalcheck assert/cover properties of RTL or a mapped netlist (SymbiYosys)
- klt functional-verificationrun a cocotb regression against Icarus/Verilator
- klt wavebuild/query an indexed store from a VCD/FST functional-verification waveform trace (native Rust)
- klt place-and-routeplace and route a synthesized netlist against a resolved PDK via OpenROAD
- klt stastandalone timing/power analysis via OpenSTA of a placed & routed DEF, or of a bare gate-level netlist with no DEF
- klt reset-coveragelist state elements of a gate-level netlist an async reset misses
- klt power-intentcheck isolation, state and sequencing of a power-gated netlist
Signoff, reports and provenance 8
- klt signoffaggregate klt drc/lvs/extract/sim JSON envelopes into one pass/fail verdict
- klt reportrender one or more klt JSON envelopes into a text/markdown report
- klt evalscore a candidate against a per-block gate/objective descriptor
- klt trajectoryrender an optimization trajectory JSONL log to a milestone table + plot
- klt evidencewrite an evidence-record/1 file around a finished klt sim / klt pex report
- klt artifactput/get/verify/delete evidence bytes in an artifact store by sha256, with a committed manifest
- klt env-provenanceemit committable environment provenance for an evidence record, scan records for leaked home paths, or lint committed JSON envelopes for absolute host paths
- klt versionreport the running build's identity (release vs post-tag build)
PDKs, decks and knowledge base 3
Agent integration 1
- klt mcpserve the klt verbs to MCP-capable agent frameworks
More 1
- klt fillinsert density fill shapes on a PDK's fill layers
Gallery
Real layouts on open PDKs. Each page is built from the block's committed klt layout-metrics output and shows layer and cell stats, renders, and an in-browser GDS viewer.
75 canary blocks · 75 with generated artifacts
Test corpus
Standard cells from the tests/corpus demo set — the loader's test fixtures, not 2AM designs.
Docs
- CLI reference — one page per verb
- JSON contract — envelope, errors, exit codes
- MCP server — client config, safety
- GitHub Action — inputs and outputs
- Architecture — scope and layers
- Roadmap — build order
- Changelog — v0.9.1, 2026-11-05
- PyPI — klayout-tools
- Issues — bugs and requests











































