Source code coming soon. The GitHub repository is private for now and opens to everyone very soon.
BetterSPICE Beta 0.8.0 Join the beta Download soon
Part VII  Files and integrationReferenceContentsIndex
52

Working with an AI agent

An AI agent such as Claude Code works in the same circuit you see, with the same operations as your own clicks, and you watch it happen. It connects through MCP, the Model Context Protocol, with the server bspice mcp. When the desktop app isn’t running, the same tools edit circuit files on disk instead.

52.1Setting up Claude Code

claude mcp add bspice -- "C:\Program Files\BetterSPICE\bspice.exe" mcp

Or in an MCP configuration file:

{ "mcpServers": { "bspice": { "command": "C:\\Program Files\\BetterSPICE\\bspice.exe", "args": ["mcp"],
                     "env": { "BSPICE_AGENT_NAME": "claude" } } } }
  • The app listens on ws://127.0.0.1:47800, on this computer only. BSPICE_PORT changes the port for both the app and the agent.
  • The agent needs the key in %APPDATA%\BetterSPICE\agent-token, which the MCP server reads by itself. Treat it as a secret.
  • The agent's name, shown as AI · name, is BSPICE_AGENT_NAME, else the name the agent reports, else agent.
  • If the app isn’t running, the tools work on files ("headless"). If the app is running but the connection fails, every result says so: "Note: this ran headless on files, NOT in the BetterSPICE window: …"

52.2What you see while an agent works

An agent at work: the top bar says what it is doing, its cursor marks the part, and Activity logs each edit.
Figure 52.1An agent at work: the top bar says what it is doing, its cursor marks the part, and Activity logs each edit.
What you see while an agent works
What you seeMeaning
Following AI: name · actionThe bar at the top of the canvas names the agent and what it’s doing. Its cursor moves to each part it touches. The bar fades four seconds after its last action.
Follow AIThe pill appears once an agent has talked to the window in this session; the View menu entry is always there. On by default: your view pans and zooms to what the agent touches. Turn it off (Ctrl+Shift+F) to keep your view where it’s while its edits still appear.
Take over or EscStops the agent: its edits are refused for 10 seconds, and Follow AI turns off. Reading tools still work.
AI badgeIn the inspector, on parts an agent changed last.
ActivityEvery edit and run, with the agent's name in violet.
Pinned notesViolet notes the agent pinned to the schematic. Click to dismiss.

Edits by an agent are normal undo steps: Ctrl+Z takes them back. Parts and symbols an agent creates go to My parts.

52.3Every tool

Every tool
ToolArgumentsWhat it does
open_circuitpath or jsonOpens a circuit, like File, Open.
get_circuitThe circuit, the file, the selection and the view.
save_circuitpathSaves it.
applyopsApplies a list of edits as one undo step.
add_parttype, id, at, rot, mirror, variant, pins, pPlaces a part. With p.modelId it takes the catalogue model's live values.
add_wirea, b, viaDraws a wire. A diagonal becomes two segments.
set_paramid, key, valueSets a parameter, the variant or the designator.
deleteidsDeletes elements.
moveids, dx, dyMoves elements, wires follow.
selectidsSelects in your view (app only).
view_focusids or pointsPans your view there, unless you turned Follow AI off (app only).
view_setzoom, centerSets your view (app only).
open_panelnameinspector, diagnostics, activity, scope, bode, fft, examples, palette, wizard, simsetup, about, shortcuts (app only).
set_modemodeschematic, analysis or split (app only).
show_traceprobeShows a probe's trace (app only).
annotateat, textPins a note on the schematic (app only).
run_livespeedRuns the live simulation (app only).
pausePauses it (app only).
simulateanalysis, stop, maxStep, source, out, at, fStart, fStop, ptsPerDec, start, stepRuns op, tran, ac, dc, noise, pz or loopgain, with ngspice or PSpice for vendor models, and returns the signals and measurements. noise and pz need out, the output net. loopgain needs at, the break point. An engineering text value such as 10m is taken.
run_analysisas simulate, plus out, all, startRuns the analysis in the Analysis view you see.
get_measurementsnamesLive probe values and min, max, mean, RMS, peak to peak and final of the last run.
get_waveformname, maxPoints, from, toA signal's data, thinned to maxPoints (500).
get_diagsThe diagnostics.
screenshotA picture of your canvas, or a render when there’s no window.
list_partsqueryPart files in the parts library.
parts_listquery, kind, sourceMy parts and the part library.
parts_getidOne part or symbol with its data.
create_partbspart, replaceValidates a part file and saves it to My parts and the circuit.
create_symbolsymbol, replaceSaves a symbol.
place_partpartRef, at, rot, mirror, id, pPlaces a part from My parts or the library (app only).
symbols_listbuiltinThe symbols, and optionally the built-in ones.
list_examplesquery, category, offset, limitThe example circuits.
open_examplepath or name, newTabOpens an example as an unsaved copy, in a new tab unless the current one is empty.
import_filepath or name and base64, flat, addSupplies, openImports a KiCad or EasyEDA Pro file.
get_reportout, fftProbe, maxCharsWrites the HTML report and returns its text.
verify_circuitCompares the engine with ngspice on this circuit.
get_eventsEvents since the last call: edits, selection, view, simulation state, diagnostics, activity.

52.4Edits (ops)

Every change is an op. A list of ops sent with apply is one undo step, and if one op fails, none is applied.

Edits (ops)
OpFieldsEffect
addpart {type, id, variant, p, pins or at, rot, mirror, symbol, symPins}Adds a part. A missing or taken id gets the next free one.
wirea, b, via (hv or vh)Adds a wire.
moveids, dx, dyMoves elements.
rotateids, dirRotates 90°.
mirroridsMirrors.
setid, key, valueSets a parameter (null removes it), the variant, the id, the pins, the slider ranges, or a source type.
delidsDeletes elements.
labelname, atA net label.
probeprobe {label, kind, at or part, scope}A probe.
dockey, valuename, description, category, or a sim key.
power, global, port, graphic, sheet, bus, busEntry, subcircuitFlags, labels, ports, drawings, sheets, buses (app only).

Coordinates are whole grid units. Element ids: parts by designator, wires w:x1,y1,x2,y2, labels l:name@x,y, probes p:label. Working on files without the app, add with at places two-pin parts and ground by itself. Other parts need explicit pins.

Try it
Ask an agent to design a filter
  1. Open the app and start Claude Code with the bspice server configured.
  2. Ask: "Build a 1 kHz second-order Sallen-Key low-pass with a TL072 and show me its Bode plot."

You should seeThe presence bar shows each step as the agent places parts, wires them, probes the output and runs the AC sweep in the Analysis view in front of you. Press Esc at any time to take over.

52.5Errors an agent can get

Errors an agent can get
CodeMeaning
-32700, -32600The message isn’t JSON, or not a valid request.
-32601Unknown tool or method.
-32602A missing or wrong argument. The message names it.
-32001Not authenticated, or you took over (retry in N seconds).
-32002No BetterSPICE window is connected.
-32003The window didn’t answer within 30 s (600 s for simulations).
-32010The tool ran and failed. The diagnostics are attached.
-32603An unexpected failure in the window.

52.6The control API for your own scripts

Any program can drive the app over WebSocket JSON-RPC 2.0: connect to ws://127.0.0.1:47800/?token=<token>&agent=<name>, call hello, then subscribe to events (circuit.changed, selection.changed, view.changed, sim.state, sim.diags, sim.frame at most ten a second, file.changed, activity), and call the same methods as the tools above. bspice serve runs the same server without a window, for the browser version.