KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

clover

★ 19 Open GitHub ↗

AI-agent for hardware simulations using arduino

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Clover: AI-agent for Hardware Simulation
<img width="3780" height="1890" alt="Image" src="https://github.com/user-attachments/assets/fd60cddc-539c-4624-b63d-0f89f1b1527d" />

> Describe what you want to build in plain English. Get working, simulated Arduino hardware in seconds.

Clover is a desktop application that bridges the gap between natural language and working hardware. Users describe Arduino projects conversationally, and an AI agent generates the code, designs the circuit, compiles the firmware, and runs everything in a visual simulator — no physical components required.

Built with Electron, React, and Claude AI (Anthropic), powered by [avr8js](https://github.com/nicschumann/avr8js) for cycle-accurate AVR simulation and [Wokwi Elements](https://github.com/nicschumann/wokwi-elements) for circuit visualization.

## Demo
<p align='center'>
    <img src="./resources/agent.gif" alt="Clover demo — describing a project and seeing it simulated" width="3780" />
</p>

## Problem Statement

Getting started with hardware and electronics is unnecessarily complex. Beginners and even junior engineers face steep barriers such as understanding circuit design, configuring microcontrollers, writing correct firmware, and setting up physical components before they can see any working result. This complexity leads to a high drop-off rate among people interested in hardware, slowing learning, experimentation, and innovation. There is currently no simple, unified tool that translates high-level intent into working, testable hardware systems while also guiding users through both simulation and real-world setup.

## Features

- **Natural Language to Hardware** — Describe your project in plain English ("blink an LED every 500ms", "build a distance sensor with an LCD display") and get working code + circuit instantly
- **Live Circuit Simulation** — See LEDs light up, servos rotate, displays render text, and buttons respond to clicks — all in the app, no Arduino board needed
- **Zero-Click Compilation** — Code generated by AI is automatically compiled and loaded into the simulator
- **Auto-Debug Loop** — If compilation fails, errors are automatically sent back to the AI for correction (up to 3 attempts)
- **Real-Time Streaming** — Watch the AI response stream in real-time as code, circuit diagrams, and explanations appear simultaneously
- **Full Code Editor** — Monaco Editor (the engine behind VS Code) with Arduino/C++ syntax highlighting for manual edits
- **Conversation History** — All chats are persisted in a local SQLite database, searchable and resumable
- **Secure API Key Storage** — Your Anthropic API key is encrypted using your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
- **Cross-Platform** — Builds for macOS, Windows, and Linux

### Supported Components

| Component | Element | Simulation |
|---|---|---|
| Arduino Uno | `wokwi-arduino-uno` | ATmega328P, 14 digital + 6 analog pins |
| LED | `wokwi-led` | Digital on/off + PWM fade |
| Push Button | `wokwi-pushbutton` | Clickable digital input |
| Potentiometer | `wokwi-potentiometer` | Draggable analog input |
| Servo Motor | `wokwi-servo` | Angle-based visual rotation |
| Buzzer | `wokwi-buzzer` | Web Audio API tone generation |
| NeoPixel Strip | `wokwi-neopixel` | WS2812 timing-accurate simulation |
| LCD 16x2 | `wokwi-lcd1602` | I2C character display |
| OLED SSD1306 | `wokwi-ssd1306` | I2C pixel display |
| 7-Segment Display | `wokwi-7segment` | Multi-digit numeric display |
| Resistor | `wokwi-resistor` | Visual representation |

## Prerequisites

- **Node.js** 18 or higher
- **npm** (comes with Node.js)
- **Anthropic API Key** — Get one at [console.anthropic.com](https://console.anthropic.com/)

## Getting Started

### 1. Clone the repository

```bash
git clone https://github.com/your-username/clover.git
cd clover
```

### 2. Install dependencies

```bash
npm install
```

This will also run `patch-package` and `electron-builder install-app-deps` automatically via the postinstall hook (required for native modules like `better-sqlite3`).

### 3. Start the development server

```bash
npm run dev
```

The app will launch in development mode with hot module replacement (HMR) enabled.

### 4. Enter your API key

On first launch, you'll see an onboarding screen. Enter your Anthropic API key. It will be encrypted and stored securely using your operating system's credential manager.

### 5. Start building

Type a description of what you want to build in the chat panel:

> "Build an LED traffic light that cycles through red, yellow, and green"

The AI will generate the Arduino code and circuit layout, compile it, and start the simulation automatically.

## Scripts

| Command | Description |
|---|---|
| `npm run dev` | Start the app in development mode with HMR |
| `npm run build` | Type-check and build for production |
| `npm run start` | Preview the production build |
| `npm run build:mac` | Build macOS distributable (DMG) |
| `npm run build:win` | Build Windows distributable (NSIS installer) |
| `npm run build:linux` | Build Linux distributable (AppImage, Snap, DEB) |
| `npm run build:unpack` | Build unpacked distributable for testing |
| `npm run typecheck` | Run TypeScript type checking (main + renderer) |
| `npm run typecheck:node` | Type-check main process only |
| `npm run typecheck:web` | Type-check renderer process only |
| `npm test` | Run unit tests with Vitest |
| `npm run coverage` | Run tests with coverage report |

## Systems Architecture

**Simulation State Machine:**

### IPC Architecture

Electron's main and renderer processes communicate through a secure `contextBridge` preload layer. The renderer never has direct access to Node.js APIs.

| Channel Namespace | Purpose |
|---|---|
| `claude:*` | AI messaging — send, stream, set/validate API key |
| `db:*` | Database — create/list/load conversations, add messages |
| `fs:*` | File system — read/write files, list directories |
| `dialog:*` | Native dialogs — open file, save file, select directory |
| `system:*` | System info — platform, memory, paths |
| `app:*` | Window controls — minimize, maximize, close, quit |

### Database Schema

Chat history is stored in a local SQLite database (`chat-history.db`) with WAL mode enabled for concurrent read performance:

```sql
CREATE TABLE conversations (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL DEFAULT '',
    created_at DATETIME NOT NULL DEFAULT (datetime('now'))
);

CREATE TABLE messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    conversation_id INTEGER NOT NULL,
    role TEXT NOT NULL,
    content TEXT NOT NULL,
    created_at DATETIME NOT NULL DEFAULT (datetime('now')),
    FOREIGN KEY (conversation_id) REFERENCES conversations(id) ON DELETE CASCADE
);
```

## Project Structure

```
open-claude/
├── src/
│   ├── main/                          # Electron main process
│   │   ├── index.ts                   # Entry point, window creation
│   │   ├── services/
│   │   │   ├── claude.ts              # Anthropic SDK wrapper
│   │   │   ├── database.ts            # SQLite operations
│   │   │   └── secure-storage.ts      # OS-level API key encryption
│   │   └── ipc/
│   │       ├── claude-handlers.ts     # AI-related IPC handlers
│   │       ├── database-handlers.ts   # Database IPC handlers
│   │       └── handlers.ts            # File system, dialog, system IPC
│   │
│   ├── preload/                       # Security boundary
│   │   ├── index.ts                   # contextBridge API exposure
│   │   └── index.d.ts                 # TypeScript definitions
│   │
│   ├── renderer/src/                  # React frontend
│   │   ├── App.tsx                    # Root component (routing)
│   │   ├── features/
│   │   │   ├── chat/                  # Chat UI, streaming, message history
│   │   │   ├── simulation/            # AVR runner, circuit canvas, code editor
│   │   │   ├── orchestrator/          # Auto-compile & auto-debug pipeline
│   │   │   ├── onboarding/            # First-run API key setup
│   │   │   └── settings/              # Preferences panel
│   │   ├── components/                # Shared UI components (Shadcn)
│   │   └── hooks/                     # Shared React hooks
│   │
│   └── shared/                        # Cross-process types & utilities
│       ├── types.ts
│       └── errors.ts
│
├── electron-builder.yml               # Build & packaging configuration
├── electron.vite.config.ts            # Vite config for Electron
├── tsconfig.json                      # TypeScript project references
└── package.json
```

## Tech Stack

| Layer | Technology |
|---|---|
| Desktop Framework | Electron 32 |
| Frontend | React 19, TypeScript, Tailwind CSS 4 |
| UI Components | Shadcn UI (Radix primitives) |
| Code Editor | Monaco Editor |
| AI Model | Claude Opus 4.6 (Anthropic SDK) |
| Simulation | avr8js (AVR CPU emulator) |
| Circuit Visuals | Wokwi Elements (web components) |
| Database | better-sqlite3 (SQLite with WAL) |
| Build Tooling | Vite, electron-vite, electron-builder |
| Testing | Vitest, Testing Library |
| Markdown | Remark, Shiki, Mermaid |

## Usage Examples

**Basic LED Blink**
> "Make an LED blink on pin 13 every second"

**Interactive Button + LED**
> "Wire a button to pin 2 and an LED to pin 9. When I press the button, fade the LED in and out"

**Display Output**
> "Show 'Hello World' on an I2C LCD display"

**NeoPixel Animation**
> "Create a rainbow animation on a strip of 8 NeoPixels"

**Multi-Component Project**
> "Build a traffic light with three LEDs (red, yellow, green) that cycles every 3 seconds, and display the current color name on an OLED"

**Learning & Explanation**
> "Explain how PWM works on the Arduino and show me an example with a fading LED"

## Configuration

### API Key

Your Anthropic API key is encrypted and stored using your OS credential manager. You can update it anytime from the Settings panel within the app.

### Compilation

Arduino code is compiled using the [Hexi cloud compiler](https://hexi.wokwi.com) (Wokwi build service) which returns Intel HEX binaries targeting the ATmega328P.

### Data Storage

| Data | Location | Format |
|---|---|---|
| API Key | OS Keychain / Credential Manager | Encrypted via Electron `safeStorage` |
| Chat History | `~/.config/open-claude/chat-history.db` | SQLite (WAL mode) |
| EEPROM Data | Browser localStorage | Key-value pairs |

## Building for Distribution

### macOS
```bash
npm run build:mac
```
Produces a `.dmg` installer in the `dist/` directory.

### Windows
```bash
npm run build:win
```
Produces an NSIS installer (`.exe`) in the `dist/` directory.

### Linux
```bash
npm run build:linux
```
Produces AppImage, Snap, and DEB packages in the `dist/` directory.

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Make your changes
4. Run tests (`npm test`)
5. Run type checking (`npm run typecheck`)
6. Commit and push
7. Open a pull request

## License

MIT

clover

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README