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:8082The 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) andproblems(relay verbatim, never invent); ambiguity returns candidates rather than guessing; success results also carrynext_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_netsundoes 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.pythonuses a per-connection namespace + an explicitexec.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.
MCP core
Tool discovery, session registry, interaction context, recorder, transfer, and diagnostics.
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.