◆ Alwavelets — The Complete Field Guide

Quick start & CLI

Zero dependencies — the launcher is alwavelets.py next to the alwavelets/ package. It parses VCD (streaming, background-loaded, or lazy for huge files) and FST (native pure-Python reader).

Reading the screen

Top to bottom: title bar (file, timescale, signal/change counts) · menu bar with paged key hints (0/9 flip pages, F2 hides it) · time ruler · signal rows · status bar.

The status bar shows the active cursor and its time, ΔAB with its equivalent frequency and the focused signal's transition count between the cursors — e.g. ΔAB=20ns (50MHz · 40t) — the visible window, the signal range, panel focus, and the focused signal's value.

Glyph language: ▔ high · ▁ low · │ edge · ▓ "busy" (transitions denser than columns) · ▚ unknown x · ┄ high-impedance z · ╳══╳ bus segments with value labels · block or braille curves for analog. Press C for the in-app color legend, ? for quick help, F1 for the full 12-page manual.

By default the split panel (scope tree, width 30) is open on the left and Tab switches focus between panel and waves; press s to close it and give the full width to names + waves.

Navigation & zoom

Cursors, markers & measurement

In the marker list, ↑/↓, PgUp/PgDn, and Home/End select a marker; Enter jumps to it, shows the active cursor, and closes the list. Press F12 again to select another marker in the list. Use r to rename, Delete or d to delete one, m to add at the cursor, and M to clear all. u/Ctrl-R undo/redo edits using the shared editing history. Esc or F12 closes the list. Click a row to select, double-click to jump, or click a control. Renaming to an empty label clears it; Esc cancels. Save edited markers with ;session.

To search markers, press / inside the list, enter a label or time, and press Enter to apply. Esc cancels the filter prompt. Matching ignores case; every space-separated term must appear in the label, displayed time, or raw tick count. The title shows matching/total counts. Ctrl-U in the list resets the filter; an empty query also shows all markers. Filtering preserves the markers themselves: Delete removes the selected match, while M still clears all markers, including those hidden by the filter.

Search: the fuzzy finder & friends

/ opens an fzf-style overlay that filters every signal in the file live — not just the displayed ones. It is also "go to signal": an already-displayed match is jumped to instead of re-added.

Finder performance: re-ranking 50 000 names takes ~15 ms, and extending a query only re-ranks the previous matches — filtering is effectively instant per keystroke.

Managing the signal list

Groups — collapsible, nestable

Bundle related signals under a named header row that folds with Tab. Groups are an overlay: the canonical signal order is untouched.

# 1. select members
V            # visual mode on the first signal, ↑↓ to extend
# 2. create
;group Handshake             # top-level group
;group Interface/Handshake   # same, nested under "Interface" (auto-created)
# 3. operate
Tab          # on the ▼/▶ header: fold / unfold
;ungroup     # dissolve (focused header, or ;ungroup NAME) — children re-attach to its parent
u            # undo any group edit

• Headers render as ▼ name (n); nested headers indent by depth and show child counts (2▸).
• Collapsing a parent hides child headers and their members; collapsing a child leaves the parent open.
• Nesting cycles are rejected; empty leafless parent nodes are pruned automatically.
• Groups persist through ;session, saved arrangements, and undo snapshots.

Display & styling

Separating adjacent signals

If the low level of one signal appears to touch the high level of the next, press | once from the default Compact mode to select Blank gap. It leaves one empty terminal row between signals. Press again for Divider, which draws a faint dotted line in that gap; another press returns to Compact.

;spacing blank
;spacing divider
;spacing compact

Blank gap and Divider show fewer signals at once. Their gaps sit below the complete waveform, including tall analog plots and comparison lanes. Q's horizontal-grid option can also draw dotted guides in gaps. Save your choice with ;session; changing workmode resets spacing to Compact.

Older sessions keep their row spacing: the former 0.25/0.5 choices become a full-row dotted divider instead of block characters, while saved two/three-row gaps retain their height.

Custom number formats

Define how a bus encodes a number using two reusable radix slots: fixed for fixed-point values and float for a custom floating-point layout.

The built-in floating-point choices remain available: f16, bf16 (bfloat16), f32, and f64. Choose BF16 in the signal menu or enter ;radix bf16; F honors BF16 when it is selected on a 16-bit bus.

Configure, then apply

