WaveQ

WaveQ

Your AI assistant can read code — WaveQ lets it read waveforms too.

WaveQ is a local MCP server and CLI that indexes .vcd / .vcd.gz files into SQLite, then answers precise questions about signal values, transitions, edges, and clock cycles. Instead of dumping megabytes of raw VCD text into context, your agent gets compact, structured answers — and honest failures when data is missing or ambiguous.

Zero runtime dependencies. Pure Python. Runs entirely on your machine.

Quick start

Requirements: Python 3.10+

git clone https://github.com/IshaanDugar/waveq.git
cd waveq
python -m venv .venv

# Linux / macOS
source .venv/bin/activate
pip install -e .

# Windows
.\.venv\Scripts\activate
pip install -e .

Try the included fixture:

waveq info examples/sample.vcd
waveq value examples/sample.vcd tb.valid 16ns
waveq digest examples/sample.vcd 30ns 10ns --scope u_apb

Start the MCP server (stdio JSON-RPC):

waveq-mcp
# or: python -m waveq.mcp_server

Connect to your AI tool

WaveQ speaks MCP over stdio. Point any MCP-capable client at python -m waveq.mcp_server (or the waveq-mcp script after install).

Example agent prompt once connected:

Use WaveQ on examples/sample.vcd. Check index_status; if query_ready is false,
build_index(level="full"). Resolve clk and reset, define clk as rising-edge clock,
and summarize activity around 10ns.

See AGENTS.md for the recommended tool workflow.

What it does

• Parse VCD/VCD.GZ into a reusable local SQLite cache
• Resolve fuzzy signal names to exact hierarchical paths
• Query values at a time, changes in a window, edges, and stability
• Summarize a debug window with window_digest instead of raw dumps
• Build a clock cycle index and query by cycle
• Return ok: false on missing signals, bad times, or partial batch failures — no silent success

What it does not do

WaveQ is not a simulator, waveform viewer, assertion engine, or protocol checker. It reports observed VCD facts. Do not use it alone to prove APB/AHB/AXI correctness, CDC safety, or formal properties. It does not read FSDB, VPD, or FST.

How it works

WaveQ is size-aware. Small VCDs may auto-index on configure; larger files stay metadata-only until you explicitly call build_index.

Recommended agent workflow:

1. configure_waveform → 2. index_status → 3. build_index if needed → 4. resolve_signals → 5. define_clock (for cycles) → 6. window_digest near the failure → 7. follow up with values_at, changes_many, edges

MCP tools (18)

Result shape

Success:

{"ok": true, "status": "ok", "summary": "tb.valid=1 at 16ns", "data": {}, "confidence": 1.0}

Failure (batch tools do not hide partial errors):

{"ok": false, "status": "partial_failure", "summary": "One or more signal lookups failed", "confidence": 0.0}

Time syntax

Raw ticks (42) or unit times (42ns, 1.5us). Unit times convert exactly via rational arithmetic — non-integral ticks fail instead of rounding silently.

Performance

Synthetic benchmarks on a typical dev laptop (Windows, Python 3.x). Regenerate anytime:

python benchmarks/benchmark_waveq.py --output reports

Query speed (median, after full index)

Index build cost (one-time per VCD)

Large files stay metadata-only at configure time — you pay for indexing only when you need it.

Why this matters for AI-assisted debug

Rule of thumb: after the one-time index build, point queries are sub-millisecond and debug-window summaries land in single-digit milliseconds — even on 50+ MB files. The real win is not raw speed alone; it is making waveform evidence queryable and context-sized for an AI agent instead of dumping unusable VCD text.

CLI reference

waveq info <vcd>
waveq configure <vcd>
waveq index-status <vcd>
waveq build-index <vcd> --level full
waveq resolve <vcd> <query>
waveq value <vcd> <signal> <time>
waveq values <vcd> <time> <signal> [...]
waveq changes <vcd> <signal> <start> <end>
waveq edges <vcd> <signal> --kind rise --start 0ns --end 50ns
waveq digest <vcd> <center> <radius> [--scope <hier>]

Development

python -m py_compile waveq/*.py          # PowerShell: py_compile (Get-ChildItem waveq\*.py)
python -m unittest discover -s tests -v
python benchmarks/benchmark_waveq.py --output reports   # optional; writes to reports/

See CONTRIBUTING.md for details.

Repository layout

waveq/           VCD parser, SQLite indexer, query engine, MCP server, CLI
tests/           Unit and MCP behavior tests
benchmarks/      Synthetic VCD performance + correctness checks
examples/        Sample VCD and smoke commands
docs/install/    MCP client setup guides

License

MIT — see LICENSE.

Originally developed by Ishaan Dugar during an internship at Ambiq Micro. Ambiq Micro is not the author or maintainer of this project.

Contributing

Issues and pull requests welcome. See CONTRIBUTING.md and SECURITY.md.