🐙 TraceWeave

TraceWeave turns local VCS/Xcelium simulation artifacts into a guided investigation. It discovers the active compile, simulation, and VCD/FSDB waveform inputs; builds the compiled hierarchy and an independent structural-risk view; normalizes failures; runs a whole-design runtime handshake sweep; and recommends the next evidence-gathering call.

Formal workflows have a separate artifact-only entry point. get_formal_paths performs bounded local discovery through tool-specific providers (currently JasperGold) and returns project directories, role-labeled logs, and exported VCD/FSDB files. It deliberately does not classify traces or interpret property or proof status.

For driver, load, structural-path, and X/Z-source questions, TraceWeave uses a provenance-preserving backend ladder: trusted Verdi NPI when a usable KDB is available, a bounded on-demand Slang Source Graph when NPI is unavailable or inconclusive, and Legacy Static as the final fallback. Results expose backend provenance, coverage, truncation, and fallback status rather than turning partial evidence into certainty.

TraceWeave is a workflow-oriented debug server rather than a loose collection of parsers. It combines:

• A guided MCP workflow from artifact discovery through parallel hierarchy/structural analysis, failure parsing, runtime protocol scanning, and focused verification
• Compile-evidence hierarchy construction, handle-based browsing, and source-aware structural analysis
• VCD/FSDB point, transition, window, cycle, divergence, and period queries
• Whole-design handshake scanning, targeted protocol checks, temporal predicates, and transaction reconstruction
• Driver/load/path/X tracing through trusted NPI -> bounded Source Graph -> Legacy Static
• Structured next actions plus coverage, provenance, truncation, and resource receipts designed for MCP clients

Architecture · Installation · Client Setup · Standard MCP Workflow · Tool Quick Reference · Testing · WeChat

When TraceWeave helps most

TraceWeave adds the most value when debugging requires correlating evidence across artifacts rather than reading one obvious RTL line. It is especially useful for:

• Opaque runtime symptoms such as timeouts, hangs, scoreboard mismatches, X/Z propagation, first divergence, or a broken cadence. Waveform queries and protocol/transaction analysis locate the first bad time, interface, or beat.
• Cross-hierarchy cause-and-effect questions where a suspicious signal must be followed through ports, interfaces, assignments, drivers, and consumers.
• Large or interface-rich designs where whole-design handshake sweeps and bounded hierarchy/Source Graph scopes reduce an otherwise open-ended search.
• Falsifiable hypothesis checks that need a concrete witness or counterexample from verify_window, divergence, period, handshake, or reconstructed-transaction evidence.
• License-constrained environments where Source Graph provides semantic connectivity without NPI, while a usable KDB can still enable deeper local or LSF-hosted Verdi NPI analysis.

For a small readable block with an obvious source-local logic error, direct source and log inspection may be faster. TraceWeave also cannot reveal behavior absent from every available source, log, waveform, and KDB artifact; with protected IP it can follow only the evidence exposed at visible boundaries, in the waveform, or in the elaborated database.

Architecture

• Architecture map: docs/architecture.md
• New-session bootstrap: read AGENTS.md first, then follow its first-read file list
• Fast path for code understanding:
  • server.py
  • config.py
  • src/analyzer.py
  • src/log_parser.py
  • src/fsdb_parser.py

Repository Layout

