klayoutclaw

KlayoutClaw

AI-powered layout design platform for KLayout. Connects your agent (Claude Code, Codex, Cline, or any MCP client) to your desktop KLayout through the Model Context Protocol, and ships Claude Code skills for geometry creation, layer display, visual capture, and nanodevice fabrication pipelines.

Built for device physicists working on 2D material devices, superconducting qubits, photonics, and other micro/nanofabricated systems.

macOS only for now. Linux/Windows support is planned but untested. We need more help with Windows/Linux Native user and more benchmark test.

Real Sample Nanodevice Demo

Full nanodevice fabrication pipeline on a real van der Waals heterostructure sample: load a GDS template, overlay flake detection results from the flakedetect and gdsalign pipelines, generate a 8 pin Hall bar, and route 11 pins to bonding pads using multi-window routing.

What's Inside

KlayoutClaw has three layers:

Layer	What it does
MCP Server	KLayout autorun macro — JSON-RPC 2.0 server on 127.0.0.1:8765. 6 tools: create layouts, run pya scripts, save GDS/OASIS, capture screenshots, autoroute pin pairs. Zero external dependencies.
Skills	Claude Code plugin with 7 skills — geometry, display, visual, image, and 3 nanodevice pipelines (flakedetect, gdsalign, routing). Claude loads them automatically when relevant.
Tools	Standalone utilities — GDS-to-PNG converter, subprocess routing engine. Used by the MCP server and skills internally.

┌─────────────┐       HTTP/JSON-RPC        ┌─────────────────┐
│  Claude /    │  ◄──────────────────────►  │  KLayout GUI    │
│  Codex /     │    127.0.0.1:8765/mcp      │  + KlayoutClaw  │
│  Any MCP     │                            │    plugin        │
│  client      │                            │                  │
└─────────────┘                            └─────────────────┘
       │
       │  Skills (Claude Code plugin)
       │  geometry, display, visual, image,
       │  nanodevice:{flakedetect, gdsalign, routing}
       ▼

Quick Start

# 1. Clone
git clone https://github.com/caidish/KlayoutClaw.git
cd KlayoutClaw

# 2. Install plugin into KLayout
python install.py

# 3. Launch KLayout
open /Applications/klayout.app

# 4. Test the connection
python tests/test_connection.py

MCP Tools

Tool	Description
create_layout	Create a new layout with a top cell
execute_script	Run arbitrary Python/pya code in KLayout
save_layout	Save layout as GDS2 or OASIS
get_layout_info	Get layout summary (cells, layers, dbu)
screenshot	Capture viewport as PNG (what the user sees)
auto_route	Autoroute connections between pin pairs

execute_script is the power tool — it runs any Python code inside KLayout with access to pya, the current layout, and view. The other tools handle lifecycle and visualization. See docs/tools.md for full parameter schemas.

Autorouter

auto_route automatically connects pin pairs using Hungarian matching and cost-based pathfinding. It runs as a subprocess with numpy/scipy/scikit-image, supporting obstacle avoidance, configurable path spacing, and graduated damping cost fields. See docs/tools.md for tuning parameters.

Example: Create a rectangle via MCP

import json, urllib.request

def mcp(method, params=None, req_id=1):
    payload = {"jsonrpc": "2.0", "id": req_id, "method": method}
    if params: payload["params"] = params
    req = urllib.request.Request("http://127.0.0.1:8765/mcp",
        data=json.dumps(payload).encode(),
        headers={"Content-Type": "application/json"}, method="POST")
    return json.loads(urllib.request.urlopen(req).read())

# Initialize + create layout
mcp("initialize", {"protocolVersion": "2025-03-26", "capabilities": {},
    "clientInfo": {"name": "example", "version": "0.1"}})
mcp("tools/call", {"name": "create_layout", "arguments": {"name": "TOP"}}, 2)

# Draw a 100x50um rectangle on layer 1/0
mcp("tools/call", {"name": "execute_script", "arguments": {"code": """
dbu = _layout.dbu
li = _layout.layer(1, 0)
_top_cell.shapes(li).insert(pya.Box(int(-50/dbu), int(-25/dbu), int(50/dbu), int(25/dbu)))
result = {"status": "ok", "shape": "rectangle"}
"""}}, 3)

# Save
mcp("tools/call", {"name": "save_layout",
    "arguments": {"filepath": "/tmp/example.gds"}}, 4)

Using with Claude Code

# Add KlayoutClaw as an MCP server
claude mcp add --transport http klayoutclaw http://127.0.0.1:8765/mcp