1. Focus a waveform, or select several with Space / V.
2. Open F10 → Number format → Configure custom fixed… or Configure custom float…. Edit the prefilled settings; Ctrl-U clears the input, Enter accepts, and Esc cancels.
3. Back in the number-format menu, choose Custom fixed or Custom float to apply that slot to the selected/focused signals. Its label shows the current layout and total width.

;fixed and ;float also open the configuration prompts. With arguments they configure directly, using the syntax below. Configuration alone does not assign the radix: use the menu for selected signals, or ;radix fixed / ;radix float for the global default. Signals with explicit overrides keep them until you choose Default (global).

Custom fixed-point

;fixed <integer bits> <fraction bits> [signed|unsigned]

Integer bits exclude the sign bit. Signed values use two's complement with a total width of 1 + I + F; unsigned values use I + F. The displayed value is the decoded integer divided by 2^F, with exact decimal output.

Example: interpret an 8-bit bus as signed fixed-point with 3 integer and 4 fraction bits:

;fixed 3 4 signed
;radix fixed

The raw word 11101000 represents -24 / 16 = -1.5. With ;fixed 4 4 unsigned, the same 8-bit word represents 232 / 16 = 14.5. Changing the definition refreshes signals already using fixed.

Custom floating-point

;float <exponent bits> <mantissa bits> [bias|auto] [ieee|finite|nan]

Words contain one sign bit, then E exponent bits and M stored mantissa bits: 1 + E + M bits in total. Normal numbers have an implicit leading 1; exponent zero represents signed zero or subnormal values.

The final argument controls how the maximum exponent is interpreted. Supply a bias or auto before choosing a policy:

Example: an 8-bit float with 4 exponent bits, 3 mantissa bits, and automatic bias 7:

;float 4 3 auto ieee
;radix float

00111100 splits into 0 | 0111 | 100 and displays 1.5 [+|E:7|M:4]. ;float 2 1 auto finite instead defines a 4-bit format whose 0111 word represents 6.

Debugging numeric components

Choose a numeric radix, focus the signal, then press F, choose F10 → Expand components, or enter ;expand-fields. The parent stays visible, followed by its component lanes:

Fields with zero bits are omitted. Exponent and integer fields start in unsigned decimal; sign, mantissa, and fraction start in binary. Use the number-format menu to change an individual field's display, or x to expand it into bits. The decoded .value lane uses an analog plot.

Fixed-point fields show the raw stored bits. For signed I=3/F=4, 11101000 splits into 1 | 110 | 1000, while .value reads -1.5. The integer field therefore starts at 6 and the fraction field at 1000; their bits form a two's-complement word, not a sign-and-magnitude encoding. Unknown X/Z bits remain visible in their own fields; known fields stay readable.

Press F on the parent again to collapse its children, including any expanded bits. Lanes share the parent history without copying it and follow newly loaded samples. Collapse and expand again after editing a custom definition to rebuild the layout. Component lanes are temporary: expand them again after restoring a session/arrangement or reloading the trace.

For convenience, F also selects f16/f32/f64 on an ordinary 16/32/64-bit bus. An explicitly selected numeric format always takes precedence and must match the signal width.

Width checks, saving, and exports

A width! (need 8b) label means the signal width does not match the configured word width. Adjust the definition or select a matching bus. Short binary strings in a correctly sized VCD signal are zero-extended; unknown X/Z values remain unknown.

;session saves both definitions and the global/per-signal assignments for the next open. Arrangements saved through E → a also contain them. Set startup defaults through custom_radixes in config.json; interactive edits do not rewrite that file.

Text and SVG snapshots using a saved arrangement honor its custom definitions and per-signal assignments. An explicit snapshot radix overrides the assignments while using the arrangement's definition for that slot. Without an arrangement, custom snapshot formats use the initial definitions above.

These formats decode individual words. External block/tensor scaling is separate, and changing a radix does not change analog plots' existing numeric interpretation.

Mouse

The ; command line

Press ;, type a command. Unrecognized input falls through to the Tcl engine, so ;puts [signals] works too.

View & navigation

Analysis

Layout, persistence & misc

Tcl scripting :

Press : for a small GTKWave-flavoured Tcl engine — enough to script view setup and batch measurements. Commands:

add_signal <glob>      remove_signal <glob>    signals [glob]
zoom <a> <b>           zoom_fit                goto <t>
cursor <t>             marker <t> [label]      radix <r> [signal]
analog <signal>        expand <bus>            translate <file>
measure <signal>       export_csv <file>       screenshot <file>
theme <name>           set / puts / foreach    # variables & loops

Example — arrange a debug view in one line: :foreach s [signals cpu.*] { add_signal $s }

Scripts can also configure the two custom slots with fixed I F [signed|unsigned] and float E M [bias|auto] [ieee|finite|nan], then select one with radix fixed or radix float.

Sessions & sidecar files

Everything persistent lives in small JSON sidecars next to the trace (never inside it), plus one global cache and one global config.

Themes & configuration

{
  "name": "Nord",
  "HIGH":   ["#A3BE8C", -1],
  "BUS":    ["#88C0D0", -1],
  "CURSOR": ["#2E3440", "#88C0D0"],
  "SELECT": ["#2E3440", "#A3BE8C"]
}

{
  "theme": "phosphor",
  "radix": "hex",
  "custom_radixes": {
    "fixed": {
      "integer_bits": 7,
      "fraction_bits": 8,
      "signed": true
    },
    "float": {
      "exponent_bits": 5,
      "mantissa_bits": 10,
      "bias": null,
      "specials": "ieee"
    }
  },
  "wave_style": 2,
  "menu_bar": false,
  "grid": 1,
  "name_width": 28,
  "keys": {
    "quit": "Q",
    "zoom_in": "=",
    "toggle_cursor": " "
  }
}

Export & graphics

MCP server — connect an LLM service

Alwavelets speaks the Model Context Protocol natively (stdio, newline-delimited JSON-RPC 2.0, protocol 2024-11-05) — implemented in the stdlib, no SDK. Any MCP client (Claude Code, Claude Desktop, agent frameworks) can open traces and interrogate them through seven tools. Parsed traces are cached per file+mtime, so repeated queries are instant.

Hook-up

claude mcp add alwavelets -- \
  python3 /path/to/alwavelets.py --mcp

{
  "mcpServers": {
    "alwavelets": {
      "command": "python3",
      "args": ["/path/to/alwavelets.py", "--mcp"]
    }
  }
}

Tool reference

Common conventions: file is a VCD/FST path (required everywhere); signals is a list of names or globs (top.alu.*); start/end accept ticks or unit strings like "500ns", "1.5us" and default to the trace extent; arrangement points at a saved arrangement JSON to supply the signal list + radixes.

Accepted radix names: bin, hex, dec, unsigned (or uns), f16, bf16, f32, f64, fixed, and float. For custom text/SVG labels, provide an arrangement containing your slot definitions.

On the wire

One JSON-RPC message per line on stdin/stdout. A complete exchange:

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
← {"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"alwavelets","version":"0.1.0"}, …}}
→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
      "name":"find_when",
      "arguments":{"file":"bench.vcd","expr":"fifo_full && wr_en","limit":5}}}
← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text",
      "text":"3 time(s) where 'fifo_full && wr_en' becomes true:\n  1.24us\t(t=1240) …"}],
      "isError":false}}

Tool failures come back as isError: true content (not protocol errors), so the model can read the message and self-correct — e.g. a mistyped signal name.

What to ask the model

• "Open bench.vcd, list the FIFO signals, and find when fifo_full && wr_en first happens" — chains list_signals → find_when.
• "Show me 200 ns around the first overflow" — find_when → render_waveform with a computed window.
• "Any glitches or x-propagation in the ALU?" — find_glitches with signals: ["top.alu.*"].
• "Is the core clock really 100 MHz across the whole run?" — measure on clk.

Live-viewer tools drives your screen

The seven tools above are headless — they parse a trace of their own and know nothing about what you have open. These five attach to a running viewer started with --control, so an MCP client can drive the session in front of you with no extra plumbing. They're a thin proxy over the same socket documented in Agent control — one implementation, two transports.

All five take an optional session (a pid or trace filename). With one viewer open it's inferred; with several the tool refuses to guess and lists the choices — silently steering the wrong window would be the worst failure mode here. With none open, the error tells the agent to ask you to start one with --control.

Agent control of a live session service