TraceWeave/
├── config.py                 # Environment-sensitive constants and discovery rules
├── server.py                 # MCP entry point, session state, and workflow gating
├── custom_patterns.yaml      # User-extensible log patterns
├── fsdb_wrapper.cpp          # Native FSDB wrapper source
├── build_wrapper.sh          # Builds libfsdb_wrapper.so
├── scripts/                  # Full installer plus Source Graph / FSDB setup and verification
├── tests/                    # Unit and integration tests
└── src/
    ├── path_discovery.py
    ├── compile_log_parser.py
    ├── tb_hierarchy_builder.py
    ├── vcd_parser.py
    ├── fsdb_parser.py
    ├── fsdb_signal_index.py
    ├── waveform_batch.py         # FSDB+VCD time-window batch reader
    ├── log_parser.py
    ├── analyzer.py
    ├── signal_driver.py
    ├── signal_load.py            # Load/fanout finder, Static + NPI
    ├── connectivity_backend.py   # ConnectivityBackend protocol + select_backend
    ├── verdi_backend.py          # KDB / license probe + kdb_hint generator
    ├── verdi_npi_backend.py      # NPI-backed driver/load/path resolution
    ├── npi_lsf.py                # Optional LSF transport + Verdi/NPI worker protocol
    ├── npi_worker.py             # Compute-node Verdi/NPI worker entry point
    ├── kdb_builder.py            # Auto-build Verdi KDB (vericom + elabcom) for Xcelium flows
    ├── structural_scanner.py
    ├── x_trace.py
    ├── cycle_query.py
    ├── schemas.py
    ├── problem_hints.py
    ├── hierarchy_provider.py     # Bounded lexical/semantic instance-binding views
    ├── hierarchy_handles.py      # HandleStore + content-addressed handle for build_tb_hierarchy
    ├── handle_tools.py           # get_tb_subtree / lookup_tb_files / find_tb_instance / ...
    ├── cursor_store.py           # Named, process-scoped time anchors (cursor_set/list/delete)
    ├── timespec.py               # Resolve @cursor / unit literals (12.34ns) to ps on time inputs
    ├── verify_condition.py       # diff_first_divergence, period, inspect_handshake
    ├── window_verify.py          # verify_window: temporal predicate over a clock window
    ├── handshake_suggest.py      # suggest_handshakes / suggest_protocol_bundles
    ├── handshake_sweep.py        # sweep_handshakes: whole-design handshake anomaly sweep
    ├── txn_reconstruct.py        # reconstruct_transactions: id-correlated transaction layer
    ├── cancellation.py           # Cooperative cancellation for worker-thread waveform scans
    └── usage_telemetry.py        # Local-only per-call usage telemetry (default off; opt-in)

Installation

TraceWeave requires Python 3.11+.

Choose an installation profile

Use one installation profile from the start:

Profile	Intended use	Command
Repository-local full EDA	Simulation hosts with Source Graph, FSDB, Verdi/NPI, VCS/Xcelium, or LSF workflows	Clone this repository, then run bash scripts/install.sh
Portable PyPI	Log/VCD analysis and the unlicensed Python fallback stack	python -m pip install traceweave-mcp
Portable PyPI + Source Graph	Portable profile plus the pinned open-source pyslang frontend	python -m pip install "traceweave-mcp[source-graph]"

When a user gives an AI coding agent this repository URL and asks it to install TraceWeave, that means the repository-local full EDA profile unless the user explicitly asks for the portable PyPI profile. Do not extend a PyPI environment with repository FSDB setup scripts: the wheel and the repository resolve the native wrapper from different runtime roots.

Repository-local full EDA installation

This is the recommended profile on simulation hosts and for users who have a local Verdi installation. It keeps Python packages, the FSDB wrapper, and the runtime links together under one repository root:

git clone https://github.com/gokeshenzhen/TraceWeave.git
cd TraceWeave
export VERDI_HOME=/path/to/verdi
bash scripts/install.sh

Alternatively, pass the Verdi root for this installer process only:

bash scripts/install.sh --verdi-home /path/to/verdi

The installer is a thin, idempotent orchestration of the established local workflow:

scripts/setup_source_graph.sh
→ scripts/setup_fsdb.sh
→ scripts/verify_fsdb.sh
→ repository MCP runtime smoke check

It never edits shell startup files or MCP client configuration. Inspect an existing installation without creating an environment, compiling, or changing links:

bash scripts/install.sh --check
bash scripts/install.sh --check --json

After a successful installation, print an absolute-path configuration template without writing it:

bash scripts/install.sh --print-config codex
bash scripts/install.sh --print-config claude
bash scripts/install.sh --print-config copilot

The existing component commands remain supported for users and site automation that already invoke them directly:

bash scripts/setup_source_graph.sh
bash scripts/setup_fsdb.sh
bash scripts/verify_fsdb.sh

setup_source_graph.sh installs requirements-source-graph.txt (the MCP runtime, PyYAML, and pyslang==11.0.0) into .venv. Its own read-only check is:

bash scripts/setup_source_graph.sh --check

