Quickstart - klink

Requirements

KLayout desktop build. Live workflows depend on the GUI macro environment and pya/db APIs.
Python 3.10 or newer. The package metadata declares requires-python = ">=3.10".
Optional: Claude Code, Codex, or another MCP client.
Optional per workflow: gdsfactory, the klayout Python package, NumPy/OpenCV, SciPy, scikit-learn, or scikit-image.

The core package does not bundle third-party scientific libraries. Feature errors name the exact missing pip install command.

Supported versions

Component	Floor	Notes
`klayout` (pip)	>= 0.28	0.27 is not supported: klink's device extractor uses a `GenericDeviceExtractor` overload that pya itself documents as introduced in 0.28.
`gdsfactory` (`[photonics]`)	>= 9.0, < 10	Every 9.x release is covered. gdsfactory 8.x works in testing but is not part of the pin yet -- treat it as experimental.

These versions are continuously verified by the public repo's CI gf-compat / klayout-compat matrices.

Install the Python package

python -m pip install klayout-klink

This installs klink and its own two Rust acceleration kernels, klink-boxmaze-rs and klink-trackmaze-rs. On unsupported platforms pip may build the kernels from source, which requires a Rust toolchain. For pure-Python core only:

python -m pip install klayout-klink --no-deps

Install optional feature dependencies only when needed:

python -m pip install klayout
python -m pip install gdsfactory
python -m pip install numpy opencv-python-headless
python -m pip install scipy scikit-learn scikit-image

Install the KLayout plugin

klink_plugin is a KLayout salt package. Copy the public repository or release checkout's klink_plugin/ folder into KLayout's salt directory.

Windows PowerShell

cd path\to\klink
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\KLayout\salt" | Out-Null
Copy-Item -Path ".\klink_plugin" -Destination "$env:USERPROFILE\KLayout\salt\" -Recurse -Force

Linux / macOS

cd /path/to/klink
mkdir -p ~/.klayout/salt
cp -R klink_plugin ~/.klayout/salt/

Restart KLayout. A successful plugin startup prints something like:

[klink.server] listening on 127.0.0.1:8765

Smoke test

from klink import KLinkClient

with KLinkClient() as c:
    print(c.ping(nonce=42))
    print(c.layout_info(verbosity="summary"))

If KLayout is listening on a different port:

from klink import KLinkClient

with KLinkClient(port=8766) as c:
    print(c.ping())

Run the preflight check when in doubt:

python -m klink.doctor --port 8765

Staying current

klink ships improvements fast, often straight from real user feedback. Run a preflight check before you start:

python -m klink.doctor

It checks whether your install is behind the latest release on PyPI, and, live against KLayout, whether the plugin has fallen behind the Python package. An update is three steps that travel together:

python -m pip install -U klayout-klink   # 1. upgrade the Python package
klink plugin install                     # 2. sync the plugin, restart KLayout (or reload the macro)
# 3. reconnect the MCP server

The doctor's PyPI probe is best-effort (2s timeout) and skips automatically offline; pass --no-latest to disable it outright.

Your first result

Offline: EBL wraparound

PyPI-only users create a project first, then run the starter copied into the template:

klink init my-chip
cd my-chip
python example_template/nanodevice/ebl_wraparound.py

Once the project exists, start every new task with klink run new <slug> (usually the agent runs it itself — the project's agent rules call for it at the start of every task): it creates a dated custom_devices/runs/<date>_<slug>/ folder (driver stub + this task's out/ + a notes.md record template, together in one place) and registers itself in the runs/INDEX.md ledger at creation ("(in progress)", collapsing into a one-line summary + PASS/FAIL when the task finishes). Code that proves out graduates into custom_devices/toolbox/, the project's own reusable-tool package.

In a public source or release checkout, the gallery module path also works:

python -m examples_klink.public.demos.nanodevice.ebl_wraparound

Recorded public output summary: "ok": true, 40 electrodes, 12 patches, writefield 16 fields / 11 windows / 20 crossings, 0 violations, 0 overlaps.

Live KLayout: neural electrode harness

python example_template/nanodevice/neural_electrode.py --port <session-port> --elec-rows 4

Source or release checkout path:

python -m examples_klink.public.demos.nanodevice.neural_electrode --port <session-port> --elec-rows 4

Recorded public output summary: 48 ports, 24 routed nets, sibling-overlap 0, obstacle-hit 0.

A KLayout port is just a session. Use an empty or test-owned window for demos, not your manual working layout.

Refresh starters after upgrading klink

After installing a newer klink, run klink update to refresh the starter demos under example_template/; your own files (pdk.py, custom_devices/, .klink/, out/, specs/) are never touched:

python -m pip install -U klayout-klink
klink update my-chip   # or run it from inside the project folder: klink update

Connect MCP

cd path\to\klink
klink-mcp --setup .

claude mcp add klayout -- python -m klink.mcp --profile read,write,verify,escape --session-id project-klink

Profile	Purpose
`read`	Layout, cell, layer, shape, view, and selection queries.
`write`	Cell, layer, shape, instance, PCell, and undo transaction authoring.
`verify`	DRC, LVS, and structured verification tools.
`escape`	Controlled escape-hatch tools such as `exec.python`.
`all`	Expose all tools.

Troubleshooting

Python cannot connect: check KLayout is running, the plugin was copied, KLayout was restarted, and the port is correct.
MCP tools exist but calls fail: MCP is running but KLayout is unreachable. Start KLayout and call klink.reconnect or restart the MCP client.
gdsfactory tools miss dependencies: install gdsfactory into the same interpreter that runs the MCP server.
PowerShell blocks venv activation: allow scripts for the current process.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

Want to understand why klink is designed this way? Read Core Concepts: geometry-first first, then move on to the step-by-step tutorials.