For AI Agents

Pi Agent integration — visual waveform results

Pi Agent integration gives the model a compact summary while keeping the full-color waveform visible for you.

What the model sees vs. what you see

The integration returns a concise completion summary to the model while keeping the complete colored TUI view available for you to review.

• The canvas contains only a read-only hierarchical-name column, the time ruler and waveform traces — no interactive toolbar, value panel, borders, overview, command hints or status line.
• Every single multi-bit transition marks the top and bottom rails with aligned │ separators without crossing the value row; multiple changes collapsed into one cell use ▓ rail activity markers.
• X, Z and mixed-unknown bus ranges use red, orange and gray patterned rectangles, including their background tint.
• The full view remains available even when the model receives only a shortened text summary.
• The ruler and grid remain; the non-interactive current-time cursor column is suppressed.
• The view remains complete vertically and clips rather than wraps when space is narrow, preserving waveform geometry.

Install the extension

Install svw first from the home page, then add the Pi Agent extension with one command:

Keep the svw-waveform agent skill installed alongside. The skill helps Pi Agent inspect the right signals, retain useful evidence and request clear waveform views consistently.

Headless mode — svw --headless

Headless mode runs svw without a terminal UI: it reads : command lines from stdin, executes them exactly as the interactive TUI would, and writes result messages to stdout. Every command in the command tutorial works here unchanged — same parser, same semantics.

# pipe commands in — one per line, leading ':' optional
printf 'mark 30\nmarks\npattern top.clk=1\nq\n' | svw --headless wave.vcd

# replay a saved session, then run a check script
svw --headless -s debug.svw < checks.svwcmd

• Never enters terminal raw mode — safe for CI jobs, cron and agent shell harnesses.
• Failures are reported as error:-prefixed lines carrying the script line number; lines may be indented, and # starts a comment.
• Arguments support single/double quotes and backslash escaping, so paths with spaces are safe.
• The script keeps collecting errors after a failure; if any command failed, the process exits non-zero.

Use headless mode when you want the full interactive command surface — sessions, markers, reports, coverage — from a script or regression suite.

One-shot typed queries — svw agent

svw agent <waveform|-> <query> answers a single question and exits. Data queries write exactly one JSON object; renders write a static UTF-8 svw TUI frame with no terminal control sequences — safe to embed in tool output.

svw agent wave.fst info                          # timescale, ranges, counts
svw agent wave.fst signals clk 10                # search: name + stable ID
svw agent wave.fst value 42 125000               # value of signal 42 at a tick
svw agent wave.fst changes 42 0 200 100          # change evidence, paginated
svw agent wave.fst render 0 200 top.clk top.state \
    --width 120 --color ansi --view wave         # static waveform frame
svw agent - compare golden.vcd dut.vcd \
    --signals top.a top.b --range-fs 0 1000000   # typed compare evidence

Query families

• Waveform — info, signals, value, changes, render.
• Design (semantic bundle) — design-info, design-objects, design-source, xprobe-object, xprobe-signal, drivers, loads, active-drivers, trace-x.
• Verification — records, assertion-stats, uvm-* history queries.
• Coverage (UCIS) — coverage-info, coverage-runs, coverage-points.
• Compare — compare with signal, range and X/Z/tolerance policies.

Conventions an agent can rely on

• signals returns both the full hierarchical name and a snapshot-scoped stable ID: copy names into render, keep IDs for value/change/xprobe evidence. Object IDs come from design-objects.
• Long results page through an opaque next_cursor bound to the waveform revision and the query.
• Wave query times are native ticks; every success carries a time_context with the exact femtoseconds-per-tick, and compare --range-fs takes decimal femtoseconds directly.
• Failures are one structured svw.tool-error.v1 JSON object on stderr: category, retryable flag, the failed field with its valid range, and a suggested next call — enough to self-repair without reparsing prose.
• Use - as the waveform when a query needs no open file (design and coverage queries).

Choosing an interface