For FSDB support, the repository setup links VERDI_HOME/share/FsdbReader/linux64/{libnsys.so,libnffr.so} under third_party/verdi_runtime/linux64 and builds libfsdb_wrapper.so in the repository root. If those prerequisites are unavailable, use the portable profile with VCD waveforms instead.

After git pull: libfsdb_wrapper.so is built locally, not tracked in git. If a pulled update changed fsdb_wrapper.cpp, rebuild it with bash scripts/setup_fsdb.sh (or bash build_wrapper.sh) and rerun bash scripts/verify_fsdb.sh. An outdated ABI deliberately fails loudly rather than risking misaligned waveform timestamps.

For a legacy repo-local minimal installation without Source Graph, the existing manual dependency setup remains available:

python3.11 -m pip install "mcp==1.27.0" pyyaml --user

Portable PyPI installation

Install the base MCP runtime and launch the stdio server from any directory:

python -m pip install traceweave-mcp
traceweave-mcp

The base package includes log/VCD analysis and the unlicensed Python fallback stack. To add the pinned open-source Source Graph frontend:

python -m pip install "traceweave-mcp[source-graph]"

pyslang is intentionally optional: the server starts without it and reports a structured Source Graph dependency blocker before falling back to Legacy Static. Inspect this installation without starting the stdio server:

traceweave-mcp --doctor
traceweave-mcp --doctor --json

PyPI distributions do not contain fsdb_wrapper.cpp, build_wrapper.sh, the repository FSDB setup scripts, libfsdb_wrapper.so, Synopsys/Cadence runtime libraries, license data, VCS/Xcelium, or the proprietary Verdi pynpi runtime. Setting VERDI_HOME can provide external EDA libraries, but it does not create the missing TraceWeave FSDB wrapper. A manually injected wrapper inside site-packages is an unsupported mixed layout; use the repository-local full EDA profile instead. Verdi NPI discovery is independent of the FSDB reader and remains conditional on the site's complete KDB, pynpi, runtime, license, and local/LSF environment.

The Official MCP Registry distribution uses the name io.github.gokeshenzhen/traceweave. After publication, use that exact name or traceweave in the registry search box.

Client Setup

Generic MCP Client

Any MCP client that supports stdio transport can connect to this server. The minimum configuration is:

• Portable PyPI installation: command traceweave-mcp, args []
• Repository-local full EDA installation: command <TRACEWEAVE_HOME>/.venv/bin/python after running scripts/install.sh, args ["<TRACEWEAVE_HOME>/server.py"]
• EDA env: keep the site-provided Verdi/NPI, VCS/Xcelium, license, and optional LSF variables available to the repository-local MCP process

If the client supports server instructions, it can follow the built-in workflow directly. Otherwise, use the workflow below.

Claude Code

Environment inheritance depends on how the MCP client itself is launched and on that client's environment policy. In one tested terminal-launched tcsh/LSF setup, Claude Code passed the shell-configured LSF, Verdi, and license variables to TraceWeave, and remote NPI driver/load/path queries worked without a separate MCP environment list. An IDE/GUI launch or another client setup may not inherit the same environment. For a deterministic Claude Code setup, list every variable the server needs — tool roots plus the dlopen chain (LD_LIBRARY_PATH is the one most often missed; without it NPI silently falls back to Static and trace_signal_path returns found: false).

Add this to ~/.claude.json:

{
  "mcpServers": {
    "TraceWeave": {
      "command": "<TRACEWEAVE_HOME>/.venv/bin/python",
      "args": ["<TRACEWEAVE_HOME>/server.py"],
      "env": {
        "VERDI_HOME": "<verdi-install>",
        "NOVAS_HOME": "<verdi-install>",
        "VCS_HOME": "<vcs-install>",
        "XLM_ROOT": "<xcelium-install>",
        "CDS_INST_DIR": "<xcelium-install>",
        "SNPSLMD_LICENSE_FILE": "xxxx@s-license.example.com",
        "LM_LICENSE_FILE": "xxxx@s-license-server.example.com",
        "CDS_LICENSE_FILE": "xxxx@c-license.example.com",
        "LD_LIBRARY_PATH": "<library-path>",
        "PATH": "<path>"
      }
    }
  }
}

Verify the connection:

