Design (the model)
The design stage turns a prompt into a structured design: the parts, the nets and a board size. Everything after it builds from that design, and none of it knows which model wrote it.
A design has these parts. Every field is documented in design.json.
| Field | What it holds |
|---|---|
summary | One line saying what the board is |
board | A name, the width and height in mm, and size_asked when the prompt sets the size |
components | Each part: reference, kind, what to buy, package, value, purpose |
nets | Which pins connect, with a voltage and a current for power nets |
assumptions | What the model assumed that the prompt did not say |
decisions | Open design choices, each with two or three options and one recommended |
unsupported | What the prompt asked for that the model could not carry |
Four functions call the model:
design.generate(prompt)returns a design. The command line, the evaluator and the repair loop use it.design.converse(prompt)is for a chat turn in the app. It returns the model's reply, plus a design only when the message changed the board. A question gets an answer and no rebuild.design.revise(prompt)is for a change to a board the app already has. It returns the reply and a patch, not a whole design. A part the patch does not name stays on the board.design.structured(prompt, schema, system)is one call that is not a design. The wiring turn (--wire) uses it, and so does reading a datasheet's pin table.
Backends
| Claude Code (default) | Gemini | Claude | Groq | Mercury | |
|---|---|---|---|---|---|
| Select | nothing, or SOLDERMASK_BACKEND=claude-code | --backend gemini | --backend claude | --backend groq | SOLDERMASK_BACKEND=mercury |
| Credentials | The claude command line, logged in | GEMINI_API_KEY or GOOGLE_API_KEY | ANTHROPIC_API_KEY, or a profile from ant auth login | GROQ_API_KEY | INCEPTION_API_KEY |
| Default model | claude-fable-5-2 | gemini-3.8-flash | claude-opus-5 | openai/gpt-oss-120b | mercury-2.5 |
| Schema | Enforced as written, plus lcsc on a part | Enforced as written | Enforced as written | Bounds relaxed | Enforced unless the endpoint objects |
| Cost recorded | Tokens, billing, and list price apart | Tokens | Tokens, and cost at $5 / $25 per million | Tokens, and cost at $0.15 / $0.75 per million | Tokens, and cost at $0.04 / $0.15 per million |
--modeloverrides the model id.--effortsets Claude's effort (defaulthigh). Claude runs with adaptive thinking and 16,000 output tokens.SILIXON_BACKENDstill works in place ofSOLDERMASK_BACKEND.
The Claude Code backend
The default backend runs Claude Code without a window, on the account it is logged into. A claude.ai plan pays for it, not an API key.
To set it up:
- Install Claude Code, so
claudeis on your PATH. - Run
claudeonce and log in with your claude.ai account. - Start the app or run the command line as usual.
A design turn is a loop, not one call. The model can call three tools of
the MCP server: search_parts, pins and
check_design. It looks parts up, reads their real pin names, and checks the
design before it answers. Each call shows as a line in the build log.
It gets nothing else from your machine. It runs in an empty folder. It loads no settings, hooks, plugins or CLAUDE.md, and has no shell or file access. Every other tool of the MCP server is refused.
A part can be pinned. Of the backends, only this one may set lcsc on a
component, because only it can look a code up. A code that search_parts or
pins did not return in the same turn is removed. The design's unsupported
list names the part and the code. For an edit, the reply names them instead.
A person or an MCP client can pin a part too (design.json).
A plan records no cost. The board records billing and list_usd, the
list price of the same tokens. cost_usd stays empty, so a plan's turns never
add up as money spent.
An API key is not used. The backend removes ANTHROPIC_API_KEY from its
environment, so the claude.ai login is used. Use --backend claude to design
on a key instead.
| Setting | Default | What it sets |
|---|---|---|
SOLDERMASK_CLAUDE_CODE_MODEL | claude-fable-5-2 | The model it asks for |
SOLDERMASK_CLAUDE_CODE_TIMEOUT_S | 900 | How long one turn may take, in seconds |
A missing install or login is one line, not a traceback:
Claude Code is not installed here (no
claudeon PATH). Install it from https://claude.com/claude-code and log in withclaude, or set SOLDERMASK_BACKEND=gemini.
Claude Code is not logged in. Run
claudeonce and log in with your claude.ai account, or set SOLDERMASK_BACKEND=gemini.
The other backends name their missing key the same way.
A relaxed schema is reported. Groq's strict mode rejects minimum,
maximum and minItems, so those limits become requests in the prompt. If
Gemini or Mercury rejects a schema keyword, the call is retried without
additionalProperties. Either way, the design's unsupported list says the
schema was relaxed.
What the model is told
The system prompt sets these hard constraints:
- Two copper layers, or four when the prompt asks. Four is read off the prompt into
constraints.board.layers, so the design does not list it as unsupported. Any other count goes inunsupported. On four layers, the first inner layer is a ground plane and the other three carry signals. Ground is a copper pour on both outer layers, so a ground pin costs the router nothing. - The board size is a guess. The pipeline resizes the board to its parts once they are known. When the prompt sets the size, the model sets
board.size_asked, and the board is never made smaller. - Only supported packages. Every part must use one of the supported packages, because those are the only footprints that exist.
- Two-terminal parts use pins
1and2. A diode or an LED names its endsAandKinstead. Most diodes number the cathode pad 1, so a number would name different ends to different readers. - ICs use pin function names, exactly as the datasheet writes them:
VI,VO,GND,EN,SDA. Never pin numbers. Multi-unit parts qualify names asA.+,B.-. - Modules use
FROM_PART. An ESP32, a radar or a GPS module iskind: "module"with packageFROM_PART. Its footprint and pin names then come from the vendor's data for that exact part number. - Placement belongs to the pipeline, on both sides. When the front is full, surface-mount parts nobody has to reach go on the back. Connectors, switches, LEDs and modules stay on the front. A request for a one-sided board is honoured. A request for a part in a particular place goes in
unsupported, namingconstraints.pinned. - Prefer parts JLCPCB stocks as basic parts.
- Decouple every IC, and give every power rail bulk capacitance.
- Every power and ground net gets a
voltage_vand acurrent_a. Use null for signal nets, and null when the load is unknown.
Pin 1 on an LED is a position, not a pad number. Vendors number LED pads
differently, so resolve.py reads which pad the ordered part calls its anode
and wires 1 to it. The design check warns when a
diode's ends are given as numbers (diode-pins).
A pin function name can be checked against the part's symbol. A recalled pin number cannot, which is why ICs never use numbers.
The prompt also tells the model what the pipeline reports on its own, so it
does not repeat it in unsupported:
- A radio module's antenna gets a copper keepout on both layers, read from its footprint.
- Where the ground pour cannot reach a pad, the pipeline stitches it or routes it, and says which.
Decisions. A prompt can leave a real fork open, such as battery or mains
power. The model then lists two or three options in decisions and marks one
recommended. It builds the recommended one, so there is always a board.
Unsupported. The unsupported list is published beside the board, word for
word. It holds real limitations only, not hedges.
What is read off the prompt
The pipeline also reads the prompt itself. What it finds goes into the constraints, which the model cannot write.
| The prompt asks for | It lands in | See |
|---|---|---|
| Four copper layers | constraints.board.layers | Four layers |
| One side of parts | constraints.board.sides | Both sides |
| A router by name | constraints.rules.router | Routers |
| A compact or a roomy board | constraints.board.size | When the board is too big |
| Mounting holes | constraints.board.mounting_holes | Mounting holes |
A prompt that asks for three or more layers gets four, and one that asks for one layer gets two. The build says so.
Priors
The prompt ends with block idioms measured from real open-hardware boards.
Block idioms. priors_blocks.json lists, for each IC symbol, the passives
drawn within 40 mm of it and how often. An IC counts when it appears at least
four times across at least two projects. mine_blocks.py builds the file from
.kicad_sch files. The six most common blocks go into the system prompt, with
their three most frequent companions each.
priors.py holds more numbers measured from real boards. They are not in the
prompt.
| Prior | Value | Measured from | Used for |
|---|---|---|---|
| Median trace width | 0.25 mm (10th percentile 0.171 mm) | 86,801 trace segments on 86 routed KiCad boards | The placer's congestion estimate, and a fallback where no rule is set |
| Median clearance | 0.20 mm | the same boards | The placer's congestion estimate, and a fallback where no rule is set |
| Median via | 0.60 mm pad, 0.30 mm drill | the same boards | The via the routers place |
| Component mix | capacitors 24.8%, resistors 15.4% | 144 schematics | Nothing reads it |
| Capacitors per IC | 5.1 | the same schematics | Nothing reads it |
| Decoupling value | 100nF (bulk: 1uF) | the same schematics | Nothing reads it |
The routers do not route at the median. Lightcycle and the A* router both route at 0.127 mm track and clearance. See Routers.
Current sets copper width. A net's current_a is the steady current in
amps. electrical.py sizes the net's trace to it by IPC-2221. A null routes at
the board's signal track: 0.127 mm, or a person's floor
(constraints.rules.min_track_mm). That track carries about half an amp. So the
schema asks for null rather than a guess, because a guess gets etched.
Copper too narrow for its declared current fails the verdict. See Copper too narrow for its current.
The schema
The design is checked against a narrow JSON schema. The model describes intent. It does not invent footprints, part numbers or pad geometry, because the pipeline resolves those against real data.
The most important field is search: what to buy. It is a manufacturer part
number when the model is sure one exists, otherwise a short description of the
part. It is searched against the parts catalogue. A search that
finds nothing drops the part. The gaps list says so, and the board fails its
verdict.