Agentic HIL

Your AI agent writes the firmware, flashes it to the board on your desk, drives UART and CAN against it, reads back what the hardware actually did, and fixes what it got wrong; the run on the real board is what decides whether the work is done, and you review the pull request with that run's evidence in it.

https://github.com/user-attachments/assets/8d39ba93-beeb-484e-b9e9-d9ce79538523

Nothing in that run is staged. One restart after the install line, in a freshly created firmware project, the first sentence makes the agent set the bench up itself and the second makes the board say Hello World and prove it said it: the configuration is created over MCP with the permissions reported out loud, the firmware is written on the spot, flash_firmware and com_read go through the gate, the twelve bytes come back off the wire, and the plan it pins is run once green and once against a wrong expectation, because a test that cannot fail proves nothing. What remains in the project afterwards is the plan as a reviewable file and the run's own report: lease released, safe state confirmed, nothing quarantined.

Install

Linux / macOS (any shell):

curl -LsSf https://agentic-hil.github.io/install.sh | sh

Windows, in PowerShell:

irm https://agentic-hil.github.io/install.ps1 | iex

The command lands in the user bin directory of the package manager that installed it, and the installer asks that manager where it went rather than assuming: uv tool dir --bin for a uv install, and the selected interpreter itself for a pip --user one. When that directory is not on your PATH already, the installer puts it there and says so: one line in the one shell profile your shell reads, or on Windows the directory in front of your own Path. Open a new shell and the command is there. Pass --no-path (-NoPath in PowerShell) to keep that edit for yourself, and the installer prints the exact line instead.

One line installs the package user-local and registers the agent skill and the MCP server for every agent CLI it finds on your PATH. No admin rights required, ever, and it touches nothing inside any repository. Finding no claude, codex or opencode CLI there, it says so and writes nothing of any agent's: install the agent CLI, then run agentic-hil agent-install --agent <claude-code|codex|opencode> yourself, which is the line the installer prints for that case. Then restart your agent once, and after that one restart your agent sets this project up itself, at the first hardware question you ask it.

The line above and the checksummed route in installation run the same installer, and on a machine with nothing here yet both install the same thing, the release from PyPI: the script resolves agentic-hil[can] against the package index and carries no branch or git reference at all, and --version <x.y.z> pins one exact release instead. On a rerun it repairs what is already installed rather than forcing the public release over it: an installation reporting a .devN version (an editable checkout of this repository) is kept untouched, and a uv-managed tool installed from a path, URL or git reference is refreshed from that same recorded source rather than switched to the index. What the checksummed route adds is the script itself, read before it runs: install.sh and its install.sh.sha256 come from the same release, one is checked against the other, and the file that runs is the file you checked.

The STM32 starter is the shortest way to watch that happen on hardware: three steps on a Nucleo-F446RE, with the firmware, the test plans and one planted defect already in place.

Claude Code can also take the skill from the plugin marketplace: /plugin marketplace add agentic-hil/agentic-hil, then /plugin install agentic-hil@agentic-hil. The plugin carries the skill and nothing else; the MCP server itself still comes from the install line above, which registers a verified absolute executable path outside your repository.

Installation has every other path: the cmd.exe spelling, the repair run (the same line again, which reinstalls in place when agentic-hil upgrade itself fails), that checksummed route in full, registering one agent instead of all of them, driving your own package manager, setup for a bench that is already attached, the optional extras, upgrading, and every platform and debugger backend. TROUBLESHOOTING.md covers what to do when something does not start.

A first command that needs no board, in a clone of this repository: agentic-hil check-plan examples/nucleo-f446re_demo/testconfig.yaml answers All 1 test plan(s) load through the reactor's loader. and exits 0, having loaded no configuration and touched no hardware.

Agentic Hardware-in-the-Loop (Agentic HIL) is a Python package that lets a coding agent develop firmware on the real board. It exposes bounded MCP tools for probing, flashing, resetting, artifact validation, serial and CAN stimulus/feedback, reports, and logs, all without giving an agent arbitrary host or debugger access. The run on the board is the gate: the work is done when the hardware behaved, and the report that run writes is the evidence a reviewer reads. What it supports is the debug probe with its backend rather than a board, ST-Link through OpenOCD or the STM32CubeProgrammer CLI and CMSIS-DAP probes through pyOCD, so any board behind such a probe runs the same software. Each project has exactly one authoritative configuration stored outside the repository, out of reach of the agent's own file tools.

Why

A green build is not enough in embedded development: firmware has to behave correctly on the real board, so the run on that board is the gate the work has to pass before it is done. Classic tools automate single steps (flash here, read a log there), but the moment real hardware has to respond, a human is back in the loop, which is what stops an agent from developing firmware through to that gate. Handing an agent a raw debugger shell or direct serial access instead is neither safe nor reproducible, and leaves a reviewer nothing to read.

Agentic HIL closes the gap with a small, auditable gate:

Every hardware action is validated against the selected authoritative configuration, executed with timeouts, logged to .agentic-hil/logs/, and answered with a structured JSON result (ok, error_type, summary, likely_causes, report_path, log_path) that an agent can act on and a reviewer can read afterwards. What the agent may do at all is per device and per permission, and reaching for a debugger escape hatch is what takes flashing away.

What it drives

The unit it drives is the probe with its backend, not one board: three debugger backends (OpenOCD, pyOCD, and the STM32CubeProgrammer CLI), plus serial ports and CAN (PCAN, SocketCAN, or a custom bridge; several runs can share one bus), on Linux, macOS, and Windows, Python 3.10 or newer, all CI-tested. The worked example in examples/nucleo-f446re_demo/ runs the whole loop on an ST Nucleo-F446RE, the board this repository proves the path on rather than the boundary of what runs; installation has every backend and platform in detail.

The test reactor

A plan is how the gate is written down, and one YAML plan drives the whole bench: flash, reset, write, read with a comparator (exact text, a pattern, or a numeric range over a captured value), delays, and sessions that close themselves. Plans name logical devices; the bench configuration binds them to real hardware, so the same plan runs unchanged on every machine that has one. A failing step aborts the run, and the bench recovers itself: reap, reset into halt, probe, all attested in the run result. How plans work.

Security by construction