claude mcp list
# Should show TraceWeave (connected)

Codex

Codex supports two ways to provide environment variables to the TraceWeave MCP server:

• Put fixed values in [mcp_servers.TraceWeave.env]. This suits stable tool and license locations, or a Codex process that is not launched from a configured terminal.
• Use env_vars to allow and forward variables already inherited by the Codex process. This suits EDA environments managed by .bashrc, .tcshrc, or a site setup script.

Choose one source for each variable; do not configure the same name in both env and env_vars. This matches the official Codex MCP configuration. The example below uses fixed values in ~/.codex/config.toml:

[mcp_servers.TraceWeave]
command = "<TRACEWEAVE_HOME>/.venv/bin/python"
args = ["<TRACEWEAVE_HOME>/server.py"]
cwd = "<TRACEWEAVE_HOME>"

[mcp_servers.TraceWeave.env]
VERDI_HOME = "<verdi-install>"
NOVAS_HOME = "<verdi-install>"
VCS_HOME = "<vcs-install>"
XLM_ROOT = "<xcelium-install>"
CDS_INST_DIR = "<xcelium-install>"
SNPSLMD_LICENSE_FILE = "xxxx@s-license.example.com"
LM_LICENSE_FILE = "xxxx@s-license-server.example.com"
CDS_LICENSE_FILE = "xxxx@c-license.example.com"
LD_LIBRARY_PATH = "<library-path>"
PATH = "<path>"

If a site setup script manages these values, do not copy its expanded values into env. Launch Codex from the configured terminal and use the inherited environment pattern in the LSF-only section below instead.

Verify the connection:

codex mcp list
# Should show TraceWeave with Status: enabled

LSF-only NPI licenses

Some EDA sites grant Verdi/NPI licenses only to scheduled compute nodes. NPI execution remains local by default; opt in to LSF at the TraceWeave MCP server process with:

export TRACEWEAVE_NPI_EXECUTION=lsf
export TRACEWEAVE_NPI_LSF_QUEUE="digital"

Here digital is only an example; replace it with the user's licensed team queue. TraceWeave reads only the namespaced TRACEWEAVE_NPI_LSF_QUEUE; it does not create, overwrite, or interpret a site's generic LSF_QUEUE. If the site already exports LSF_QUEUE, the user may map that existing value instead:

export TRACEWEAVE_NPI_LSF_QUEUE="$LSF_QUEUE"

For tcsh:

setenv TRACEWEAVE_NPI_EXECUTION lsf
setenv TRACEWEAVE_NPI_LSF_QUEUE "digital"

Or, only when LSF_QUEUE already exists:

setenv TRACEWEAVE_NPI_LSF_QUEUE "$LSF_QUEUE"

Putting these values in .bashrc / .tcshrc works only when the MCP client passes that shell environment to the TraceWeave server. In the tested terminal-launched setup, Claude Code did so and completed LSF-hosted NPI driver/load/path queries. Codex required the needed site variables to be named in env_vars; without them, the NPI attempt failed.

The following Codex configuration is for an EDA environment already established by the parent shell. It is an alternative to the fixed-value EDA block in the Codex section above. The list reflects one tested LSF/EGO site; add or remove names to match the site's setup, and do not repeat any name under env:

[mcp_servers.TraceWeave]
command = "<TRACEWEAVE_HOME>/.venv/bin/python"
args = ["<TRACEWEAVE_HOME>/server.py"]
cwd = "<TRACEWEAVE_HOME>"
env_vars = [
  "TRACEWEAVE_NPI_LSF_QUEUE",

  "LSF_ENVDIR",
  "LSF_BINDIR",
  "LSF_SERVERDIR",
  "LSF_LIBDIR",
  "PATH",

  "EGO_TOP",
  "EGO_BINDIR",
  "EGO_CONFDIR",
  "EGO_ESRVDIR",
  "EGO_LIBDIR",
  "EGO_LOCAL_CONFDIR",
  "EGO_SERVERDIR",

  "VERDI_HOME",
  "LD_LIBRARY_PATH",

  "LM_LICENSE_FILE",
  "SNPSLMD_LICENSE_FILE",
]

[mcp_servers.TraceWeave.env]
TRACEWEAVE_NPI_EXECUTION = "lsf"

