`rtl_buddy`

rtl_buddy is a Python CLI for Verilog and SystemVerilog RTL design and verification workflows: simulator-driven tests and randomized regressions, filelist generation, synthesis, place-and-route, power analysis, formal property verification, mutation testing, waveform viewing, hierarchy rendering, AXI interconnect profiling, spec traceability, and adjacent automation. It is designed to work well for both humans and AI agents.

It is built to sit on top of the tools your project already uses, while giving you a cleaner, more repeatable interface for day-to-day RTL work. Current first-class flows cover Verilator/VCS simulation (with optional cocotb), Yosys synthesis (with optional yosys-slang frontend), OpenROAD-based place-and-route and power analysis, SymbiYosys formal verification, and Surfer-based waveform viewing with live editor annotation. Verible command integration covers lint, syntax, format, preprocessor, and verible.filelist generation; broader first-class Verible and PeakRDL workflows are on the roadmap.

Typical commands look like:

uv run rb test basic
uv run rb test smoke --repeat 20
uv run rb regression
uv run rb regression --coverage-merge
uv run rb synth -c synth/sandbox/synth.yaml
uv run rb fpv -c fpv/sandbox/fpv.yaml
uv run rb wave basic
uv run rb axi-profile run basic
uv run rb tool-check

Why `rtl_buddy`

rtl_buddy gives RTL projects a lightweight control plane for common verification tasks:

Run a single test or a full regression from YAML config instead of ad hoc shell scripts
Keep simulator invocation, seeds, logs, and result handling consistent across runs
Manage filelists easily with project model definitions
Add sweep generation, preprocessing, and postprocessing hooks without rewriting the main flow
Export machine-readable logs that work well in CI and AI-agent-driven workflows

Features

Test and regression commands: run one test, many tests, or whole suites with a consistent CLI across Verilator and VCS
Randomized testing support: create new seeds, repeat runs, and replay previous randomized iterations
Structured config model: describe suites, regressions, platforms, builders, and models in readable YAML
Filelist generation: build simulator-ready filelists from models.yaml
Fast model elaboration (rb elab, rb elab-regression): parse, type-check, and elaborate existing models.yaml filelists with optional pyslang profiles and structured artifacts
Synthesis flows (rb synth): run Yosys synthesis from synth.yaml, including optional Liberty-mapped runs, synthesis regressions, configurable effort levels, and an optional yosys-slang frontend; OpenROAD is also available as an alternative backend
Place-and-route (rb pnr): OpenROAD-driven flow that consumes the post-synth netlist and produces routed DEF, post-route netlist + SDC, and timing/DRC reports
Power analysis (rb power, rb power-regression): OpenROAD report_power over post-synth or post-PnR netlists, with static, synthetic, or SAIF/VCD activity sources (rb saif converts FST/VCD traces to SAIF v2.0)
Formal property verification (rb fpv, rb fpv-regression): SymbiYosys-driven proofs with reproducible solver pinning; rb wave-fpv opens the counterexample VCD for a failed run
Mutation testing (rb mut): scores how well a verification suite catches injected bugs by mutating a design file and checking whether an FPV proof or a simulation/assertion oracle kills each mutant (via the optional rtl-buddy-xeno engine)
Waveform viewing (rb wave): opens Surfer with live signal-value annotation in your editor via the WCP protocol
Hierarchy rendering (rb hier): module hierarchy diagrams via rtl-buddy-view, with optional clock-domain annotations
AXI interconnect profiling (rb axi-profile): discover AXI bundles from RTL, emit a bind-style SV monitor, ingest a test's FST into per-test axi-perf.json + per-transaction Parquet, and launch a packaged marimo notebook for interactive analysis
Coordination hub (rb hub): TCP + HTTP/WebSocket broker that mediates between the rtl-buddy-view SPA, Surfer (via rb wave), and editor adapters, and serves the graph (/gph), coverage (/cov), and physical-metrics (/phy) panes; supports runtime model switching, AXI-perf overlays, and cross-pane focus; optional macOS LaunchAgent install
Physical metrics (rb phys): query the merged synthesis + power model — per-module gate counts and area, per-instance power, and a provenance-labelled run listing (rb phys summary/module/instance/runs); the same model drives the hub's /phy pane with heat-shaded tables and a run selector
Spec traceability (rb spec): trace specs.yaml items to design models (check-design) and tests (check-coverage)
Tool dependency check (rb tool-check): declarative manifest of external tool dependencies — reports which rb subcommands are ready and which are blocked on missing or out-of-version tools
Coverage workflows: collect, merge, summarize, and export Verilator coverage
cocotb support: Verilator + VPI cocotb tests integrated into the standard test/regression flow
Hookable execution flow: plug in your own sweep generation, test preprocessing, and postprocessing scripts
Verible integration (rb verible): invoke lint, syntax, formatting, and preprocessor commands through the same project config, plus generate verible.filelist from models.yaml for verible-verilog-ls
Rich outputs for humans: displays pretty formatted for easy reading
Structured logging for machines: emits JSONL logs for interpretation by CI systems, automation, and coding agents
Cross-project reuse: keep one tool interface while adapting it to different RTL repo layouts and builder setups

