wavepeek

wavepeek is a deterministic CLI for inspecting RTL waveforms (.vcd/.fst) in scripts, CI, and LLM-driven workflows.

Why

In RTL debugging, waveforms are the primary artifact, but most existing tooling is GUI-first.
LLM agents and CI jobs need short, composable commands instead of interactive navigation.
Raw dumps (especially large VCD/FST files) are too heavy for direct, repeated analysis in context-limited systems.
wavepeek closes this gap with deterministic, bounded, machine-friendly waveform queries.

Quick Start

Install:

cargo install wavepeek
# or from source
cargo install --path .

Run a complete inspection flow:

# 0) Get a dump
# Note: example `.fst` dumps can be downloaded from `rtl-artifacts` releases: https://github.com/kleverhq/rtl-artifacts
WAVES=./dump.fst

# 1) Check dump bounds and time unit
wavepeek info --waves "$WAVES"

# 2) Discover hierarchy
wavepeek scope --waves "$WAVES" --tree

# 3) Find relevant signals in a scope (--filter is a regex)
wavepeek signal --waves "$WAVES" --scope top.cpu --filter '.*(clk|rst|state).*'

# 4) Sample values at one timestamp
wavepeek value --waves "$WAVES" --at 100ns --scope top.cpu --signals reset_n,state

# 5) Inspect transitions over a time window (--on is a SystemVerilog-like clocking event expression)
wavepeek change --waves "$WAVES" --from 0ns --to 500ns --scope top.cpu --signals state --on 'posedge clk'

By default, commands print human-readable output. Add --json for strict machine output:

wavepeek info --waves "$WAVES" --json

Chain commands in scripts with jq:

scope="$(wavepeek scope --waves "$WAVES" --json | jq -r '.data[0].path')"
wavepeek signal --waves "$WAVES" --scope "$scope" --json | jq '.data[:5]'

Agentic Flows

wavepeek ships with a ready-to-install agent skill:

Packaged source (repo): docs/skills/wavepeek.md
CLI export: wavepeek skill

Install via your agent:

Ask your coding agent to install the skill from docs/skills/wavepeek.md or from the output of wavepeek skill.

Manual install examples:

Codex CLI: ~/.codex/skills/wavepeek/SKILL.md
Claude Code: ~/.claude/skills/wavepeek/SKILL.md

Note: an MCP server for tool-native agent integration is not available yet, but is planned.

Commands

Command	Status	Purpose
`info`	available	Print dump metadata (`time_unit`, `time_start`, `time_end`)
`scope`	available	List hierarchy scopes (deterministic DFS, optional `--tree`)
`signal`	available	List signals in a scope with metadata
`value`	available	Signal values at a specific time
`change`	available	Delta snapshots over a time range with `--on` event triggers
`property`	available	Property checks over event triggers with capture modes
`schema`	available	Print canonical JSON schema used by `--json` output
`docs`	available	Browse embedded narrative docs, search topics, and export Markdown
`skill`	available	Print packaged agent skill Markdown
`help`	available	Print detailed long help for top-level or nested command paths

Use progressive disclosure via built-in help and docs:

wavepeek -h for compact lookup help
wavepeek --help for detailed top-level reference help
wavepeek help <command-path...> for nested long-help aliases
wavepeek docs for embedded command guidance, workflows, troubleshooting, reference topics, and export
wavepeek skill for packaged agent skill Markdown

Development

Preferred workflow uses Makefile targets aligned with CI.
In devcontainer/CI image, run:

make bootstrap
make check
make test

License

Apache-2.0