Values under [mcp_servers.TraceWeave.env] are copied literally by Codex, so do not write TRACEWEAVE_NPI_LSF_QUEUE = "$LSF_QUEUE" there. env_vars is the supported way to forward the value that the user's shell already expanded. If the Codex parent does not inherit the shell environment, omit the queue from env_vars and put a fixed TRACEWEAVE_NPI_LSF_QUEUE = "digital" directly under [mcp_servers.TraceWeave.env] instead. If some EDA values are intentionally fixed under env, omit those same names from env_vars.

In the tested terminal-launched Claude Code setup, no extra MCP environment map was needed when the shell already exported both namespaced values and the full site environment. For a deterministic setup, or when the client does not inherit that shell, merge the following fixed values into the existing TraceWeave server's "env" object (replace digital with the user's queue):

{
  "TRACEWEAVE_NPI_EXECUTION": "lsf",
  "TRACEWEAVE_NPI_LSF_QUEUE": "digital"
}

JSON values are literal too; do not put "$LSF_QUEUE" in this static map.

With this mode enabled, explicit connectivity operations (explain_signal_driver, find_signal_loads, trace_signal_path, trace_x_source) and every build_kdb cache miss or forced rebuild submit a short bsub -K worker. Exact KDB cache hits, log parsing, waveform reads, structural scans, KDB detection, and Static analysis remain local because they do not invoke a licensed Verdi executable. Connectivity-worker failure or timeout falls through to the local Source Graph and then to Legacy Static if that bounded graph is unavailable or inconclusive. A KDB-build worker failure does not fall back to local vericom/elabcom; build_kdb returns a fixed failure receipt instead. Static still has no path API, so a final path fallback is explicitly unsupported. Routing is visible through fixed backend_status.execution_mode / scheduler_status / worker_status / fallback_reason labels; queue, host, command, and license details are not returned.

After restarting or reconnecting the MCP server, ask the AI agent to run one explicit connectivity operation and report backend_status. A successful LSF NPI call has execution_mode="lsf", scheduler_status="completed", worker_status="completed", and actual_backend="verdi_npi". Otherwise inspect fallback_reason; a Static fallback is not an exact NPI result.

For an Xcelium KDB cache miss, build_kdb exposes the same top-level execution_mode / scheduler_status / worker_status / fallback_reason labels. A successful remote build reports execution_mode="lsf" and both statuses as "completed"; a cache hit reports both statuses as "not_started" because no license-bearing process ran.

An error-marked KDB may still complete the worker successfully. In that case actual_backend="verdi_npi" is paired with kdb_degraded=true; read the NPI attempt's coverage_status="partial" and the kdb_error_count / kdb_error_log diagnostics rather than treating scheduler completion alone as proof of complete elaboration.

Optional settings:

export TRACEWEAVE_NPI_LSF_TIMEOUT=120
export TRACEWEAVE_NPI_LSF_KDB_TIMEOUT=1260
export TRACEWEAVE_NPI_LSF_BSUB=/path/to/bsub
export TRACEWEAVE_NPI_LSF_BKILL=/path/to/bkill
export TRACEWEAVE_NPI_LSF_PYTHON=/path/to/python3.11
export TRACEWEAVE_NPI_LSF_STAGING_DIR=/shared/private/traceweave-npi
export TRACEWEAVE_NPI_LSF_EXTRA_ARGS_JSON='["-R", "select[...]"]'

The compile log, every source/include input, TraceWeave checkout/installation, staging directory, and TRACEWEAVE_CACHE_DIR (including the generated KDB) must be visible at the same absolute paths on the submission and compute nodes. After a remote success the parent verifies that the returned KDB path is visible; otherwise it reports npi_lsf_artifact_unavailable. The staging directory defaults under TraceWeave's cache root; set it explicitly when that cache is not on a shared filesystem. TRACEWEAVE_NPI_LSF_TIMEOUT controls short connectivity jobs; TRACEWEAVE_NPI_LSF_KDB_TIMEOUT separately bounds queue wait plus both KDB phases (default 1260 seconds). Scheduler options are JSON argv, not shell text, and are limited to scheduler option/value pairs.

On-Demand Source Graph