# Gf Viz

> Terminal visualization for GateFlow codebase maps. Renders module hierarchies, FSM state diagrams, and module detail cards as interactive ASCII/Unicode art. Example requests: "visualize the codebase", "show hierarchy", "show FSM", "show module detail"

- Skill: `codejunkie99/gf-viz` (Agent Skill)
- Install (CLI): `npx skillmds@latest add codejunkie99/gf-viz`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codejunkie99/gf-viz/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codejunkie99 (https://skillmd.com/u/codejunkie99)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/codejunkie99/gf-viz

---


# GF-Viz: Terminal Visualization

Renders `.gateflow/map/` data as interactive ASCII/Unicode diagrams in the terminal.

## Prerequisites

Check for codebase map:

```bash
ls .gateflow/map/CODEBASE.md 2>/dev/null
```

- **Map exists:** Proceed to render
- **No map:** Tell user: "No codebase map found. Run `/gf-map` first to generate one."

## Entry Point

When invoked, render the **Overview Dashboard** and present the navigation menu.

If invoked with an argument (e.g., `/gf-viz uart_tx`), jump directly to the **Module Detail Card** for that module.

---

## View 1: Overview Dashboard

**Data sources:** `CODEBASE.md` (stats, module index), `hierarchy.md` (tree), `fsm.md` (FSM list), `clock-domains.md` (clocks/CDC)

Read these files, extract the data, and render:

```
╔══ CODEBASE: <project_name> ═══════════════════════════════╗
║                                                            ║
║  ● N modules  ● N packages  ● N FSMs  ● N interfaces       ║
║  ● N clocks   ● N CDC       ● N ports   ● N warnings       ║
║                                                            ║
╠══ HIERARCHY (compact) ════════════════════════════════════╣
║                                                            ║
║  ◆ <top> ──┬── <child1> ──┬── <grandchild1>               ║
║            │              └── <grandchild2>                ║
║            └── <child2> ── <grandchild3>                   ║
║                                                            ║
╠══ FSMs ═══════════════════════════════════════════════════╣
║  ↻ <fsm_name> (<module>)  N states: S1→S2→S3→S4           ║
║  ↻ <fsm_name> (<module>)  N states: S1→S2→S3              ║
║                                                            ║
╠══ HEALTH ═════════════════════════════════════════════════╣
║  <✓ or ⚠> lint status  <✓ or ⚠> undriven  <✓ or ⚠> CDC   ║
║                                                            ║
╠═══════════════════════════════════════════════════════════╣
║  [1] Hierarchy  [2] FSMs  [3] Module detail                ║
║  Or ask anything: "show uart_tx", "trace data path"        ║
╚═══════════════════════════════════════════════════════════╝
```

**Rules:**
- Hierarchy flattened to **2 levels max** in dashboard
- FSMs show **one-line summaries** with state chain
- Stats pulled from CODEBASE.md frontmatter and module index
- Health pulled from warnings section
- If any section has no data, show "none detected" rather than omitting

---

## View 2: Hierarchy Explorer

**Data sources:** `hierarchy.md`, `modules/*.md`

```
══ MODULE HIERARCHY ════════════════════════════════════════

◆ <top_module>                                       TOP
├── ■ <inst> : <module> [PARAM=VAL]                   MID
│   ├── ■ <inst> : <module>                           MID
│   │   ├── □ <inst> : <module>                       LEAF
│   │   └── □ <inst> : <module>                       LEAF
│   └── □ <inst> : <module> [W=32, D=16]              LEAF
└── ■ <inst> : <module>                               MID
    └── □ <inst> : <module>                           LEAF

── STATS ──────────────────────────────────────────────
  Total: N modules │ Max depth: N │ Leaf count: N

── INSTANCE TABLE ─────────────────────────────────────
  ┃ Parent       │ Instance   │ Module          │ Params       ┃
  ┃ ...          │ ...        │ ...             │ ...          ┃

═══════════════════════════════════════════════════════════
  [H] Home  [2] FSMs  [3] Module detail: <name>
  Or: "show <module>", "which modules use <module>?"
```

**Module type badges:**
- `◆` **TOP** - bold, top-level module (never instantiated by others)
- `■` **MID** - standard weight, has children
- `□` **LEAF** - lighter weight, no children

**Depth cues:** Deeper modules rendered with lighter visual weight. Top pops, leaves fade.

**Behaviors:**
- Show full tree with all depth levels
- Parameters shown inline as `[PARAM=VAL]`
- Instance table shows all parent→child relationships
- "show <module>" re-renders tree rooted at that module
- "which modules use <module>?" searches instance table, lists parents

---

## View 3: FSM Viewer

**Data sources:** `fsm.md`, per-module pages

**When multiple FSMs exist, show picker first:**

```
══ STATE MACHINES ══════════════════════════════════════════

  [1] ↻ <fsm_name>  (<module>)   N states
  [2] ↻ <fsm_name>  (<module>)   N states
  [3] ↻ <fsm_name>  (<module>)   N states

  Pick a number, or: "show <fsm_name>"
```

**Single FSM rendering:**

```
══ FSM: <fsm_name> ═════════════════════════════════════════
   Module: <module> │ Encoding: N-bit │ Reset: → <reset_state>

                    <condition>
   ┌──────┐  ─────────────►  ┌───────┐
   │      │                  │       │
   │  S1  │                  │  S2   │
   │  ◉   │                  │       │
   └──────┘                  └───┬───┘
      ▲                          │ <condition>
      │                          ▼
   ┌──────┐                  ┌───────┐
   │      │  ◄───────────   │       │──┐
   │  S4  │   <condition>   │  S3   │  │ <self-loop cond>
   │      │                  │       │◄─┘
   └──────┘                  └───────┘

── TRANSITIONS ────────────────────────────────────────────
  ┃ From  │ To    │ Condition     │ Output          ┃
  ┃ S1    │ S2    │ ...           │ ...             ┃
  ┃ S2    │ S3    │ ...           │ ...             ┃
  ┃ ...   │ ...   │ ...           │ ...             ┃

── STATE DETAILS ──────────────────────────────────────────
  ◉ S1   Reset state. <description>
    S2   <description>
    S3   <description>
    S4   <description>

═══════════════════════════════════════════════════════════
  [H] Home  [1] Hierarchy  [3] Module: <parent_module>
  Or: "show another FSM", "explain the S2→S3 transition"
```

**Layout rules for FSM box diagrams:**
- **2-4 states:** Arrange in a line or L-shape
- **4-6 states:** Arrange in a 2x2 or 2x3 grid
- **7+ states:** Use transition table only (too complex for ASCII boxes)
- Reset state always marked with `◉`
- Self-loops shown as `──┐` / `◄─┘` back to same box
- Transition arrows use `──►` with condition labels

**Behaviors:**
- "explain <from>→<to> transition" triggers analysis using RTL source
- "show module" cross-links to parent module's detail card
- Output column in transition table filled when map data includes it

---

## View 4: Module Detail Card

**Data sources:** `modules/<module_name>.md` (primary), `hierarchy.md`, `fsm.md`, `signals.md`

```
╔══════════════════════════════════════════════════════════╗
║  <module_name>                              <TYPE_BADGE> ║
║  <file_path>:<line_range>                                ║
╠══ PARAMETERS ════════════════════════════════════════════╣
║  ┃ Name     │ Type │ Default     │ Description       ┃  ║
║  ┃ ...      │ ...  │ ...         │ ...               ┃  ║
╠══ PORTS ═════════════════════════════════════════════════╣
║  → <name>     input   <width>   <description>           ║
║  → <name>     input   <width>   <description>           ║
║  ← <name>     output  <width>   <description>           ║
║  ← <name>     output  <width>   <description>           ║
╠══ INTERNALS ═════════════════════════════════════════════╣
║                                                          ║
║  Clock : <clock_name> (<domain info>)                    ║
║  Reset : <reset_name> (<type>)                           ║
║  FSM   : ↻ <fsm_name> → <state_list>                    ║
║  Inst  : <instance_count> (<list or "none (leaf)")>      ║
║                                                          ║
╠══ CONNECTIONS ═══════════════════════════════════════════╣
║                                                          ║
║  Instantiated by:                                        ║
║    ■ <parent_module> as <instance_name>                  ║
║      .<port>(<signal>) .<port>(<signal>)                 ║
║      .<port>(<signal>) .<port>(<signal>)                 ║
║                                                          ║
╠══ HEALTH ════════════════════════════════════════════════╣
║  <✓ or ⚠> port connection status                         ║
║  <✓ or ⚠> lint status                                    ║
║  <✓ or ⚠> assertion coverage                             ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝
  [H] Home  [1] Hierarchy  [2] FSM: <fsm_name>
  [↑] Parent: <parent_module>
  Or: "show ports", "explain the handshake", "add assertions"
```

**Port direction symbols:**
- `→` inputs
- `←` outputs
- `↔` bidirectional (inout)

**Type badges:** `TOP`, `MID`, `LEAF`

**Behaviors:**
- Connections section shows **actual signal bindings** from parent instantiation
- If module is instantiated multiple times, show each instance
- FSM line cross-links to FSM viewer
- Parent name cross-links to parent's detail card
- "add assertions" can hand off to `sv-verification` agent
- "explain the handshake" reads RTL source to reason about protocol

---

## Color/Emphasis Vocabulary

Apply these consistently across all views:

| Element | Symbol | Style |
|---------|--------|-------|
| Top module | `◆` | **Bold** |
| Mid module | `■` | Standard |
| Leaf module | `□` | Light |
| Input port | `→` | Green emphasis |
| Output port | `←` | Yellow emphasis |
| Bidir port | `↔` | Cyan emphasis |
| FSM indicator | `↻` | Standard |
| Reset state | `◉` | **Bold/highlighted** |
| Clean/pass | `✓` | Green |
| Warning | `⚠` | Yellow/amber |
| Info/stat | `●` | Standard |
| Transition | `──►` | Standard |

**Depth cues in hierarchy:** Top-level bold, mid standard, leaf dimmed.

---

## Interaction Model

### Menu Navigation

After every render, show a navigation footer with numbered options:
- `[H]` Home - return to dashboard
- `[1]` `[2]` `[3]` - switch between views
- `[↑]` Parent - navigate up in hierarchy (detail card only)

### Free-Form Queries

Always accept natural language alongside menus:
- "show <module_name>" → Module Detail Card
- "show <fsm_name>" → FSM Viewer for that FSM
- "which modules use <module>?" → filtered hierarchy
- "trace <signal> from <module_a> to <module_b>" → signal path analysis
- "explain <aspect>" → reads RTL source, reasons about it
- "add assertions to <module>" → hands off to sv-verification agent
- "back" → previous view
- "home" → dashboard

### Agent Handoff

For queries that go beyond visualization:
- "explain" / "why" → spawn `sv-understanding` agent via Task tool
- "add assertions" → spawn `sv-verification` agent via Task tool
- "fix" / "refactor" → spawn `sv-refactor` agent via Task tool

When handing off, pass the current visualization context (which module, which view) so the agent has full context.

---

## Auto-Trigger After /gf-map

When used as a final step in `gf-architect`, render ONLY the Overview Dashboard (View 1) as a compact summary. Do not show the full interactive menu - just the dashboard with a note:

```
Run /gf-viz to explore interactively.
```

---

## Data Extraction

### Reading CODEBASE.md

Extract from frontmatter:
- `total_files`, `total_tokens`, `commit`, `last_mapped`

Extract from Module Index table:
- Module names, types, files, port summaries

Extract from Warnings section:
- Lint warnings, undriven signals, CDC issues

### Reading hierarchy.md

Extract from Mermaid flowchart:
- Parent→child relationships
- Instance names

Extract from Instance Table:
- Full parent, instance, module, parameters data

### Reading fsm.md

Extract for each FSM:
- FSM name, parent module
- State list with encoding
- Transition table (from, to, condition, output)
- Reset state

### Reading modules/*.md

Extract per module:
- Parameters table
- Ports table (name, direction, width, description)
- Clock/reset info
- Instance list
- Assertion/coverage info

---

## Edge Cases

- **Empty map:** "No codebase map found. Run `/gf-map` first."
- **No FSMs detected:** FSM section shows "No state machines detected in this codebase."
- **Single module:** Hierarchy view shows just the one module. Skip instance table.
- **Module not found:** "Module '<name>' not found in map. Available modules: <list>"
- **Very deep hierarchy (>6 levels):** Render full tree but note: "Deep hierarchy detected. Use 'show <module>' to focus on a subtree."
- **Very wide hierarchy (>10 siblings):** Show first 8, then "... and N more. Use 'show <parent>' to see all."

---

## View 5: Signal Path Trace

Triggered by: "trace data_in from top to digest_out"

Renders signal path across module boundaries as ASCII with boxes for modules, arrows for signals, and `◈` markers for registered boundaries (pipeline stages). Shows hop count and pipeline stage summary.

## View 6: Timing Diagram

Triggered by: "timing uart_tx" or "timing fsm tx_state"

ASCII waveforms: `┌─┐└─┘` for clock, `───` high, `___` low, `╡val╞` for bus/enum values. Auto-generates from FSM data or known protocol patterns. Accepts WaveJSON input for custom diagrams.

## View 7: Diff View

Triggered by: "diff" or "what changed"

Shows structural changes between map snapshots: `+ ADDED`, `~ MODIFIED` (with specific change: port/instance/FSM/parameter), `- REMOVED`. Requires previous snapshot at `.gateflow/map/.prev_*`.

## View 8: Port Connection Matrix

Triggered by: "matrix uart_ctrl" or "connections"

Table showing which parent signals connect to which instance ports. Bottom row shows connected/unconnected counts. Separate section lists all unconnected ports with `⚠` warning. Compact dot-matrix variant for large designs: `●` connected, `○` not connected.

## Search

Triggered by: "find modules with FSM", "find signals named *_valid"

| Query | Finds |
|---|---|
| `find modules with <clock>` | Modules using specific clock |
| `find modules with fsm` | All modules containing FSMs |
| `find modules with >20 ports` | Large interface modules |
| `find signals named <glob>` | Signal name pattern match |
| `find instances of <module>` | All instantiations |
| `find unconnected ports` | Floating ports |
| `find cdc crossings` | Clock domain crossings |