A local-first, AI-assisted circuit design tool for your projects. Wire components in a 3D view, describe what you want to build, and the AI agent writes the firmware and simulates it , all before you touch a physical chip.

Table of contents

1. Features
2. Prerequisites
3. Installation
4. UI overview
5. Creating a project
6. Extending the palette , adding components
   • component.json reference
   • Pin definitions
   • Sim metadata
   • 3D model (.glb)
   • Schematic symbol
7. Adding boards
8. Using the agent
   • Agent tools reference
   • Prompting tips
9. Behaviors DSL
   • Triggers
   • Actions
10. Firmware simulation
11. Code generation
12. Build and flash
13. Project file format
14. Architecture overview
15. Development

Features

• 3D circuit view , drag components onto the board, click pins to wire them, inspect nets in real time
• AI agent , describe a circuit in plain English; the agent adds components, wires them, runs DRC, and writes firmware
• Firmware simulation , behaviors defined by the agent run in the browser; GPIO outputs animate instantly with no hardware required
• Code generation , a complete ESP-IDF 5 C project (app_main.c, CMakeLists.txt, sdkconfig.defaults) is generated live from the project state
• Build and flash , one-click idf.py build, idf.py flash, and serial monitor, all streamed inside the app
• Extensible catalog , drop a component.json + .glb folder into ~/.circuitiny/catalog/ to add any component to the palette
• Multi-board , ESP32-DevKitC v4, ESP32-S3-DevKitC-1, ESP32-C3-DevKitM-1, ESP32-C6-DevKitC-1, XIAO ESP32-S3

Prerequisites

ESP-IDF setup (optional)

Install via the official guide. After installation, set the path:

export CIRCUITINY_IDF_PATH=/path/to/esp-idf   # default: /Users/$USER/esp/esp-idf

Add to your shell profile to make it permanent. If IDF is not installed, all design, simulation, and code generation features still work , only Build and Flash are disabled.

Installation

git clone https://github.com/mfranzon/circuitiny
cd circuitiny
pnpm install
pnpm dev          # opens the Electron app in dev mode with hot reload

To build a distributable:

pnpm build

UI overview

┌─────────────────────────────────────────────────────────────────────────────┐
│  Circuitiny     [Project]  [Catalog Editor]              myproject ●  [Open] [Save]  [+ New] │
├──────────┬──────────────────────────────────┬────────────────────┬──────────┤
│          │                                  │                    │          │
│ Palette  │         3D Viewer                │ Schematic /        │  Agent   │
│          │                                  │ Behaviors          │          │
│ (catalog │   ● sim badge when running       │                    │  chat    │
│  list)   │                                  │                    │  window  │
│          ├──────────────────────────────────┤                    │          │
│          │   Code / Build / Sim             │                    │          │
│          │   [Code] [Build/Flash] [Sim ▶]   │                    │          │
└──────────┴──────────────────────────────────┴────────────────────┴──────────┘

Creating a project

1. Click + New Project in the top-right
2. Choose a board from the picker
3. Name your project and click Create

Projects auto-save state in memory. Use Save (or Cmd+S) to persist to a .circuitiny.json file. An amber ● dot after the project name means there are unsaved changes.

To reopen a project: click Open and select the .circuitiny.json file.

Creating 3D models with Claude Code

If you use Claude Code, you can generate custom 3D component models with the /render skill and import them directly into Circuitiny without leaving the terminal.

Step 1 — Generate a 3D model

/render a 10kΩ potentiometer with 3 pins

The /render skill generates a .glb model from a text description using build123d and opens it in a browser viewer. You can iterate on the shape until it looks right.

Step 2 — Import into Circuitiny

/esp-ai-import

The /esp-ai-import skill picks up the most recently rendered .glb, asks you for the component name, category, and pin layout, then installs it into ~/.circuitiny/catalog/. Restart Circuitiny and the component appears in the palette.

You can also fine-tune pin positions after import using the built-in Catalog Editor tab.

Extending the palette , adding components

The component catalog lives at ~/.circuitiny/catalog/. Each component is a folder containing:

~/.circuitiny/catalog/
└── my-component/
    ├── component.json    ← required
    └── model.glb         ← optional but recommended

The app loads all catalog entries at startup. Restart the app (or hot-reload in dev mode) to pick up new components.

component.json reference

Pin definitions

Each entry in the pins array describes one physical pin:

Pin types:

Finding pin positions for a new model

Pin positions must match the GLB model's local coordinate space. Use the built-in Catalog Editor (Catalog Editor tab in the nav bar):

1. Click Load GLB and pick your model file
2. Click on the model surface at each pin location , the app records the 3D position and normal
3. Name each pin and set its type
4. Click Save to catalog , writes component.json + copies the GLB to ~/.circuitiny/catalog/<id>/

Sim metadata

The sim field tells the simulator how to animate this component during firmware simulation:

Sim roles:

You can combine both fields , e.g. a component that both outputs and accepts clicks.

3D model (.glb)

