The wtf MCP server lets an agent open and analyze VCD/FST/GHW waveforms, decode protocols into records, query signals/search expressions, and prepare views for the user.
Open or reload traces in isolated workspaces; list and switch sessions/workspaces.
Inspect trace metadata, signal lists, values at a time or over ranges, and text-rendered signal views.
Decode built-in or custom protocols; list protocol roles/params/fields and query decoded records with filters, grouping, counts, time ranges, and radix options.
Run wtf : commands, search waveform expressions (including clock-cycle matches), and read built-in help topics.
Configure workspace rows, cursors/marks, visible range, decodes, computed signals, and custom protocols in one call.
Inspect the user's current view, optionally adopt it, and present the agent's workspace in the user's wtf window or as a session file.
Waveform Terminal Frontend: a Vim-like terminal viewer for VCD, FST and GHW waveforms that
decodes AXI, SPI and UART into transactions you can filter, count and measure. It runs where your
simulations run, over ssh and in tmux, and opens no network connections. Also what you say when
the bus goes X.
The site has a quick start, recipes and every key.
Signals added from the tree, an AXI4-Lite bus decoded into its writes and reads with their
latency, a search for the cycles where the address waits for ready (mark 2), and a jump from the
list of reads to the one answered with SLVERR, unfolded into its fields. To try it, clone this
repository and run cp docs/demo.vcd tour.vcd and wtf tour.vcd.
Decoding. AXI-Stream, AXI4-Lite, AXI4, SPI and UART into records (transfers, frames,
transactions with their latency, protocol errors), and your own protocols defined in a few
lines. The records browser filters, sorts and counts them, and Enter jumps to one.
Search. /0x40 finds a value; /valid && ready && data == 0x40 an expression;
/@clk fell(valid) && !past(ready) a protocol violation, cycle by cycle.
Vim-like. Time is the line axis: h / l move the cursor, w / b jump between
transitions, gg / G go to the start / end, :2000ns goes to a time, z / x zoom.
dd, J / K, r change the rows, and u takes any change back. Space opens a menu of
the rest, every entry with its key. The mouse works too: click to place the cursor,
Ctrl+wheel to zoom.
Signals. A finder with a preview, a signal tree, groups, buses expanded into bits, structs,
records and arrays as one row, radixes (hex, binary, decimal, signed, octal, ASCII, float,
fixed point, and enum names from FST files), computed signals (data[7:4], {a, b}).
Cursors. The cursor and up to eight marks, with the time between them on a ruler.
Sessions. What you look at is saved in a TOML file next to the trace and comes back the next time. After you rerun the simulation, the window reloads it by itself, decodes included.
Display. Dark and light themes or your own colours, X and Z told apart by shape as
well as colour, NO_COLOR, and plain box drawing or ASCII for fonts and terminals that need
it (--glyphs). --snapshot prints a screen as text, for CI logs and bug reports.
Related MCP server: waveform-MCP
On Linux or macOS (x86_64 or arm64):
curl -fsSL https://raw.githubusercontent.com/xtrollyj00/wtf/main/install.sh | shThis puts the wtf command in ~/.local/bin, checked against the release's checksum. The
archives are on the releases page too. Or build it
from crates.io:
cargo install --locked wtf-waveWindows is not supported.
wtf trace.fst # or .vcd or .ghw; the format is read from the content
wtf # the start screen: recent traces
wtf -S my.session.toml trace.fst
wtf --snapshot 120 trace.fst # one screen as text, for CI logs and bug reports
wtf --snapshot 120x30 --ansi --keys '?' trace.fst # in colour, after pressing keyswtf shows what the file holds. A VCD keeps less than an FST: no enum names and no scope types, so a struct or union is a plain scope.
The first start asks which glyphs your terminal draws well and whether you want dark or light
(wtf --setup asks again). Then wtf shows what to do first: Space f finds a signal by name,
a browses the signal tree, and Space d d decodes an interface wtf found in the trace. ?
shows the keys, : takes commands, :w saves the session, q quits. The
quick start walks through it on docs/demo.vcd (in a clone of this repository).
If you use an AI coding agent, wtf can give it your traces: the same decoders and records, and it shows you what it found. The agents page has the full story.
Register the MCP server once, for example with Claude Code:
claude mcp add wtf -- wtf --mcpA VCD is text, and an agent left to itself reads it with cat and grep. Claude Code defers an
MCP server's tools until the agent searches for them, which makes that likelier: on NVIDIA's CVDP
debug problems, agents given the failing run's VCD with wtf's tools deferred called wtf in none
of 10 runs. Keep wtf's tools loaded (ENABLE_TOOL_SEARCH=false in the environment), and tell the
agent in your project's CLAUDE.md or AGENTS.md: "Read waveforms (VCD, FST, GHW) with the wtf
MCP server's tools."
Then ask the agent about a trace. It opens it in a workspace of its own and answers
from the decoded values. Asked for failed reads in docs/demo.vcd, an agent calls the command
tool with decode bus axilite clock=aclk prefix=s_axi_, then records on bus.rd with
where: "resp != 0", and gets:
1 of 1 matching, of 2
start end delay addr data resp
175ns 205ns 20ns 0x40 0x0 0x2When it has found something, it prepares the rows and puts marks on the events, then presents
them in your open wtf window (:undo gives you your own view back). With no window open, it writes
a session file for you to open. While it works, your window on the trace shows each step it takes,
and :follow shows its workspace as it builds it.
https://github.com/user-attachments/assets/19ea36cd-b8ff-4986-a786-f335e6e31a12
wtf-bench agent measures how much it helps: it gives an agent failing RTL testbenches to debug
and fix, with wtf and without it. Every run fixed its bug either way; 17 of 20 runs with wtf also
had every answer right (when and where it went wrong), against 11 of 20 without. The numbers and
how they were taken are in bench/RESULTS.md.
wtf is young and changes fast. Until 1.0.0 nothing is kept backward compatible: session files,
the MCP tools' arguments, keys and commands change whenever a better design turns up, and the
old form stops working. A commit that breaks something says so (feat(core)!: ..., with a
BREAKING CHANGE: note on what to do instead).
The site has a quick start on docs/demo.vcd, how wtf works,
recipes, every key and command, configuration, the agent setup and its reference, and
troubleshooting.
The design is in spec/, one file per topic: the keys, commands, search,
sessions, the MCP server and the decoders. ROADMAP.md says what comes next;
the shortcuts taken so far are the known-limit issues.
Bug reports, ideas for the screen, agent benchmark tasks and speedups are all welcome:
CONTRIBUTING.md says how.
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in wtf by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Run one of wtf's : commands on the workspace: decode, protocol, rows, cursors (help commands). Answers with the rows it added or removed; undo takes a step back.
Inputs: line (required).
When a search expression holds, as a table of times; show adds values, count_only counts. With @<clock> first, a match is a cycle whose ending edge samples it true (@clk x: the cycles x is high), reported at the cycle's start; without, where it becomes true (rose(x): x's edges). A bus: decode it (help decode).
Inputs: expr (required), to, from, show, +4 more.
The reference for one concept: its form, recipes and details. Topics: names, patterns, times, radix, expressions, decode, records, workspace, commands; without a topic, lists them. Call it when an argument's doc or an error isn't enough.
Inputs: topic.
The open waveform: file, time range, signals, and the interfaces a built-in protocol decodes, each with its decode line.
Inputs: no named parameters.
Choose the trace the other tools work on: trace opens a waveform (VCD, FST or GHW file) in a new workspace; session goes back to one of your workspaces (sessions); neither re-reads the current one's file, after the simulation ran again, keeping its rows. Answers with info, which lists the interfaces to decode.
Inputs: trace, session.
Show your workspace to the user as evidence: it replaces the view of every wtf window on this trace (theirs is one u away), or with none open writes <trace>.agent.session.toml for them to open.
Inputs: no named parameters.
What can be decoded; with a name, its roles, params, streams and fields (help decode).
Inputs: name.
Records of a decoded stream, or of several in start order (a decode's name: its results), as a table: n, start (the rising edge that starts the record's first clock cycle), end (the edge that samples its last) and the fields; where, group_by, count_only (help records).
Inputs: stream (required), to, from, unit, +5 more.
Draw signals over a time range as text, as wtf's screen does; without signals, the workspace.
Inputs: to, from, unit, width, +1 more.
The open sessions: the user's wtf windows and agents' workspaces, with ids and traces, yours marked. open starts one or switches between yours.
Inputs: no named parameters.
Search the waveform's design, scopes (instances) and signals, by a regex in slashes found anywhere in the path, as grep does (/uart/, /_valid$/); none lists it all, folded to fit.
Inputs: pattern.
What the user is looking at in their wtf window on this trace, worded as view words the workspace, to start from what they see. Changes nothing unless adopt: that replaces the workspace's rows, cursors and range with the user's, dropping yours; command undo brings them back.
Inputs: adopt.
Values of signals from from to to: the value at from, then each change, as time value lines; omit to for one time. A struct or array also lists its fields. For when something happens, find.
Inputs: from (required), signals (required), to, unit, +1 more.
Describe the workspace in words: rows, cursors with the time between them, visible range. Drawn: render; the user's window: user_view.
Inputs: unit.
Set up the whole workspace in one call: rows, cursors, range, decodes (help workspace). Answers as view does.
Inputs: rows (required), range, scope, decode, +3 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 15 tools
The analysis tools (find, values, records, signals) are clearly separated by query type, and view/render/present/user_view describe distinct outputs. However, workspace, view, present, info, and sessions all cluster around workspace and UI state, so the names alone leave some room for misselection.
Names are all lowercase and mostly single-word CLI-style commands, but they mix nouns and verbs unpredictably and only user_view uses an underscore. There is no consistent verb_noun pattern, so agents must rely on descriptions.
15 tools is reasonable for a rich waveform debugging workflow with trace inspection, values, edge finding, protocol decoding, and workspace management. It is slightly heavy because several tools cover related view/workspace presentation concerns.
The set covers opening traces, inspecting signals, reading values, finding events, decoding protocols, querying records, configuring workspaces, rendering, and presenting to the user. Minor gaps exist around explicit close/delete/export operations and cursor manipulation, though command and workspace partly mitigate them.
Manage SysML2 projects; check, evaluate, verify, query, document and diagram models.
Build, run and analyse block-diagram simulations: PID, Bode, FFT, optimisation and code export.
ASN.1 tools. Validate, compile ASN.1 schema, encode and decode ASN.1 data.
7-chain EVM audits, log simulator, wallet due diligence, calldata decoder, Chainlink & ENS.