Architecture

Three tiers

Tier	Content	Form
Mechanism	`klink` Python client, algorithms, MCP bridge, and KLayout plugin.	Installed package and salt package; normal users do not edit these.
Development repo	Tests, recordings, development examples, and internal design records.	Development source, not the full public release surface.
User project	`pdk.py`, `custom_devices/`, specs, and generated outputs.	Your folder. The agent writes here.

Control path

Agent (Claude Code / Codex)
  -> MCP server (python -m klink.mcp)
  -> klink client (NDJSON over TCP)
  -> KLayout plugin (in-process RPC server)
     RPC: 127.0.0.1:8765+
     klive-compatible: 127.0.0.1:8082

The plugin stays thin. Heavier logic runs in external Python, where agents, tests, and optional third-party libraries are easier to manage.

Process purity

The core holds no process defaults. Any layer number, size, or device parameter in a demo belongs to that example or to the user's pdk.py.

To bring up a new process, write pdk.py; do not edit klink/.
Pass layers, widths, spacing, and device libraries explicitly.
When required process facts are missing, tools should return instructive errors with the next action.

Agent tool design principles

klink's reliability comes from tool design, not prompt wording. The same principles recur across routing, transfer, and the device flows:

One intention = one call. Orchestration is the product; klink does not rely on a weak agent to assemble primitives in the right order (e.g. structdevice.build_from_netlist, nanodevice.hallbar, photonics.connect).
Errors instruct, they don't diagnose. A failure result carries next_action (the next step to relay verbatim) and problems (relay verbatim, never invent); ambiguity returns candidates rather than guessing; success results also carry next_action, making the workflow "a linked list joined by results".
Validate before mutate. Pure computation/validation runs first; only a clean result writes to disk or edits the layout; edits are wrapped in transactions so a failure is idempotently retryable and leaves no scar (e.g. connect_nets undoes everything on any LVS mismatch).
State on disk, not in the agent's memory. Cross-call/cross-session context is persisted by the tools to documented paths (specs, net tables, interaction context under .klink/), so any agent and any fresh session can resume.
Long-running process purity. Tools must be called repeatedly in one MCP server process without cross-contamination — e.g. exec.python uses a per-connection namespace + an explicit exec.reset.

These guarantees land in three layers: strongest is tool-level enforcement (harness-independent) → neutral lane/recipe definitions → thin per-harness adapters (CLAUDE.md / AGENTS.md). Even a weaker agent is steered back on track by tools that refuse bad input with a fix.

Batch RPCs

Generated layouts should not make one RPC per object. Use batch methods to avoid repeated TCP, JSON, transaction, and GUI bookkeeping costs.

Workload	Preferred RPC
Many boxes on one cell/layer	`shape.insert_boxes`
Mixed shapes	`shape.insert_many` for box, polygon, path, and text.
Many child-cell instances	`instance.insert_many`
Many library/basic PCell instances	`instance.insert_pcell_many`

Public domains

routing

Port/Anchor tapered, steiner, damped, and channel backends, plus custom-device detailed routing to LVS.

nanodevice

EBL wraparound, Hall bar, neural electrode harness, and flake-related tools.

photonics

gdsfactory bridge, blackbox port harvesting, import_gf_component, photonic net intent, and reroute.

structdevice

Device extraction, netlists, logic map, layout engine, P&R, LVS-lite, and live LVS integration.

imaging

Imaging exits driven by one layout/process declaration: .pyxs process cross-sections, 3D renders with an offline interactive viewer, SEM-style top views, and paper-grade Blender renders.

L-Edit bridge

Two-way file exchange with a running Tanner L-Edit: pull selections/cells, push geometry back; deeper T-Cell read/write goes through the Python API.

MCP core

Tool discovery, session registry, interaction context, recorder, transfer, and diagnostics.

These domains are built in, but third parties can extend klink too: ship a pip package that contributes its own MCP tools, a find_tools domain, and named resources (profile/devices/recipe/stack) through the klink.plugins entry point, with failures isolated per package — an on-ramp for PDK vendors and extension authors, not an end-user feature. See the extension-package guide.

Release boundary

This website only documents release-verifiable public content: root READMEs, docs/public, examples_klink/public, package metadata, klink/, and klink_plugin/ public entry points.

Internal development notes are used only to avoid publishing the wrong thing. The public website does not disclose unreleased workflows, private PDKs, private GDS, or confidential validation details.

Stable mechanism, user-owned process