wavecli-waveform

name	wavecli-waveform
description	Use this skill when the user asks to read, inspect, understand, explain, search, summarize, or query VCD/FST waveform files, signal hierarchies, time ranges, value changes, or IEEE 754 float encodings with the local wavecli tool. Trigger on requests about waveform understanding, signal lookup, timing/value inspection, VCD/FST analysis, or converting float32/float16/bfloat16 values.

wavecli waveform skill

Use this skill when the task is about reading or understanding waveforms. Typical triggers:

• "看一下这个 vcd/fst 波形"
• "帮我理解这个信号怎么变化"
• "列出模块里的 signals"
• "查询某个时间范围内的值"
• "解释这个波形文件里发生了什么"
• "把 hex/bin 转成 float32/float16/bfloat16"
• "用 wavecli 分析 waveform"

This skill is designed to work for both Codex and Claude style agents. The core assumption is simple: if you have shell access, run wavecli commands and inspect the returned JSON or text.

What wavecli does

wavecli is a local CLI for:

• inspecting VCD and FST waveform files
• listing hierarchical signals
• getting waveform time ranges
• querying signal value changes in a time window
• converting IEEE 754 values between float / hex / binary

Default output is JSON. Use --format text when a human-readable terminal view is better.

Installation

You should be able to install and use the CLI from this file alone.

Prerequisites

• Rust toolchain with Cargo installed
• a local checkout of the wavecli repository

Install to local PATH

From the repository root:

cargo install --path .

This installs the binary to Cargo's bin directory, usually:

$HOME/.cargo/bin/wavecli

If wavecli is not found

Temporarily add Cargo bin to PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Persist it in Bash:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Development use without installing

From the repository root:

cargo run -- --help
cargo run -- info tests/fixtures/test.vcd

Basic command map

1. File metadata

wavecli info <file>

Example:

wavecli info ./trace.vcd

Returns JSON like:

{
  "file": "./trace.vcd",
  "format": "vcd",
  "signal_count": 28,
  "file_size_bytes": 3018,
  "time_range": {
    "start": 0,
    "end": 196,
    "total": 196
  }
}

2. List signals

wavecli signals <file> [--module <path>] [--depth <n>] [--limit <n>] [--pattern <expr>] [--regex]

Examples:

wavecli signals ./trace.vcd --pattern Dout
wavecli signals ./trace.vcd --module test.dut --depth 1 --format text
wavecli signals ./trace.vcd --pattern '^test\.dut\.' --regex

3. Get time range

wavecli range <file>

Example:

wavecli range ./trace.fst --format text

4. Query signal values

wavecli values <file> <signal>... --start <n> --end <n> [--radix bin|hex|dec] [--limit <n>]

Examples:

wavecli values ./trace.vcd Dout --start 0 --end 30
wavecli values ./trace.vcd Dout Din --start 0 --end 100 --radix hex
wavecli values ./trace.fst clk --start 0 --end 1000 --limit 20 --format text

Typical JSON result:

{
  "file": "./trace.vcd",
  "format": "vcd",
  "query": {
    "signal_names": ["Dout"],
    "start_time": 0,
    "end_time": 30,
    "format": "bin",
    "limit": 2
  },
  "warnings": [],
  "signals": [
    {
      "path": "test.dut.Dout",
      "count": {
        "shown": 2,
        "total": 8
      }
       
             
             
      
    
  

5. Float conversions

wavecli float hex-to-float <hex> [--type float32|float16|bfloat16]
wavecli float float-to-hex <value> [--type float32|float16|bfloat16]
wavecli float bin-to-float <bin> [--type float32|float16|bfloat16]
wavecli float float-to-bin <value> [--type float32|float16|bfloat16]

Examples:

wavecli float hex-to-float 0x40490FDB --type float32
wavecli float float-to-hex 3.14 --type float16 --format text
wavecli float bin-to-float 0100000001001001 --type bfloat16
wavecli float float-to-bin 3.14159 --type float32

Recommended workflow for agents

When the user asks to understand a waveform, prefer this order:

1. Run wavecli info <file> to confirm format, signal count, and time range.
2. Run wavecli signals <file> with a narrow --pattern or --module.
3. Run wavecli values <file> ... --start ... --end ... on the specific signals.
4. Summarize the behavior in plain language.

Do not dump huge waveforms at once if a narrower query will answer the question.

Output strategy

• Use default JSON when you want structured downstream reasoning.
• Use --format text when you want to show a concise terminal view to the user.
• Errors are printed to stderr and return a non-zero exit code.

Claude / Codex compatibility

This skill is intentionally tool-agnostic.

In Codex

Use shell commands directly, for example:

wavecli info /path/to/file.vcd
wavecli signals /path/to/file.vcd --pattern clk
wavecli values /path/to/file.vcd clk --start 0 --end 100

In Claude

If terminal or local command execution is available, run the same wavecli commands. If a terminal tool is not available, ask the user to run the command and paste the JSON/text output.

Suggested fallback wording:

• "Please run wavecli info <file> and paste the JSON output."
• "Please run wavecli signals <file> --pattern <name> and share the result."
• "Please run wavecli values <file> <signal> --start <n> --end <n> and paste the output."

Good defaults

• start with info
• prefer JSON unless a text table is easier to read
• use --pattern before broad signal listing
• limit value queries to a bounded time window
• use --limit to avoid oversized outputs

Troubleshooting

command not found: wavecli

Install it:

cargo install --path .

Or call it from Cargo directly:

cargo run -- info <file>

Unsupported file format

Current intended public scope is VCD and FST. If the file is another format, convert it first or confirm it is really a VCD/FST file.

No signals found

Try one of these:

wavecli signals <file> --limit 0
wavecli signals <file> --pattern <partial-name>
wavecli signals <file> --module <scope>

Too much output

Narrow the query:

wavecli signals <file> --pattern <name> --limit 20
wavecli values <file> <signal> --start 100 --end 200 --limit 20

Minimal examples to remember

wavecli info file.vcd
wavecli signals file.vcd --pattern clk
wavecli range file.fst
wavecli values file.vcd clk --start 0 --end 100
wavecli float float-to-hex 3.14 --type float16