HDL Wave AI

AI-assisted hardware verification for VS Code. Connect your active simulation waveform to an LLM — ask questions about signal behavior, debug logic errors, and cross-reference transitions against your HDL source in natural language.

Built as a companion to the VaporView waveform viewer.

How it works

1. Open a VCD/FST file in VaporView and add signals to the viewer
2. Optionally place VaporView's markers to define a time window of interest
3. Open the HDL Wave AI chat (HDL Wave AI: Open Chat from the Command Palette)
4. Ask questions — the extension automatically injects:
   • Signal transition data for the marked (or full) time range
   • Relevant HDL module source ranked by match to your tracked signals
5. Continue the conversation — subsequent messages use the same context without re-fetching

Requirements

• VaporView — VS Code will prompt you to install it automatically
• An LLM provider: either an Anthropic API key or a locally running Ollama instance

Quick Start

Using Claude (Anthropic)

1. Install the extension
2. Open VS Code Settings (Ctrl+,) and search hdlWaveAi
3. Set Provider to anthropic
4. Paste your Anthropic API key into Anthropic: Api Key
5. Open a VCD in VaporView, add signals, then run HDL Wave AI: Open Chat

Using a local model via Ollama

# Install Ollama and pull a model
ollama pull deepseek-coder-v2:16b

Set in VS Code Settings:

• Provider → openai-compatible
• Openai Compatible: Base Url → http://localhost:11434/v1
• Openai Compatible: Model → deepseek-coder-v2:16b

Or run Ollama via Docker Compose — see the docker-compose example in the repo.

Usage

Workflow

1. Simulate your design and open the resulting VCD/FST file in VaporView
2. Add the signals you care about to the VaporView signal list
3. (Optional) Place VaporView's primary and alt markers to focus on a specific time window
4. Run HDL Wave AI: Open Chat from the Command Palette (Ctrl+Shift+P)
5. Ask questions — the first message automatically collects and injects waveform + HDL context

Tips

• Markers: If no markers are set the extension samples the entire simulation. Setting both VaporView markers to bracket the region of interest gives the LLM a tighter, more relevant window.
• HDL source: Open your RTL directory as the VS Code workspace, or configure hdlWaveAi.hdl.searchPaths to point at it. The extension finds modules whose signal names match what's in the viewer.
• Stop: A Stop button appears during streaming — click it to cancel a response mid-generation without losing conversation history.

Generating a VCD for testing

If you don't have a VCD handy, Icarus Verilog can generate one from any Verilog testbench:

sudo apt install iverilog
iverilog -o sim testbench.v design.v && ./sim
# produces output.vcd

Add $dumpfile("output.vcd"); $dumpvars(0, tb); to your testbench's initial block.

Tool-Use (RAG) Mode

For large designs with millions of signal transitions, the extension uses a tool-calling approach instead of dumping all transitions into the LLM context. The LLM receives a compact waveform summary and queries signal data on-demand through tools.

This is enabled by default (hdlWaveAi.waveform.useToolMode: true) and works with both Anthropic and OpenAI-compatible providers. If the provider doesn't support tool calling, it falls back to legacy mode automatically.

MCP Server

The extension includes a standalone MCP (Model Context Protocol) server that exposes waveform query tools to any MCP-compatible client — Claude Code, Claude Desktop, Cursor, and others. This runs independently of VS Code.

Setup

Build the server (if not already built):

cd hdl-wave-ai
npm install
npm run compile

This produces dist/mcp-server.js.

Claude Code

claude mcp add hdl-wave-ai node /path/to/hdl-wave-ai/dist/mcp-server.js

Or to pre-load a waveform on startup:

claude mcp add hdl-wave-ai node -- /path/to/hdl-wave-ai/dist/mcp-server.js /path/to/waveform.vcd

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "hdl-wave-ai": {
      "command": "node",
      "args": ["/path/to/hdl-wave-ai/dist/mcp-server.js"]
    }
  }
}

Project-level config (.mcp.json)

{
  "mcpServers": {
    "hdl-wave-ai": {
      "command": "node",
      "args": ["/path/to/hdl-wave-ai/dist/mcp-server.js", "/path/to/waveform.vcd"]
    }
  }
}

Available Tools

Example Prompt

After loading a waveform, try:

Load the waveform at /path/to/design.vcd, then analyze signal activity between t=4200000 and t=4220000. What instructions is the CPU fetching and are there any anomalies?

FST Support

FST files require fst2vcd (part of GTKWave) to be installed and on your PATH.

Extension Settings

Tuning for larger models

Models with bigger context windows (32b+) can handle more data. Increase these settings:

"hdlWaveAi.waveform.maxTransitions": 1000,
"hdlWaveAi.hdl.maxModules": 10,
"hdlWaveAi.hdl.maxCharsPerModule": 8000

Commands

Troubleshooting

No waveform context / "No signals tracked yet" Add signals to VaporView before opening the chat. The extension reads whatever is currently displayed in the signal list.

HDL context not found Either open your RTL directory as the VS Code workspace root, or add the path to hdlWaveAi.hdl.searchPaths in settings.

LLM not responding / very slow For large VCDs with no markers set, the extension may sample many time steps. Set markers in VaporView to limit the time range, or increase sampleStepSize.

Check the Output channel Run HDL Wave AI: Debug VaporView State and open the HDL Wave AI output channel (View → Output) to see what signals, URIs, and state are being read.

License

AGPL-3.0 — see LICENSE.