klayout-tools

# klayout-tools

[![CI](https://github.com/2AMLogic/klayout-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/2AMLogic/klayout-tools/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/pypi/v/klayout-tools)](https://pypi.org/project/klayout-tools/)
[![Status: early alpha](https://img.shields.io/badge/status-early%20alpha-yellow.svg)](ROADMAP.md)

**Tools for AI agents to work with IC layout.**

🌐 **[klayout-tools.org](https://klayout-tools.org)** — project site.

The [kicad-tools](https://github.com/rjwalters/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](https://www.klayout.de)'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](ROADMAP.md) holds the build order,
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) how the pieces fit; the
work itself is tracked in GitHub issues.

Built in the open by [2AM Logic](https://2amlogic.com).

## 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](docs/guides/mcp-server.md))
- **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](https://pypi.org/project/klayout-tools/)
(44 verbs at release; see [`docs/cli/`](docs/cli/) for the set). The
pattern is proven (see the kicad-tools [gallery](https://kicad-tools.org) of
boards designed end-to-end by agents); this repo is where it meets silicon.
See [ROADMAP.md](ROADMAP.md) for the build order and [CLAUDE.md](CLAUDE.md)
if you are an agent working here.

## Install

```bash
uv tool install klayout-tools
```

Or with `pip`:

```bash
pip install klayout-tools
```

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

```bash
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`](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:

```bash
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`](docker/eda-sim/README.md)
for the version pins and the full contract.

## Quick start

```bash
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 components design.gds --conductors '[{"name":"m1","layer":

... (truncated)