booley-rtl 0.1.0

Orchestrated RTL development harness with ticket-based workflow automation

Booley

Agentic RTL development framework — sandboxed EDA flows driven by AI agents

It's 2026, and LLMs are finally good enough to do real work. Software already accepts this: agents write more and more of the code while humans move up to architecture, specification, review, and integration. Hardware moves slower, but it moves: every major EDA vendor and a wave of startups are shipping AI tools for chip design. Those tools are closed, expensive, and out of reach if you don't work at a big company. I hit that wall myself, and raw agents like Claude Code and Codex kept failing on RTL work in the same predictable ways. So I built the tool I was missing: free and open source.

The idea:

1. Take the most capable coding agents available (Claude Code, Codex).
2. Put them in a sandbox with the repo under development, blocking access to the host, so they can run without asking for permissions.
3. Give them quick, one-command access to an open-source sim/lint/synth/waveform stack inside the sandbox, so they can check their own work and iterate fast.
4. Wrap it all in one IDE: VS Code.

A harness checks the agent's claims against real tool results (see below for the protection measures), and you choose how to drive it: hands-on in a chat, or hand it a self-contained ticket and let it run.

What Booley Solves

Dropping a capable model into an RTL repo is not enough. I tried it. The toolchain is fragmented (every EDA tool speaks its own CLI, every coding agent its own protocol), and even once that's unified, a handful of failure modes make naive agentic hardware work unreliable. Booley puts one interface over every tool and every agent, then hardens it against the failure modes below.

A fragmented toolchain, one interface

An RTL flow is a pile of tools that share nothing: Verilator, Icarus, Yosys, plus licensed heavyweights like Vivado or Xcelium, each with its own CLI, flags, and output format. The agent driving them is a moving part too: today Claude Code, tomorrow Codex. Wire an agent straight into that mess and you get N tools × M agents of brittle glue. Booley collapses it to one:

• One typed surface over every tool: every EDA tool is a B-Tool: the same structured call in, the same normalized verdict out, whether it runs in the sandbox (Verilator, Icarus, Yosys, sv2v, bwave) or crosses the adapter boundary to a licensed tool on the host (Vivado, Xcelium, VCS). The agent learns one interface, not one per tool (details).
• Agent-agnostic: the same B-Tools are exposed over MCP, which Claude Code and Codex both drive natively. Pick the model you want; the toolchain stays identical (details).
• One environment: editor, tools, and agent share a single VS Code window. No context switch between where you write RTL and where you run it: that's what makes VS Code the agentic RTL IDE the toolchain never had.

Hallucination and unreliability

Left to its own judgment, an agent will declare a task done that it never finished, "pass" a test by misreading a log, or quietly run the wrong configuration. I've watched all three happen. Booley replaces the agent's judgment with machine-checked facts:

• Config and test registry: config and test arguments resolve to named entries in Booley's shared configuration, not ad-hoc command lines. A request to run one test resolves to exactly that test, and the report carries the resolved identity, so the agent can't fool itself about what ran (details).
• Acceptance criteria: Ticket Mode drives toward explicit criteria (sim_pass, lint_clean, synthesis_pass), and the ticket cannot complete until the harness, not the agent, confirms every mandatory one (details).
• Structured tool contracts (B-Tools): a tool call returns a normalized verdict (pass / fail / inconclusive / timeout) instead of raw terminal output for the agent to (mis)interpret. A criterion is satisfied only when the tool itself returns a valid pass (details).

You can't let an agent loose on your machine

Autonomous work only pays off when the agent doesn't stop to ask permission at every step. But I'm not giving a capable, fallible model that's steerable by whatever text it reads free rein on my machine. The sandbox turns each failure mode into a contained non-event:

• Prompt injection: text in a datasheet or web page hijacks the agent. Trapped in a container with no host access or general internet, the payload has nowhere to reach.
• Off-script pushes: the agent drifts and "helpfully" commits half-finished work. It only touches an isolated worktree behind a human review-and-merge gate, never your remotes or real branches.
• Accidental damage: a misfired rm or a script in the wrong directory. With only the worktree mounted, the blast radius stops at the sandbox.

That's what makes "let it run autonomously" a sane default instead of a gamble:

• Sandboxed by default: agents run in a container with only the worktree mounted: full autonomy inside, zero host access, network restricted to LLM API endpoints (details).
• Tools run inside too: the sandbox image ships the EDA stack (Verilator, Icarus Verilog, Yosys, sv2v, bwave), so the common flows execute fully contained.
• A safe boundary for heavyweights: when a tool is too heavy or too licensed to containerize (Vivado, vendor simulators), it runs on the host behind a narrow adapter interface, and Booley still sees the same tool contract (details).

Context rot

Long single-context agent sessions degrade: the model loses the thread, gets distracted by stale logs, and quality falls off over a multi-hour task.