• Format: binary glTF (.glb)
• Coordinate system: Y-up, units in meters
• Recommended: keep models small , typical components are 3–30 mm = 0.003–0.03 in model units
• Materials: standard PBR (MeshStandardMaterial). Emissive properties are overridden by the sim.
• If no GLB is provided, the app renders a colored box placeholder

Schematic symbol

Available symbols: resistor, capacitor, led, button, potentiometer, display, ic, sensor, motor, relay, speaker, microphone, ledstrip, generic-rect

If the symbol field is omitted the component renders as a generic labeled rectangle in the schematic view.

Adding boards

Boards are defined in code at src/catalog/index.ts. To add a new board:

1. Define the board by adding a BoardDef object:

const myBoard: BoardDef = {
  id: 'my-board-v1',                    // unique id
  name: 'My Board v1',
  version: '0.1.0',
  boardVersion: 'v1',
  category: 'misc',
  model: 'my-board.glb',                // GLB filename in assets
  target: 'esp32s3',                    // IDF target: esp32 | esp32s2 | esp32s3 | esp32c3 | esp32c6 | esp32h2

  features: ['Wi-Fi 6', 'BLE 5.0', 'USB CDC'],  // shown in board picker

  // Restricted pins , DRC checks these
  inputOnlyPins:  ['GPIO34', 'GPIO35'],
  strappingPins:  ['GPIO0', 'GPIO3', 'GPIO45', 'GPIO46'],
  flashPins:      ['GPIO27', 'GPIO28', 'GPIO29', 'GPIO30', 'GPIO31', 'GPIO32'],
  usbPins:        ['GPIO19', 'GPIO20'],    // native USB; triggers USB CDC config
  adc1Pins:       ['GPIO1', 'GPIO2', 'GPIO3'],
  adc2Pins:       ['GPIO11', 'GPIO12'],
  pwmCapablePins: [],                      // empty = all GPIO are PWM-capable
  railBudgetMa:   { '3v3': 600 },

  pins: [
    // Use the headerPins() helper for standard 2.54mm header rows
    ...headerPins('left', halfX, halfZ, [
      { id: '3v3',   label: '3V3', type: 'power_out' },
      { id: 'gnd_l', label: 'GND', type: 'ground'    },
      { id: 'gpio1', label: '1',   type: 'analog_in' },
      // ... one entry per pin
    ]),
    ...headerPins('right', halfX, halfZ, [
      // right header row
    ])
  ]
}

2. Register it by adding to the boards record near the bottom of the file:

const boards: Record<string, BoardDef> = {
  [devkitc.id]:  devkitc,
  // ... existing boards
  [myBoard.id]:  myBoard,   // add here
}

3. Pin positions , the headerPins(side, halfX, halfZ, labels) helper places pins evenly along a header row. Parameters:

   • side: 'left' (−Z edge) or 'right' (+Z edge)
   • halfX: half the board length in meters (e.g. 0.022 for a 44mm board)
   • halfZ: half the board width in meters (e.g. 0.0145 for a 29mm board)
   • labels: array of { id, label, type } from the pin closest to the USB end to the far end

4. GLB model , place the .glb file in resources/ (Electron assets). Pin coordinates in the board definition must match the model's local coordinate space. The board mesh is centered at the origin in the 3D view.

Tip: If you don't have a GLB yet, omit the model field (or point it at a non-existent file). The app renders a parametric green PCB placeholder automatically based on the pin bounding box.

Using the agent

Open the Agent pane on the right. Select a model provider and key in the settings (gear icon), then type your request.

Supported providers

Agent tools reference

The agent has access to the following tools. You can reference these in prompts to guide behavior.

Prompting tips

Start with a clear goal:

"Add an LED on GPIO16 with a 220Ω resistor, a push button on GPIO4, and write firmware that lights the LED while the button is held."

The agent follows a fixed workflow:

1. think to plan the BOM and wiring
2. list_catalog to check available components
3. add_component + connect for each component
4. run_drc after every wire
5. set_behavior for each firmware behavior
6. Summarises and tells you to click ▶ Play

Iterate freely:

"The LED should also blink at 2Hz when not pressed." "Replace the button with a PIR sensor."

The agent knows ESP32 constraints , it will avoid strapping pins, check current limits, add pull-up resistors for I2C, and suggest safe GPIO numbers.

Behaviors DSL

Behaviors are the single source of truth for firmware logic. They drive both the in-app simulator and the generated C code.

A behavior has one trigger and a list of actions:

Edit behaviors manually in the Behaviors tab, or let the agent write them with set_behavior.

Triggers

source for gpio_edge is a pin ref: "instance.pinId" (e.g. "btn1.a") or "board.pinId" (e.g. "board.gpio4").

Actions

target is a pin ref pointing at the component pin or board pin to drive.

Pin refs always follow the format "instance.pinId" , not raw GPIO numbers. The sim and codegen resolve the actual GPIO number from the net connections.

Firmware simulation

Click ▶ Play in the Sim tab (Code/Build/Sim panel) to start the simulator.

The simulator evaluates your behaviors in JavaScript at up to 10× speed:

• Timer triggers fire when the simulated clock crosses a period boundary
• gpio_edge triggers fire when a button or input component is clicked in the 3D view
• GPIO outputs animate immediately , LEDs glow, relays activate, WS2812B strips light up
• Log actions print to the Sim console

Interacting during simulation:

• Components with sim.role: "button" or "generic_input" show a blue highlight ring
• Click and hold a button → rising edge fires → LED turns on
• Release → falling edge fires → LED turns off
• Rapid clicks each fire their own edge (no debounce in sim v0)

Speed control: 1×, 2×, 5×, 10× , adjusts how fast simulated time advances relative to wall time.

The sim stops automatically if DRC errors appear while it's running.

Code generation

The Code tab shows a live-generated ESP-IDF 5 project, updated as you edit the circuit. Three files are generated:

The code generator covers:

• GPIO output/input init from net connections
• I2C bus init (when I2C components are present)
• xTaskCreate / vTaskDelayUntil for timer behaviors
• gpio_set_level / gpio_set_direction for set_output and toggle actions
• ESP_LOGI/W/E for log actions

If the agent writes raw firmware via write_firmware, those files appear as additional tabs in the Code pane with an agent badge and override the generated output.

Build and flash

Open the Build / Flash tab.

1. Select a serial port , click ↻ to rescan, then pick your device (e.g. /dev/cu.usbserial-0001)
2. ▶ Build , writes the generated C project to ~/circuitiny/projects/<name>/ and runs idf.py build
3. ⚡ Flash , runs idf.py flash to the selected port
4. 📟 Monitor , opens idf.py monitor to stream serial output from the device
5. ■ Stop , kills the current operation (SIGINT → SIGKILL after 1.5s)
6. Clean , runs idf.py fullclean

Build output streams in real time. Errors appear in red, metadata in green.

First build is slow , idf.py set-target runs only once per project, configuring the toolchain for the selected chip. Subsequent builds are incremental.

Project file format

Projects are saved as .circuitiny.json. The format is stable and human-readable:

schemaVersion is 1. Future breaking changes will increment this field.

Architecture overview

src/
├── agent/          # LLM integration
│   ├── anthropic.ts / openai.ts / ollama.ts   # provider adapters
│   ├── chatSession.ts                          # turn loop, tool dispatch
│   ├── tools.ts                                # all tool definitions + executors
│   └── expertPrompt.ts                         # system prompt for expert mode
│
├── catalog/
│   ├── index.ts        # in-memory catalog: boards + inline components
│   └── hydrate.ts      # loads ~/.circuitiny/catalog/ on startup
│
├── codegen/
│   ├── ir.ts           # intermediate representation: resolves nets → GPIO numbers
│   └── generate.ts     # emits app_main.c, CMakeLists.txt, sdkconfig.defaults
│
├── drc/
│   └── index.ts        # design rule checks (strapping pins, flash pins, short circuits…)
│
├── panes/
│   ├── Viewer3D.tsx     # 3D scene, component placement, wiring, sim visuals
│   ├── Schematic.tsx    # 2D schematic view
│   ├── ChatPane.tsx     # agent chat UI
│   ├── CodePane.tsx     # generated code viewer
│   ├── BuildPane.tsx    # build/flash/monitor UI
│   ├── SimPane.tsx      # sim controls + log
│   └── Palette.tsx      # component browser sidebar
│
├── project/
│   ├── schema.ts       # Project, Behavior, Action, Net types
│   └── component.ts    # ComponentDef, BoardDef, SimDef, PinDef types
│
├── sim/
│   ├── evaluate.ts     # behavior evaluator: advances sim time, fires triggers
│   └── useSimLoop.ts   # React hook: 100ms interval, mounted in App.tsx
│
└── store.ts            # Zustand store: all app state + actions

electron/
├── main.ts     # IPC handlers: file dialogs, catalog IO, idf.py pipeline
└── preload.ts  # contextBridge: exposes window.circuitiny to the renderer

Data flow:

Project state (store)
  │
  ├──► generate.ts ──► Code pane (live C code)
  │
  ├──► evaluate.ts ──► sim visuals (Viewer3D)
  │
  ├──► drc/index.ts ──► DRC overlay + sim guard
  │
  └──► agent/tools.ts ──► LLM ──► mutations back to store

Development

pnpm dev          # Electron + Vite hot reload
pnpm typecheck    # TypeScript check (both node and web tsconfigs)

Adding a new agent tool:

1. Add a ToolDef entry to the tools array in src/agent/tools.ts
2. Add the executor case in executeInternal
3. Mention the tool in expertPrompt.ts if the agent should use it proactively

Adding a new behavior action:

1. Add the new type to the Action union in src/project/schema.ts
2. Handle it in src/sim/evaluate.ts → runActions
3. Handle it in src/codegen/generate.ts → emitActions
4. Add it to the set_behavior tool schema in src/agent/tools.ts

Adding a new trigger type:

1. Add to TriggerKind in src/project/schema.ts
2. Handle in src/sim/evaluate.ts → firesInWindow
3. Handle in src/codegen/generate.ts (may need a new task template)
4. Add to the set_behavior tool schema