Skip to main content
Glama
README.md
<p align="center">
  <img src="docs/assets/bench-logo.svg" alt="Bench" width="200">
</p>

<h1 align="center">Bench</h1>

**Made by [Seaynic Labs](https://seayniclabs.com).** Need tools like this built around your own systems? [We do that](https://seayniclabs.com/#business).

<p align="center"><strong>USB hardware discovery for your AI tools.</strong></p>

Bench is a native macOS [MCP server](https://modelcontextprotocol.io) for developers who work with boards plugged into their Mac: Arduino, ESP32, Raspberry Pi Pico and other USB boards. It names the board, finds its serial port, reads and writes that port, detects the chip, decodes crash dumps, and flashes firmware with your approval. Bench is free and open source, made by [Seaynic Labs](https://seayniclabs.com).

<!-- security-card:start (generated by scripts/security_card.py) -->
| Security card | |
|---|---|
| Network | None. Bench makes no network calls and sends no telemetry. |
| Files | Reads the skills folder beside the binary. Writes the approval log (`~/.local/state/bench/approvals.jsonl`, arguments redacted; `BENCH_APPROVAL_LOG` moves it). Tags only: `~/.bench/device-tags.json` (`tag_device`). Nothing else is written. |
| Secrets | Bench stores no credentials and needs none. Its settings are environment variables only, and it never returns them to the model. |
| Read-only tools | 13: `ping`, `list_usb_devices`, `get_device_info`, `identify_device`, `list_serial_ports`, `hub_topology`, `power_info`, `monitor_events`, `diagnose_device`, `device_descriptors`, `serial_read`, `serial_monitor`, `bench_modules` |
| Needs your approval | 7: `eject_device`, `port_reset`, `flash_firmware`, `chip_detect`, `hid_send`, `serial_write`, `serial_write_and_expect`. The client shows each call; the model's own `confirm` flag does not count. `hid_send` needs approval except for its read actions. |
| Changes without approval | `tag_device`, `snapshot_state`, `serial_open`, `serial_close`: open or close a port, or change Bench's own tag and snapshot data. No device write. |
| Startup cost | about 6,000 tokens (24 tools, 5 skill prompts) |
| Changes | Tool and prompt text is locked by hash (`tool-manifest.lock.json`); CI fails if it changes without the lock. |
<!-- security-card:end -->

## First five minutes

1. Install it: `brew install seayniclabs/tap/bench` (see [Install](#install)).
2. Run `bench --doctor`. It prints one line per check and a `FIX` line for each problem.
3. Connect your AI client (see [Connect your AI client](#connect-your-ai-client)).
4. Ask it to call `bench_modules`. It lists the modules that are on and their tools.
5. Plug in a board and ask: "Which boards are connected, and which serial port is each one on?"

## Audience and modules

Bench is for developers working with connected hardware. It is one server made of modules. You switch modules on or off. Every module that shipped before 0.4.0 is on by default. A module added in a later release ships off, so you choose to turn it on.

| Module | Status | What it does |
|--------|--------|--------------|
| `core` | Ready (always on) | Health check and module discovery |
| `usb` | Ready | Enumerate, identify and inspect USB devices; hub tree; power; events; snapshots; port reset; eject |
| `serial` | Ready | List serial ports; open, read, write, write-and-expect, monitor and close them |
| `firmware` | Ready (needs the flashing tool installed) | Detect chip type; flash with esptool, dfu-util, avrdude or UF2 |
| `hid` | Ready | Send and read raw HID reports |
| `debug` | Ready, off by default (new in 0.4.0) | Decode ESP32 Guru Meditation and ARM HardFault dumps into source lines with addr2line |

Linux is not in this release. It is planned behind the same tools.

## Skills

Skills are short, tested guides for the jobs Bench does. Any app that speaks MCP gets them as prompts (one per skill) and resources (every file in the skill). Apps that read Agent Skills directly load the same `skills/` folder.

| Skill | Use it for |
|-------|-----------|
| `getting-started` | Setting up Bench, switching modules, reading approvals and errors |
| `board-bring-up` | Taking a new board from USB to a working serial round trip |
| `serial-debugging` | Garbled, silent, looping or unresponsive serial output, and crash dumps |
| `safe-flashing` | Flashing firmware: checking the target and the file, then the approved write |
| `systematic-debugging` | Finding the cause of a bug before changing code (credited, see [CREDITS.md](CREDITS.md)) |

## Tools

25 tools in total. 24 are on by default; `decode_crash` needs the `debug` module.

**core**: `ping`, `bench_modules`

**usb**: `list_usb_devices`, `get_device_info`, `identify_device`, `eject_device`, `hub_topology`, `tag_device`, `port_reset`, `power_info`, `monitor_events`, `snapshot_state`, `diagnose_device`, `device_descriptors`

**serial**: `list_serial_ports`, `serial_open`, `serial_read`, `serial_write`, `serial_write_and_expect`, `serial_close`, `serial_monitor`

**firmware**: `chip_detect`, `flash_firmware`

**hid**: `hid_send`

**debug**: `decode_crash`

Call `bench_modules` first to see what is on and how to change it.

## Settings

All settings are environment variables. Bench starts with an empty environment, and a tool call tells you which variable is missing.

| Variable | Default | Effect |
|----------|---------|--------|
| `BENCH_MODULES` | the defaults | Comma list of modules to enable, for example `usb,serial`. `core` is always on. |
| `BENCH_<MODULE>_ENABLED` | per module | `1` or `0` to switch one module on or off, for example `BENCH_DEBUG_ENABLED=1`. Overrides `BENCH_MODULES`. |
| `BENCH_APPROVE_DEVICE_WRITES` | off | `1` pre-approves device-changing calls so they run without a prompt. See Safety. |
| `BENCH_APPROVAL_LOG` | `~/.local/state/bench/approvals.jsonl` | Where the approval log is written. |
| `BENCH_ADDR2LINE` | found on PATH | Full path to the addr2line that `decode_crash` runs. |
| `BENCH_SKILLS_DIR` | found next to the binary | Folder of skills to serve, when it is not beside the binary. |

## Safety

Bench can change hardware, so some calls are gated.

- **Device writes need approval.** `serial_write`, `serial_write_and_expect`, `flash_firmware`, `port_reset`, `eject_device`, `chip_detect` (it resets the chip into its bootloader), and `hid_send` with an action other than `get_report` or `list_reports` change a device or its state. Your client asks you through its approval prompt, and the prompt shows the full arguments. A flag from the model, such as `confirm: true`, does not count as approval.
- **Clients that cannot show a prompt are refused.** Set `BENCH_APPROVE_DEVICE_WRITES=1` in the server's environment to allow writes without a prompt. Only do this when you trust every tool call your AI client makes.
- **Every approval is logged.** Each request, grant, decline and refusal goes to the approval log. Payloads and file contents are not written there.
- **Reads are not gated.** Discovery, monitoring, serial reads and `serial_monitor`, `diagnose_device`, and crash decoding run without a prompt.
- **Local only.** Bench makes no network calls and needs no root. Serial access on Linux (future) will need the `dialout` group, not sudo.

See [SECURITY.md](SECURITY.md) for the reporting policy and the list of what Bench touches.

## Errors

Every error reads `bench.<module>.<code>: <message> Fix: <hint>`, for example:

```
bench.serial.write_not_approved: serial_write changes a device and no approval was given. ... Fix: Set BENCH_APPROVE_DEVICE_WRITES=1 in the server's environment and restart it, or use a client that supports MCP elicitation.
```

Every tool result also has `structuredContent` with `ok`, `module`, `tool` and `text`.

## Install

### Claude Desktop (MCP Bundle)

Download `bench-<version>-darwin-universal.mcpb` from the [latest release](https://github.com/seayniclabs/bench/releases/latest) and open it: Claude Desktop shows the install dialog. The bundle carries the binary (Apple Silicon and Intel, macOS 14 or later) and the skills, so it needs neither Homebrew nor Xcode. The binary is ad-hoc signed, not notarized. Check the download against the `.sha256` file next to it in the release.

### Homebrew

```bash
brew install seayniclabs/tap/bench
bench --doctor
```

The formula builds from source with Swift, so it needs Xcode 16.3 or later. It installs the binary as `bench` and the skills to `share/bench/skills`, next to it.

### Pinned install

Use this when you want exactly the 0.4.3 source, not whatever the formula points at:

```bash
git clone --branch v0.4.3 https://github.com/seayniclabs/bench.git
cd bench
swift build -c release
codesign --force --sign - --entitlements Sources/Bench/Bench.entitlements .build/release/Bench
.build/release/Bench --doctor
```

The skills are read from `skills/` in the checkout, because the build directory sits inside it.

### Claude Code plugin

The repository also packages Bench as a Claude Code plugin (`.claude-plugin/plugin.json` and `.mcp.json`): the server and its skills in one install. The plugin runs the `bench` binary from your PATH, so install Bench with Homebrew first. Then add the Seaynic Labs marketplace and install the plugin:

```
/plugin marketplace add seayniclabs/plugins
/plugin install bench@seayniclabs
```

## Connect your AI client

Bench speaks plain MCP over stdio. Use the full path to the binary in each snippet.

**Claude Code**

```bash
claude mcp add bench -- $(which bench)
```

**Claude Desktop** (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "bench": {
      "command": "/absolute/path/to/bench",
      "args": []
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "bench": {
      "command": "/absolute/path/to/bench",
      "args": []
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`)

```json
{
  "servers": {
    "bench": {
      "type": "stdio",
      "command": "/absolute/path/to/bench",
      "args": []
    }
  }
}
```

To set a variable, add an `env` object next to `args`, for example `"env": { "BENCH_DEBUG_ENABLED": "1" }`.

## Try these

- "Which boards are connected to this Mac, and which serial port is each one on?"
- "Identify the board on /dev/cu.usbserial-2120 and tell me its exact chip."
- "Bring up my ESP32: confirm the chip, read its boot output, and check it answers `ping`."
- "My ESP32 keeps rebooting. Decode the crash in this log against `build/firmware.elf`."
- "Flash `build/firmware.bin` onto the board with serial number ABC123. Ask me to approve it first."

## How it works

Bench uses Apple's [IOKit](https://developer.apple.com/documentation/iokit) framework to enumerate USB devices. It adds serial port detection (`/dev/cu.*`), storage details from `diskutil`, and a built-in database of known maker boards. It talks to your AI tool over stdio using the [Model Context Protocol](https://modelcontextprotocol.io).

```
AI client  --stdio/JSON-RPC-->  Bench  --IOKit-->      USB device tree
                                       --diskutil-->   storage info
                                       --/dev/cu.*-->  serial ports
                                       --device DB-->  board recognition
                                       --addr2line-->  crash decoding (debug module)
```

## Build and test

```bash
swift build             # debug build
swift build -c release  # release build
swift test              # unit tests and stdio tests
```

Bench requires Swift 6.1 or later and targets macOS 14 or later. The tests start the built binary with an empty environment, so run `swift build` before `swift test` if you change the server.

The checks that CI and release runs use:

```bash
python3 scripts/check_skills.py           # every skill has license, source and credit; no site links in bodies
python3 scripts/tool_lock.py --check      # tool, prompt and instruction text matches the lock
python3 scripts/security_card.py --check  # the security card above is current
python3 scripts/mcpb_manifest.py --check  # manifest.json lists the tools and prompts the binary serves
scripts/pack_mcpb.sh .build/release/Bench dist  # pack the MCP Bundle and check it unpacked
python3 scripts/scan_identifiers.py .     # no private identifiers in the tree
```

After you change a tool, prompt or the instructions, run `python3 scripts/tool_lock.py` and `python3 scripts/mcpb_manifest.py`, and add a changelog line in the same change. After you change the card's inputs, run `python3 scripts/security_card.py` and paste its output between the card markers.

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## License

MIT. Published by Seaynic Labs. Third-party material is listed in [CREDITS.md](CREDITS.md).

---

**Built by [Seaynic Labs](https://seayniclabs.com).** We build tools like this around a business's own systems: local-first, with a person approving every change. [See custom integrations](https://seayniclabs.com/#business).