• Specialists with isolated context: each Specialist (testbench authoring, code review, mutation testing) runs in a fresh LLM context, so none of them drags along stale logs or drafts from earlier iterations. The orchestrator carries continuity through structured state, not an ever-growing conversation (details).

Debugging blind

A waveform is how a hardware engineer actually debugs. But an LLM can't read a multi-gigabyte VCD, so without one the agent is reduced to guessing about the code. So I wrote it a waveform tool:

• Waveform-aware debug (bwave): a Rust tool that lets the agent query signal values over time ranges, trigger sampling of one signal on another, and trace data through the design, debugging from observed behavior, not speculation. The simulator streams its VCD through an in-RAM FIFO that bwave compacts into a .bwave cache on the fly, so the multi-gigabyte VCD never touches disk; even 10 GB+ traces stay tractable and the tracing overhead stays small (details).

Weak testbenches

Agents work best against a concrete criterion. For RTL that criterion is the testbench: the agent writes and fixes the design until the testbench passes. But nothing judges the testbench: a weak one passes no matter what, and a green run tells you nothing about whether the design was actually exercised.

• Mutation testing: Booley injects targeted bugs into the RTL and checks whether the testbench catches them, scoring the detection rate against a threshold. "Tests pass" becomes "tests pass and are proven to catch real bugs." The testbench is the RTL's criterion; mutation testing is the testbench's (details).

Booley does much more than this: coverage measurement, multi-phase code review, automated SVA generation, lint triage, scope enforcement, and more. See FEATURES.md for the full list.

Modes of Operation

Two modes, same project configuration, same tool stack, same per-folder sandbox container (the Session Runtime), just two ways to drive it.

Interactive Mode

The hands-on path. Open your RTL repo in VS Code, accept "Reopen in Container", and the window reloads inside a Booley runtime container with everything it needs: simulators, lint, synthesis, waveform tools, and the specialist agents. The container comes from an untracked .devcontainer/devcontainer.json that booley init writes into the repo (hidden from git via .git/info/exclude, never committed). Egress is restricted to a Booley proxy, the agent runs as a non-root user, and an idle reaper stops orphaned sessions.

From there you just chat: what to inspect, which simulation to run, what failure to debug, what code to review, which waveform to query. You guide the work closely and make decisions as they come up. (booley_status at the start of a session shows the sandbox container id and available tools.)

Ticket Mode

The autonomous path. You write a ticket (the ticket-creation skill helps) specifying what needs doing, which files are in scope, which tests must pass, and any other completion criteria. Then booley run from a terminal inside the devcontainer, one terminal per concurrent ticket alongside your interactive session, and Booley does the rest: isolated worktree, orchestrator, specialists, EDA tools, criteria tracking, all the way to completion.

When the ticket reaches review, you inspect the result, adjust if needed, then approve and merge into your working branch.

Limitations

• Booley will not design hardware for you. You design the architecture and write the specs; Booley handles the grunt work. Force multiplier, not replacement.
• Testbenches are simple and direct. Plain SystemVerilog, no UVM.
• Only tested at the IP level. Complex IPs, like a RISC-V core or crypto accelerators, but never chip- or SoC-level integration.
• Setup can take effort. The setup skills make integration as smooth as I could get it, but every build system is different; complex flows or heavy licensed EDA tools may still need project-specific work.
• The code quality is "hardware engineer writing software." The architecture is sound, but the Python could use polish. Contributions from actual software developers are very welcome.
• Work in progress. Expect occasional bugs and rough edges in the UI. I'm actively on it, and things keep getting better.

Quick Start

Three ways in, ordered by how much you want to invest:

1. Level 1: Watch. See an engineer drive Booley on a demo project, start to finish. Zero setup.
2. Level 2: Try the demo yourself. Clone a pre-configured demo repo and run its tickets out of the box.
3. Level 3: Use it on your own project. Full integration on your own RTL.

Level 1 — Watch (2 min)

Coming soon. A short screencast of me driving Booley on a demo project end to end (feasibility triage, ticket run, results) so you can see the workflow before touching anything.

Level 2 — Try the demo yourself

Demo repo coming soon. A well-known open-source IP with pre-configured Booley tickets, ready to run out of the box: no /booley-setup needed, since the design description, tests, and config already ship in the repo. The steps below are the flow you'll follow once the link is live.

The prerequisites and platform notes below apply to Levels 2 and 3 alike.

Supported platforms: Windows (yes, you can now design hardware on Windows), Linux (Ubuntu 24.04 tested). macOS is not supported.

Windows. Booley runs natively on Windows: install the CLI with Windows Python, keep your repo on a normal C:\... path, and let Docker Desktop (WSL2 backend) host the containers: no WSL shell needed, no repo on the WSL filesystem. Three Windows-specific gotchas:

• Python: a fresh Windows has only the Microsoft Store aliases (python/python3 open the Store instead of running). Install a real one first, e.g. winget install Python.Python.3.13.
• Docker Desktop must be running: its CLI only joins PATH once the app has started; open a new terminal after first launch.
• Line endings: Git for Windows defaults to core.autocrlf=true, which checks files out with CRLF; the Linux container then sees every file as modified. In your RTL repo set git config core.autocrlf false, commit a .gitattributes with * text eol=lf, and re-checkout (git checkout -- .). booley init detects and warns about this.

EDA tool support. First-class today: the open-source stack (Verilator, Icarus Verilog, Yosys, sv2v) plus Vivado for FPGA implementation: built-in flows, no extra work. Cadence Xcelium runs through a built-in host-boundary simulate backend (builtin-host) that loads your tool module and license on the host, validated end-to-end. Full picture in the supported-tools matrix; wire your own commercial flow via a project-native host adapter, or track remaining Big-3 coverage (Design Compiler, Siemens) on the roadmap.

Synthesis is a PPA estimate, not tape-out. The asic_synthesize B-Tool gives you power/performance/area metrics fast enough to iterate the RTL against, not a sign-off, whatever engine backs it (Yosys + OpenROAD today; Genus / Design Compiler may follow). Real tape-out synthesis (physical implementation, CTS, routing, DRC/LVS, multi-corner STA on a foundry PDK) is out of scope for Booley. See SUPPORTED-TOOLS.md.

Prerequisites:

• Python 3.11+
• Docker: hosts the sandbox and tool stack
• VS Code with the Dev Containers extension: Booley runs inside a devcontainer via Reopen in Container
• Credentials for at least one supported agent backend:
  • OpenAI / Codex (default): a ChatGPT Plus subscription ($20/mo minimum) or an OpenAI API key
  • Anthropic / Claude: a Claude Pro/Max subscription or an Anthropic API key

Booley runs on a single provider; select it via booley.toml [agent] provider (codex or claude). Both the orchestrator and all specialists run on the chosen provider.

Note: Booley's agents authenticate the same way Claude Code or Codex do. A subscription (Claude Pro/Max or ChatGPT/Codex) covers both modes, including the nested Specialist agents. An API key is the pay-per-token alternative; if ANTHROPIC_API_KEY is set it takes precedence over a Claude subscription. Auth and billing details in USAGE.md.

# Install Booley
pip install booley-rtl

# Clone the pre-configured demo repo (link coming soon) and enter it
git clone <demo-repo-url>
cd <demo-repo>

# Initialize Booley project state and seed the Interactive Mode devcontainer
booley init

Then open the repo folder in VS Code and accept Reopen in Container. When the window reloads, the agent extension (Claude Code or Codex, whichever you picked during booley init) is already installed, chat panel in the sidebar. The demo ships its design description, tests, and tickets, so there's nothing to configure: run a shipped ticket straight from a terminal inside the container:

# Run an autonomous ticket end to end
booley run --ticket <slug>

Level 3 — Use it on your own project

Same shape: pip install booley-rtl, booley init, Reopen in Container, but instead of shipped tickets you run the /booley-setup skill in the agent chat to onboard your own RTL: feasibility triage, AGENTS.md, FuseSoC .core design discovery, tests, config, and a final booley doctor audit. Then booley run your own tickets.

Do you have to adopt FuseSoC? The built-in flows build from a FuseSoC .core target: the default, simplest path that fits most projects. If you'd rather keep your existing build system (Makefile, vendor-simulator flow, custom scripts), use a project-native adapter: no .core is required and you do not convert your build to FuseSoC.

Full walkthrough, including project-native adapters for commercial EDA flows, is in SETUP.md.

Documentation

• Features: expanded descriptions of all capabilities
• Setup: installation, configuration, advanced backends
• Usage: CLI reference, ticket-driven workflow, acceptance criteria
• Architecture: orchestrator, agentic tools, mechanical tools, context isolation
• Why: the rationale behind the load-bearing decisions (Docker, VS Code, two modes, MCP)
• Benchmarks: results and comparison with related work
• Roadmap: planned features and future directions

Contributing

Contributions welcome. See CONTRIBUTING.md for guidelines.

Acknowledgments

Booley stands on a lot of other people's work. Thank you to:

• The authors of Edalize and FuseSoC, and especially their lead maintainer, Olof Kindgren, for the framework that makes Booley's whole idea of a simple, unified CLI-over-EDA interface possible.
• The author of vcdvcd, Ciro Santilli, for the VCD-parsing work that seeded the bwave idea.
• The author of wavepeek, another neat waveform-to-CLI tool, for the clean top-level CLI interface that inspired bwave's (the internals started well before wavepeek and are quite different).
• The authors of Yosys, Verilator, Icarus Verilog, and sv2v, for the excellent open-source EDA tools that make Booley possible at all.

License

Apache 2.0. See LICENSE for details.