Installation

rtl_buddy is available on PyPI and installed into your project environment with uv:

uv add rtl_buddy

For local development in this repo, install the composite dev group:

uv sync --group dev
npm ci                    # required only for documentation builds
uv run ruff check
uv run ruff format --check
uv run pytest

Prerequisites:

Python 3.11+
uv

Beyond Python and uv, every other dependency is feature-dependent: which external tools you need depends on which rb commands you use. For example, rb test needs a simulator (Verilator / VCS), rb synth needs the rtl-buddy/yosys fork, rb pnr and rb power need OpenROAD, rb fpv needs SymbiYosys plus an SMT solver, rb hier needs rtl-buddy-view, and rb wave needs the rtl-buddy/surfer fork.

See the installation page for the full feature-to-dependency matrix, including integration types (Integrated tool vs Pluggable vs Pluggable — curated) and install commands.

Documentation

Full documentation is at rtl-buddy.github.io/rtl_buddy.

The Docusaurus site also publishes version-pinned agent resources at <version>/llms.txt and <version>/agent/catalog.json. For an installed version without network access, use rb docs list and rb docs show.

Quick Start

The fastest way to get started is the rtl-buddy project template — a ready-to-run RTL project with example designs, tests, and full rtl_buddy integration.

Once you have a project set up, the basic commands are:

uv run rb test basic      # run a single test
uv run rb regression      # run the full regression
uv run rb synth -c synth/sandbox/synth.yaml

For full usage, see the Quick Start guide.

Runtime artefacts are stored under artefacts/{sanitized_test_name}/. Single runs write files such as test.log, test.err, test.randseed, and coverage.dat there directly, while repeated runs use nested directories such as artefacts/{sanitized_test_name}/run-0001/. The suite root always keeps test.log, test.err, and test.randseed symlinked to the latest run for convenience.

Known Issues

See the known issues page.

Release files for rtl-buddy 6.51.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rtl-buddy 6.51.0
File	Size	Uploaded
rtl_buddy-6.51.0.tar.gz	1.5 MB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for rtl-buddy 6.51.0
File	Interpreter	ABI	Platform	Reset
rtl_buddy-6.51.0-py3-none-any.whl 1.6 MB Sep 18, 2026	Python 3	none	any	Details

Total release size: 3.1 MB

Release files / rtl_buddy-6.51.0.tar.gz

Download URL	rtl_buddy-6.51.0.tar.gz
Size	1.5 MB
Tags	Source
SHA-256 checksum How to use checksums	`c45c336bd69ed38eebcd043207f28c3b01778d9158aab34d039d6323676f5d9e`
BLAKE2b-256 checksum How to use checksums	`0552f06fc779f259f9e24c96c19b7f89c7ad5bddeba21aebec9ea7b819def400`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/rtl-buddy/rtl_buddy
Publishing commit: github.com/rtl-buddy/rtl_buddy/tree/a138f8736ed6aa7fa10f0cf28b8fdca759eee082

Workflow

Publishing configuration: github.com/rtl-buddy/rtl_buddy/blob/a138f8736ed6aa7fa10f0cf28b8fdca759eee082/.github/workflows/release.yml
Publishing logs: github.com/rtl-buddy/rtl_buddy/actions/runs/35334996597/attempts/1

Artifact

Subject: rtl_buddy-6.51.0.tar.gz
SHA-256 checksum: c45c336bd69ed38eebcd043207f28c3b01778d9158aab34d039d6323676f5d9e Verifying attestations

Release files / rtl_buddy-6.51.0-py3-none-any.whl

Download URL	rtl_buddy-6.51.0-py3-none-any.whl
Size	1.6 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`b567480bac98db3ae5e5e74f77fa62baf8c797132b58b749e7a4f7e654c485c3`
BLAKE2b-256 checksum How to use checksums	`40a0db1789b0bfc9a0e2db74ed2ee20c99434e4fbde284384e56493afd3be70d`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/rtl-buddy/rtl_buddy
Publishing commit: github.com/rtl-buddy/rtl_buddy/tree/a138f8736ed6aa7fa10f0cf28b8fdca759eee082

Workflow

Publishing configuration: github.com/rtl-buddy/rtl_buddy/blob/a138f8736ed6aa7fa10f0cf28b8fdca759eee082/.github/workflows/release.yml
Publishing logs: github.com/rtl-buddy/rtl_buddy/actions/runs/35334996597/attempts/1

Artifact

Subject: rtl_buddy-6.51.0-py3-none-any.whl
SHA-256 checksum: b567480bac98db3ae5e5e74f77fa62baf8c797132b58b749e7a4f7e654c485c3 Verifying attestations