The direct socket protocol behind the viewer_* MCP tools above — use this when your agent isn't an MCP client, or wants a persistent connection. Start a viewer with --control and an authorized local agent can drive that exact session while you watch — group signals, jump the cursor to where an expression holds, zoom, restyle — and read back both the view state and the waveform on your screen. Built for exactly this: describe what you want to your agent, watch your own viewer do it.

Turning it on

python3 alwavelets.py bench.vcd --control     # your terminal / tmux pane
python3 alwavelets.py --list-sessions         # how an agent finds it

Nothing listens unless you pass --control. The status bar then shows who's driving: ◇ctl armed but idle · ◆agent:1 connected · ◆AGENT acted within the last two seconds.

Protocol

Each session publishes a 0600 descriptor (socket path + per-session token) under $XDG_RUNTIME_DIR/alwavelets/sessions/<pid>.json. The agent connects to the Unix socket and exchanges one JSON object per line.

The first four never modify the view. command takes exactly what you'd type at the ; prompt, so the agent's vocabulary is the same one documented above — nothing is duplicated, nothing can drift. Commands that would open an interactive prompt are no-ops over the channel rather than freezing the viewer for a keyboard nobody is at.

Python client

from alwavelets.control import list_sessions, ControlClient

session = next(s for s in list_sessions() if not s["stale"])
with ControlClient(session) as c:
    c.command("group Interface/Handshake")   # organize the view
    r = c.command("when valid && ready")      # cursor lands on the match
    t = r["state"]["cursor"]["a"]
    c.command(f"zoom {t-200} {t+200}")        # frame it
    print(c.render(width=100)["text"])        # see what the user sees

Python API

The same snapshot machinery the MCP server uses is importable directly — handy in scripts, notebooks and CI checks.

Two lines in a REPL

The quickest way to show what this does — no curses terminal, no file needed. demo() generates the built-in trace (cached after the first call), prints it, and hands back the parsed VCDFile so the session can continue:

>>> import alwavelets
>>> vcd = alwavelets.demo()
waveform  [0ns .. 300ns]
              ┬0ns          ┬60ns          ┬120ns         ┬180ns         ┬240ns
top.clk       ▁││▁││││▁││││▁││││▁│││││▔││││▔││││▔│││││▁││││▁││││▁││││▁│││││▔││
top.valid     ▁▁▁▁▁▁▁▁▁▁│▔│▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁│▔│▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁│▔▔│
top.data_out  XXXXXXXX░░░╳96═════════╳B9══════════╳62═════════╳23═════════╳17═

>>> alwavelets.demo(signals=["top.adc"], end="1us")   # pick signals / window
>>> alwavelets.measure(vcd, ["top.clk"])              # keep going with the trace

Full surface

import alwavelets

vcd = alwavelets.parse_file("trace.vcd")                       # VCD or FST
print(alwavelets.render_text(vcd, ["top.clk", "top.data*"],
                          "0ns", "2us", width=100))          # Unicode snapshot
svg = alwavelets.render_svg(vcd, ["top.*"], None, None)         # vector snapshot
stats = alwavelets.measure(vcd, ["top.clk", "top.valid"])       # period/freq/edges
names = alwavelets.list_signals(vcd, "cpu.*")                   # discovery

sig = vcd.signals[names and vcd.signal_order[0]]             # raw access:
sig.value_at(1500); sig.changes_in_window(0, 2000)           # O(log n) reads

Values are 4-state throughout (0 1 x z); buses return full-width bit strings, reals return numeric strings.

Guided demo tour — five minutes

Register panel demo

python3 alwavelets.py demo_register_panel.vcd --expanded --no-session

The panel docks right by default. While it is open, click a placement command at its top or press 3 Right, 4 Bottom, 5 Top, 6 Left, or 7 Overlay. Narrow panels use arrows for dock directions. Docks reserve waveform space so cursors remain unobstructed; overlay covers the waveform. Moving or closing the panel preserves cursor times and the displayed time range. Sessions remember the chosen position.

Press p, then type ;goto 6500ns and press Enter. This synthetic RV32 trace supplies automatically detected instruction, PC, writeback, clock and hart signals. The panel reconstructs earlier writes and displays hexadecimal values for the hart at the cursor.

New writes are highlighted at retirement. Resize the terminal to try adaptive columns; use PgUp/PgDn when the registers need multiple pages. Close with p or Esc. Regenerate the capture with python3 tools/generate_register_demo.py.