Agentic HIL
About
Policy-gated MCP tools that let coding agents build, flash, stimulate and observe real embedded hardware (OpenOCD, pyOCD, STM32CubeProgrammer, serial, CAN).
Details
- Author
- agentic-hil
- Categories
- Developer Tools, Other
Jump to
Setup
Install Agentic HIL in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/agentic-hil/agentic-hil
Follow the installation instructions in the repository README, then restart your MCP client.
Your AI agent can develop firmware on its own, because Agentic HIL closes the loop with real hardware.
Agentic Hardware-in-the-Loop (Agentic HIL) is a Python package that 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. Each project has exactly one authoritative configuration stored outside the repository, out of reach of the agent's own file tools.
curl -LsSf https://agentic-hil.github.io/install.sh | sh
irm https://agentic-hil.github.io/install.ps1 | iex
powershell -c "irm https://agentic-hil.github.io/install.ps1|iex"
One line installs the package user-local (throughuvwhere it exists,pip --userotherwise) and registers the agent skill and the MCP server for every agent CLI it finds on yourPATH.No admin rights required, ever, and it touches nothing inside any repository: no project configuration is written, no shell profile is edited. Thenrestart your agent once, and after that one restart your agent sets this project up itself, at the first hardware question you ask it.
The same line is also the repair line: run it again on a machine that already has Agentic HIL and it reinstalls in place, which is the way back whenagentic-hil upgradeitself fails.
Prefer to read before you run? Take the script and its SHA-256 from the same release, check one against the other, and run the file you checked:
curl -LsSfO https://github.com/agentic-hil/agentic-hil/releases/latest/download/install.sh curl -LsSfO https://github.com/agentic-hil/agentic-hil/releases/latest/download/install.sh.sha256 sha256sum -c install.sh.sha256 && sh install.sh
iwr -OutFile install.ps1 https://github.com/agentic-hil/agentic-hil/releases/latest/download/install.ps1 iwr -OutFile install.ps1.sha256 https://github.com/agentic-hil/agentic-hil/releases/latest/download/install.ps1.sha256 if ((Get-FileHash install.ps1).Hash -eq (-split (Get-Content install.ps1.sha256))[0]) { .\install.ps1 }
The one-line form above installs from the default branch, which is where a fix lands first; this form installs the release, which is the pair a checksum can speak for.
Pass--agent claude-code(orcodex,opencode) to register one agent instead of all of them,--helpfor the rest; piped, that reads| sh -s -- --agent claude-code. If you would rather drive your own package manager, the same two halves by hand:
uv tool install "agentic-hil[can]" # or: pip install --user "agentic-hil[can]" agentic-hil agent-install --agent claude-code # or: codex / opencode
Installationhassetupfor a bench that is already attached, the optional extras, upgrading, and every platform and debugger backend;TROUBLESHOOTING.mdcovers what to do when something does not start.
One restart after the install line, in a freshly created firmware project: the first sentence makes the agent set the bench up itself, the second makes the board say Hello World and prove it said it.
https://github.com/user-attachments/assets/d19b3b24-0250-4226-91c4-61bea65fa4b2
Nothing in that run is staged: the configuration is created over MCP with the permissions reported out loud, the firmware is written on the spot,flash_firmwareandcom_readgo 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.
A green build is not enough in embedded development: firmware has to behave correctly on the real board. 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. Handing an agent a raw debugger shell or direct serial access instead is neither safe nor reproducible. 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. 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.
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 inexamples/nucleo-f446re_demo/runs the whole loop on an ST Nucleo-F446RE;installationhas every backend and platform in detail.
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.
Deny-by-default permissions per device, every hardware action validated, leased machine-wide, and written to a SHA-256 audit chain. The authoritative configuration lives outside the workspace, where the agent cannot edit it. Enforcement sits in the tool rather than in the agent host on purpose: a host's permission system judges shell strings and differs per host, while the bench's permissions judge the hardware action itself and travel with the bench, so the CLI, pytest, CI and the test reactor all walk the same gate. A failed run still gives the bench back: it aborts with its verdict, the recovery action resets and re-reads the target, and the standing quarantine is kept for the one state no later contact can rebuild, a broken audit trail.The safety modelis the short version,the security designthe long one.
The worked example is a firmware project of its own. Plug the board in, build it, and point Agentic HIL at it from that directory:
cd examples/nucleo-f446re_demo cmake --preset Debug && cmake --build --preset Debug # → build/Debug/nucleo-f446re_demo.elf agentic-hil setup --agent claude-code # or: codex / opencode agentic-hil doctor
doctorchecks the configuration against the attached bench and names what it finds (a missing toolchain, an unreachable probe, a target type this host cannot resolve) before anything is flashed. If the board arrived aftersetupran,agentic-hil adopt-hardwarefills in the probe serial, the backend executable and the COM device it left unset (--dry-runshows the plan first).
With the MCP host started from that directory, the agent drives four calls:
flash_firmware {"image_path": "build/Debug/nucleo-f446re_demo.elf"} com_session_start {"port_id": "dut_uart"} reset_target {"mode": "run"} com_read {"port_id": "dut_uart", "wait_timeout_s": 5} → feedback contains "Hello World"
The same loop runs headless as a pytest regression:pytest tests/in that directory flashes the ELF, resets the target and asserts the boot banner on the UART.examples/nucleo-f446re_demo/walks through both, anddocs/testing.mdcovers writing the run down as a reviewable YAML plan instead.
Names: the Python distribution/install target, CLI command, repository URL, and MCP server name useagentic-hil. Python imports, pytest plugin names, fixtures, and Python examples useagentic_hil.
python -m pip install -e '.[dev]' ruff check src tests evals tools pytest python -m build twine check dist/*
The package is configured for PyPI publishing through GitHub trusted publishing in.github/workflows/workflow.yml. Contribution guidelines:CONTRIBUTING.md.
Policy bypasses are treated as vulnerabilities; seeSECURITY.md.
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
LSP-Claw is an MCP server that lets an AI agent safely build, run, and debug Lua/LSP web apps inside a controlled Mako/Xedge/BAS lab, including on embedded or RTOS devices.
AI-powered live runtime debugging with Lightrun production context.
Run, debug, and triage tests via natural language across HyperExecute, Automation, SmartUI, and Accessibility on the TestMu AI cloud.
Understand, develop, and debug authorization policies in Oso Cloud.
A comprehensive proxy that combines multiple MCP servers into a single MCP. It provides discovery and management of tools, prompts, resources, and templates across servers, plus a playground for debugging when building MCP servers.
Proxyman MCP allows AI to inspect HTTP traffic, create debugging rules, and control Proxyman - all through natural language conversations.
Debug your remote Node.js and Next.js applications directly from your AI IDE like Cursor.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Drives an Android emulator or a real device over adb: screenshots, UI hierarchy with true device-pixel coordinates, tap and type, app lifecycle, logcat, and Gradle builds and tests.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
