klayout-klink CLAUDE.md

klink — AI-native control plane for KLayout

Let an AI agent (Claude Code / Codex) directly control the KLayout layout editor: draw shapes, manage cells/layers, place instances, run pya macros, and generate layouts with gdsfactory.

Architecture

AI agent
├── MCP: klink-mcp           ← klink RPCs exposed as MCP tools
├── Skill: klayout            ← RPC + pya macro domain knowledge
└── Skill: klayout-gdsfactory ← gdsfactory → KLayout bridge
       │
       ▼
KLayout (klink_plugin)        ← port 8765 (RPC) + 8082 (klive-compat)

Do not rely on a hard-coded RPC count. Query the live server:

from klink import KLinkClient

with KLinkClient().connect() as c:
    print([m["name"] for m in c.methods()["methods"]])

MCP tools are organized along two orthogonal axes (klink/mcp/catalog.py): intent/capability (read/write/verify/escape/all) and domain/area (device_photonics, routing_backends, …). tools/list always advertises every tool; call klink.find_tools to navigate them (no args → domain index; domain=<token> → that area's tools; query=<keywords> → ranked matches). --profile accepts both axes — default read,write,verify,escape.

Setup

Install the package (pip install klayout-klink) and the KLayout salt plugin, then configure your agent's MCP server:

{
  "mcpServers": {
    "klayout": {
      "command": "<python-that-has-klink>",
      "args": ["-m", "klink.mcp", "--profile", "read,write,verify,escape",
               "--session-id", "project-klink"],
      "env": {
        "KLINK_CONTEXT_ROOT": "<your-project>/.klink/sessions"
      }
    }
  }
}

Interpreter rule: optional libraries (gdsfactory, klayout, numpy, …) must live in the SAME Python that runs klink.mcp. klink does not bundle them — install the one a feature needs yourself; the tool error names it. klink.status reports interpreter and capabilities so you can verify.

Environment

• klink core is pure Python; its only runtime dependencies are its own two Rust kernels (prebuilt wheels, byte-parity with the pure-Python reference), so pip install klayout-klink brings klink + both accelerators. They are speed-only (pure-Python fallbacks exist); pip install --no-deps gives the pure-Python core alone.
• gdsfactory must be in the SAME interpreter that runs klink.mcp.
• klink RPC port: 8765; klive-compat port: 8082.
• interaction context memory: .klink/sessions/<session-id>/interaction_context.jsonl