Openbaud

What Leonezz/openbaud does

Leonezz/openbaud gives coding agents a structured way to inspect and operate local serial devices. Instead of treating a device session as an unstructured stream of bytes, it records exchanges, validates frames, parses response fields, and returns typed results. Device knowledge is stored alongside a project in profiles, commands, workflows, notes, captures, audits, and derived reports.

The system is designed for exploration that can become repeatable. Verified behavior can be expressed as reviewable YAML commands and fixed workflows, with provenance tied to the captures used during analysis. It can also process data that a device sends without a direct request, validating each frame as it arrives.

How it works

A typical flow connects a serial device, identifies it using USB metadata, starts in read-only mode, and preserves a lossless capture. Commands describe protocol layouts and parsing rules, including checksums, scalar values, bit fields, lists, and record arrays. Parsed results are returned in structured form rather than as raw byte dumps.

Commands may declare prerequisites describing the device state they require. OpenBaud rejects a command before sending bytes if the session has not established that state. An explicit override is possible with assume_preconditions; that decision is recorded in both the result and the audit trail.

Captures use the .obcap format and retain RX and TX bytes. The same command and parser can run against a capture through a replay port, allowing protocol work and demonstrations without connected hardware. The included ESP32 example replays a real-device capture and decodes CRC-16-checked responses into polar-point records.

Setup and configuration

The documented installation path registers the Git repository as the openbaud-marketplace Codex marketplace, then installs the openbaud plugin:

codex plugin marketplace add Leonezz/openbaud --ref stable
codex plugin add openbaud@openbaud-marketplace

The plugin includes five native MCP runtimes and chooses the matching local runtime when it starts. Its portable launcher requires Node.js 18 or newer. The installation does not require Rust, Cargo, Homebrew, an install hook, or a runtime download. Supported host platforms are macOS ARM64 and Intel, Linux x64 and ARM64, and Windows x64.

For an immutable installation, use a versioned marketplace archive from GitHub Releases and register its extracted local path. After marketplace updates, start a new Codex task. The schema MCP tool and the openbaud schema CLI command define the current profile, command, and workflow formats.

Tools and capabilities

• Identify serial devices using USB metadata.
• Send typed YAML commands and run fixed workflows.
• Validate checksums and decode structured protocol fields.
• Record append-only audits and lossless .obcap captures.
• Replay commands and parsers without physical hardware.
• Enforce device-state prerequisites before writes.
• Require explicit acknowledgement for commands marked risk: danger.
• Expose the current workspace schemas through the schema MCP tool.

Limitations and notes

Serial writes may reconfigure hardware or actuate physical equipment. Raw writes and device commands are treated as potentially destructive operations, so unknown devices should be approached read-only and given a recovery path before state changes.

Replay is based on recorded exchanges and is intended to run the same command and parser against captured data; it does not replace live-device verification. macOS binaries in the preview distribution are ad-hoc signed and are not Apple-notarized. The Codex plugin targets the host platforms listed above and requires a new task after updates.