`rtl_buddy`

rtl_buddy is a Python CLI for Verilog and SystemVerilog RTL design and verification. It drives the tools your project already uses from YAML configuration, with a consistent interface for humans, CI, and AI agents.

It covers simulation and randomized regressions, filelist generation, synthesis, place-and-route, power analysis, formal property verification, mutation testing, waveform viewing, hierarchy rendering, AXI profiling, and spec traceability.

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`

Run one test or a full regression from YAML instead of ad hoc shell scripts.
Keep simulator invocation, seeds, logs, and result handling consistent across runs.
Define filelists once in project models.
Add sweep and preprocessing hooks without rewriting the main flow.
Export JSONL logs and JSON results for CI and agent workflows.

Features

Tests and regressions (rb test, rb randtest, rb regression): one CLI across Verilator, Icarus Verilog, and VCS, with new-seed, repeat, and replay support. cocotb tests run through the same flow.
Configuration: suites, regressions, platforms, builders, and models in YAML. rb filelist generates simulator-ready filelists from models.yaml.
Elaboration (rb elab, rb elab-regression): parse, type-check, and elaborate models.yaml filelists with pyslang, without building a simulator.
Synthesis (rb synth): Yosys from synth.yaml, with optional Liberty mapping, effort levels, synthesis regressions, and the yosys-slang frontend. OpenROAD is an alternative backend.
Place-and-route (rb pnr): OpenROAD flow from the post-synthesis netlist to routed DEF, netlist, SDC, and timing/DRC reports.
Power analysis (rb power, rb power-regression): OpenROAD report_power with static, synthetic, or SAIF/VCD activity. rb saif converts FST/VCD to SAIF.
Formal verification (rb fpv, rb fpv-regression): SymbiYosys proofs with pinned solvers. rb wave-fpv opens a failed proof's counterexample.
Mutation testing (rb mut): scores a verification suite by mutating a design and checking whether an FPV proof or simulation oracle kills each mutant. Uses the optional rtl-buddy-xeno engine.
Waveforms (rb wave): opens Surfer with live signal values annotated in your editor over WCP.
Hierarchy (rb hier, rb hier-query): module hierarchy diagrams and queries through rtl-buddy-view, with optional clock-domain annotations.
AXI profiling (rb axi-profile): discover AXI bundles, emit a bind-style monitor, turn a test's FST into axi-perf.json and per-transaction Parquet, and open a marimo notebook.
Coordination hub (rb hub): a broker between the rtl-buddy-view SPA, Surfer, and editor adapters. Serves graph (/gph), coverage (/cov), and physical-metrics (/phy) panes.
Physical metrics (rb phys): per-module gate count and area, per-instance power, and a run listing from the merged synthesis and power model.
Spec traceability (rb spec): trace specs.yaml items to models and tests.
Tool check (rb tool-check): reports which rb subcommands are ready and which are blocked on missing or out-of-version tools.
Coverage: collect, merge, summarize, and export Verilator coverage.
Hooks: sweep generation and test preprocessing scripts.
Verible (rb verible): lint, syntax, format, and preprocessor commands, plus verible.filelist generation.
Output for humans and machines: Rich console output, and JSONL logs plus JSON results with --machine.

Installation

rtl_buddy is on PyPI. It needs Python 3.11 or newer and uv:

uv add rtl_buddy

External tools depend on the commands you use. rb test needs a simulator, rb synth needs the rtl-buddy/yosys fork, rb pnr and rb power need OpenROAD, rb fpv needs SymbiYosys and an SMT solver, rb hier needs rtl-buddy-view, and rb wave needs the rtl-buddy/surfer fork. The installation page has the full feature-to-tool matrix.

To develop rtl_buddy itself, install the dev group:

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

Quick start

The rtl-buddy project template is a ready-to-run project with example designs, tests, and rtl_buddy integration. In a project:

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

See the Quick Start guide.

Artefacts go under artefacts/{sanitized_test_name}/. A single run writes test.log, test.err, test.randseed, and coverage.dat there. Repeated runs write to artefacts/{sanitized_test_name}/run-0001/ and so on, and the three top-level test.* files are symlinks to the latest run.

Documentation

Full documentation: rtl-buddy.github.io/rtl_buddy. Each version also publishes <version>/llms.txt and <version>/agent/catalog.json for agents. Offline, use rb docs list and rb docs show.

Known limitations are on the known issues page.

Metadata

Release files for rtl-buddy 6.74.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.74.0
File	Size	Uploaded
rtl_buddy-6.74.0.tar.gz	1.2 MB	Oct 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for rtl-buddy 6.74.0
File	Interpreter	ABI	Platform	Reset
rtl_buddy-6.74.0-py3-none-any.whl 1.4 MB Oct 7, 2026	Python 3	none	any	Details

Total release size: 2.7 MB

Release files / rtl_buddy-6.74.0.tar.gz

Download URL	rtl_buddy-6.74.0.tar.gz
Size	1.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`c482cc6cd7f77762db6150d707a25d6106a0dfac898e79190d3116d5c1a22dbc`
BLAKE2b-256 checksum How to use checksums	`5577295cc75179ea18537c08eb5e77570b6926151ddf2bf4085fd446f255e463`
Upload date	Oct 7, 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/f7de05edcd1ba4f6aed00356458bbcf84b3b7c63

Workflow

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

Artifact

Subject: rtl_buddy-6.74.0.tar.gz
SHA-256 checksum: c482cc6cd7f77762db6150d707a25d6106a0dfac898e79190d3116d5c1a22dbc Verifying attestations

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

Download URL	rtl_buddy-6.74.0-py3-none-any.whl
Size	1.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`6878ae15a4c0b1131096f169bf69965db448c0f1e7fad412b6c2ad25c8223bb6`
BLAKE2b-256 checksum How to use checksums	`9144a0dc804e19f4e854a3943842fdd0dbe345d8d427e011d7693216315fb716`
Upload date	Oct 7, 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/f7de05edcd1ba4f6aed00356458bbcf84b3b7c63

Workflow

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

Artifact

Subject: rtl_buddy-6.74.0-py3-none-any.whl
SHA-256 checksum: 6878ae15a4c0b1131096f169bf69965db448c0f1e7fad412b6c2ad25c8223bb6 Verifying attestations