klayoutclaw

KlayoutClaw

Drive KLayout from any AI agent — chip & nanodevice layout over MCP.

---

KlayoutClaw plugs KLayout into the Model Context Protocol so Claude, Codex, Cline, or your own agent can create layouts, run pya scripts, autoroute pins, and drive full nanodevice fabrication pipelines — all in your existing KLayout GUI.

macOS only for now. Linux / Windows are on the roadmap.

Quick Start

git clone https://github.com/caidish/KlayoutClaw.git
cd KlayoutClaw
python install.py                 # copies plugin into ~/.klayout/pymacros
open /Applications/klayout.app    # KLayout starts the MCP server on :8765
python tests/test_connection.py   # verify

Point any MCP client at http://127.0.0.1:8765/mcp:

claude mcp add --transport http klayoutclaw http://127.0.0.1:8765/mcp

Then just ask:

"Create a Hall bar with a 100×25 µm graphene channel, 6 side probes, and bonding pads. Save as hallbar.gds."

What's Inside

Layer	Purpose
MCP Server (plugin/)	KLayout autorun macro. 19 JSON-RPC tools on 127.0.0.1:8765: layout I/O, execute_script, screenshot, autoroute, design evaluation, plus 9 vc_* version-control tools. Zero external deps.
Skills (skills/)	Claude Code plugin with 9 skills — geometry, display, visual, image, GDS import, and 4 nanodevice pipelines (flakedetect, gdsalign, routing, e2e design). Loaded automatically.
Qlaybot (agent/)	Standalone TypeScript agent (v0.4.4) built on Pi-Agent SDK. Ink/React TUI, 10 slash commands, planning sandbox, categorized memory with FTS5 + vector search, 3-phase context compaction, JSON-RPC mode. Auto-launches KLayout.
Tools (tools/)	Subprocess helpers: GDS→PNG, ordered-loop routing engine (numpy/scikit-image/klayout), nanodevice DRC + metric evaluator (gdstk/shapely).

  Any MCP client                          KLayout GUI
  (Claude / Codex / Qlaybot / …)          + KlayoutClaw plugin
┌──────────────────┐  HTTP/JSON-RPC   ┌──────────────────┐
│                  │ ◄──────────────► │  pya.QTcpServer  │
│   agent + skills │  :8765/mcp       │  (Qt main thread)│
└──────────────────┘                  └──────────────────┘

End-to-End Demo

An autonomous run of the full vdW heterostructure pipeline — load a GDS template, overlay flake-detection results, generate a Hall bar, route every pin to bonding pads — from a single prompt.

https://github.com/user-attachments/assets/f51d5649-e69b-4885-b17f-f849277a05a6

_{Video not rendering? Uncompressed copy at docs/Demo.mp4.}

Qlaybot — Batteries-Included Agent

cd agent
npm install && npm run build
export ANTHROPIC_API_KEY=...
npm start        # interactive TUI

Qlaybot ships its own MCP client and auto-launches KLayout. First run creates ~/.qlaybot/. After npm link, the qlaybot command is available globally. See agent/README.md for the full CLI, RPC mode, subagents, and 697-test suite.

Dependencies

The MCP server itself uses only Python stdlib + KLayout's pya. Subprocess tools (auto_route, evaluate_design) and nanodevice skills need a scientific Python stack — we recommend a conda env named instrMCPdev:

conda create -n instrMCPdev python=3.11 -y && conda activate instrMCPdev
pip install numpy scipy scikit-image scikit-learn opencv-python-headless \
            gdstk shapely matplotlib klayout==0.30.3

Pass python_path= to override the env per-call.

Documentation

• docs/tools.md — MCP tool reference (all 19)
• docs/skills.md — skill catalog
• docs/ui-plugin.md — UI panel + status bar
• docs/plans/ — architecture design notes
• CONTRIBUTING.md — how to help

Acknowledgments

The auto-routing engine borrows algorithmic techniques from Klayout-Router by Legendrexial (MIT).

License

MIT — see LICENSE. Questions or collaboration: [email protected].