🌊 CLI tool for RTL waveform (VCD/FST/FSDB) inspection
Overview
A CLI for querying RTL waveform dumps. Supports hierarchy browsing, signal inspection, Boolean condition checking, and event extraction. Playground · Documentation · Quickstart · Releases wavepeek is a stateless CLI that runs non-interactive queries over waveform files. Its main use cases are LLM-driven debugging and other automated workflows. Each invocation opens one VCD/FST/FSDB file, runs one query, writes text, JSON, or JSONL, and exits. It starts on demand and does not require a background service. For example, this command returns the value of top.data at 10ns: wavepeek is not a GUI or TUI waveform viewer. It does not provide real-time waveform streaming, live simulator connections, or waveform comparison. The protocol extractors do not check protocol compliance or reconstruct high-level transactions. Their output contains observed channel transfers or protocol phase events with sampled payload and context. Open the Playground to run wavepeek in a browser.
README
A CLI for querying RTL waveform dumps. Supports hierarchy browsing, signal inspection, Boolean condition checking, and event extraction.
Playground · Documentation · Quickstart · Releases
wavepeek is a stateless CLI that runs non-interactive queries over waveform files. Its main use cases are LLM-driven debugging and other automated workflows.
Each invocation opens one VCD/FST/FSDB file, runs one query, writes text, JSON, or JSONL, and exits. It starts on demand and does not require a background service. For example, this command returns the value of top.data at 10ns:
$ wavepeek value --waves dump.vcd --at 10ns --signals top.data
@10ns top.data=8'h0f
wavepeek is not a GUI or TUI waveform viewer. It does not provide real-time waveform streaming, live simulator connections, or waveform comparison.
Commands
| Task | Commands |
|---|---|
| Read dump metadata and browse the recorded hierarchy | info, scope, signal |
| Read values at a time or on selected events | value, change |
| Find when a Boolean condition matches, asserts, or deasserts | property |
| Extract custom handshakes or synchronous events | extract generic |
| Extract AMBA transfers or phase events | extract axi, extract axistream, extract ahb, extract apb, extract atb |
The protocol extractors do not check protocol compliance or reconstruct high-level transactions. Their output contains observed channel transfers or protocol phase events with sampled payload and context.
Getting started
Open the Playground to run wavepeek in a browser.
To install wavepeek on macOS or Linux, run:
curl --proto '=https' --tlsv1.2 -LsSf https://kleverhq.github.io/wavepeek/install.sh | sh
The prebuilt binary supports VCD and FST. FSDB support requires a source build on Linux x86_64 and the Synopsys Verdi FSDB Reader SDK.
Alternatively, ask your agent to do the setup:
Install the latest release from https://github.com/kleverhq/wavepeek/releases. Run 'wavepeek skill' to get the skill.
Check the version after installation:
wavepeek --version
See the Quickstart for Windows, Cargo, source installation, FSDB setup, and further examples.
Agent skill
Extract the skill package included in the binary:
wavepeek skill ./wavepeek-skill
The package matches the installed wavepeek version. Its directory contains SKILL.md, offline references, examples, helper scripts, and provenance. Follow your agent harness’s instructions to install the directory.
Documentation
| Topic | Link |
|---|---|
| Installation and first query | Quickstart |
| Command groups | Commands |
| Hierarchy and signal values | Explore dump · Inspect values |
| Boolean conditions | Evaluate properties |
| Generic and AMBA extraction | Extract transfers |
| JSON and JSONL output | Machine output |
| Syntax and flags | CLI reference |
Development
See CONTRIBUTING.md.
License
Apache-2.0
Recommended Tools
Try a different keyword or remove a filter.
Install
npx skillfish add kleverhq/wavepeek