Bench

Bench

Made by Seaynic Labs. Need tools like this built around your own systems? We do that.

USB hardware discovery for your AI tools.

Bench is a native macOS MCP server 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.

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.

First five minutes

1. Install it: brew install seayniclabs/tap/bench (see 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).
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)

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 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 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

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:

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

claude mcp add bench -- $(which bench)

Claude Desktop (claude_desktop_config.json)

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

Cursor (~/.cursor/mcp.json)

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

VS Code (.vscode/mcp.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 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.

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

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:

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.

License

MIT. Published by Seaynic Labs. Third-party material is listed in CREDITS.md.

---

Built by Seaynic Labs. We build tools like this around a business's own systems: local-first, with a person approving every change. See custom integrations.