Stm32-blinky

pcb-studio — OpenCode for PCBs, local-first

Chat with an AI that designs real KiCad boards. Runs fully on your machine (or WSL).

Before choosing a setup, read Windows and WSL. They can share board files, but they do not share OpenCode sessions, credentials, or global plugin installs.

Create a workspace from the release package

After the package is published to npm, create a new, empty workspace without copying files manually:

npx pcb-studio create my-pcb-studio
cd my-pcb-studio

The command refuses to overwrite an existing directory. Until publication, use git clone in the setup instructions below.

Quick start — first time (WSL Ubuntu)

git clone <this-repo> pcb-studio && cd pcb-studio
bun install                  # root scripts
bun --cwd viewer install     # board viewer UI
bun --cwd outputs install    # outputs gallery (renders + 3D)
bun run fetch:kicanvas       # once: vendors the KiCanvas viewer bundle (not on npm)
bun run fetch:freerouter     # once: autorouter engine, verified by SHA-256 (needs Java 17+)
opencode auth login          # once: pick any provider (Anthropic/OpenAI/Google/local)
bash scripts/link-global.sh  # once per machine: every session PCB-aware + project pointer
bun run doctor               # checks bun, node, opencode, auth, kicad-cli, java, ports
bun run dev                  # starts everything, opens all 3 tabs for you

Requirements: Bun >= 1.0, KiCad >= 8 with kicad-cli reachable (Windows C:\Program Files\KiCad\<ver>\bin\kicad-cli.exe works from WSL automatically), Java 17+ (only for autorouting), an OpenCode provider login. WSL has its own OpenCode login; run opencode auth login inside Ubuntu even if you are already signed in on Windows.

Native Windows (no WSL)

Everything works natively too — same repo, same commands, PowerShell instead of bash:

git clone <this-repo> pcb-studio; cd pcb-studio
bun install; bun --cwd viewer install; bun --cwd outputs install
bun run fetch:kicanvas; bun run fetch:freerouter
opencode auth login          # once for Windows TUI + Desktop; WSL login is separate
.\scripts\link-global.ps1    # optional: expose PCB tools to every Windows OpenCode workspace
bun run doctor               # must show ok opencode + ok provider auth
bun run dev                  # same 3 tabs: 4096 chat, 5173 viewer, 5174 gallery

Notes: link-global.ps1 falls back to privilege-free links automatically and refuses to overwrite an existing OpenCode file. Stop with Ctrl+C in the dev terminal. If the OpenCode web UI ever misbehaves on native Windows, switch to the WSL flow above — boards carry over when the repository is on the C: drive, but sessions and login do not.

Every day after

cd pcb-studio
bun run dev

That's it. It starts all three servers, reuses (never duplicates) the pinned chat session, prints bookmark links, and opens the tabs:

Stop

Ctrl+C in the bun run dev terminal stops everything. If a port stays busy afterwards (stale process from a killed terminal):

pkill -f "opencode web"; pkill -f "vite.*5173"; pkill -f "outputs/src/server"
bun run doctor   # confirms all three ports free again

Troubleshooting

• Tab shows "Nothing here yet", "Friendly greeting", or agent "Default" — that's the Desktop app's server, not ours. Close the tab. Only ever use the bookmarked links bun run dev prints. To remove the confusion entirely, quit the OpenCode Desktop app while doing PCB work.
• Viewer looks outdated — hard refresh: Ctrl+F5. (The dev servers hot-reload; a stale browser tab does not.)
• Tool says server not running / connection refused — the opencode server (:4096) isn't up. Start it with bun run dev, or just the API with opencode serve --port 4096 from this folder.
• bun run doctor is the arbiter — run it first whenever anything behaves oddly; fix what it flags, top to bottom.

Layout

• opencode.json — project-only config (model default, permissions, server). Never touches ~/.config.
• .opencode/tools/kicad_*.ts — the PCB harness. Only thing custom-built.
• .opencode/agents/ — pcb-engineer (primary) + pcb-reviewer (read-only subagent).
• .opencode/skills/ — on-demand KiCad playbooks (ERC, DRC, layout).
• .opencode/commands/ — /check, /export shortcuts.
• hardware/ — your boards. Starts empty; the agent creates every project here via kicad_scaffold.
• viewer/ — sidecar web UI (chat + KiCad board, talks to same local server).
• outputs/ — final-renders gallery server (schematic/PCB SVG via tscircuit pipeline, 3D GLB via KiCad).
• scripts/ — dev (launcher), doctor (health check), fetch-* (vendored engines), link-global.sh, test-tools.ts (15-check harness: bun scripts/test-tools.ts).
• constraints/ — shareable versioned design-constraint packs (JSON).

Which tab is mine? (important)

bun run dev prints two bookmark links and opens them for you:

• board viewer: http://localhost:5173 — live KiCad render, follows your session
• chat: deep link straight into the pinned ✅ PCB STUDIO — talk HERE session

Always use those links. The opencode web UI also sees your Desktop app's server — any tab showing "Friendly greeting" or agent "Default" is the Desktop server, not us. Close it. If you lose the chat link, re-run bun run dev and it prints it again (the pinned session is reused, never duplicated).

Relationship to tscircuit, Copperhead, et al.

Same dream (describe a board, get a board), opposite bet on source of truth:

• tscircuit ("React for Electronics"): the board IS TypeScript code. Powerful — registry, playground, fast autorouter — but existing KiCad projects can't enter, only leave via export, and the cloud APIs it depends on are occasionally down.
• pcb-studio: the board IS KiCad files. Any .kicad_sch/.kicad_pcb ever made (including tscircuit KiCad exports — feed them to kicad_import) works on day one, KiCad GUI stays usable side-by-side, everything runs locally, and every step is verified (ERC/DRC/netlist) instead of trusted.

Import from code-first tools; do not fight them. No framework lock-in either way.

Existing OpenCode users

Safe by default: the repo never edits your global config. The optional scripts/link-global.sh / scripts/link-global.ps1 install only missing PCB tools, agents, skills, guardrail, and shared tool library into ~/.config/opencode. They refuse to overwrite an existing file. This makes the PCB agent available in every session while the repository remains the source of truth.