@the-forge-flow/visual-explainer-pi

---

Turns complex terminal output into styled, self-contained HTML pages for diagrams, architecture overviews, diff reviews, data tables, and project recaps. Built on top of the design system from nicobailon/visual-explainer.

✨ Features

• 🎨 11 Visual Types: architecture, flowchart, sequence, ER, state, table, diff, plan, timeline, dashboard, slides
• 🖌️ 8 Aesthetic Palettes: blueprint, editorial, paper, terminal, dracula, nord, solarized, gruvbox
• 📄 Self-Contained HTML: single file with embedded CSS/JS, opens in any browser
• 🧜 Mermaid Integration: automatic diagrams with zoom/pan controls
• 📊 Data Tables: responsive tables with sticky headers and status indicators
• 🤖 PI-native: seamless integration with PI's tool system, abort-signal aware, output truncated to PI's limits

📦 Installation

1. Install the extension with pi install

PI discovers the extension automatically once installed as a pi package. By default this installs globally into ~/.pi/agent/; pass -l to install into the current project (.pi/) instead.

From npm (recommended):

pi install npm:@the-forge-flow/visual-explainer-pi

From GitHub (tracks main):

pi install git:github.com/MonsieurBarti/visual-explainer-pi

Pin to a specific version:

# npm — pin to a published version
pi install npm:@the-forge-flow/visual-explainer-pi@0.1.0

# git — pin to a release tag
pi install git:github.com/MonsieurBarti/visual-explainer-pi@visual-explainer-pi-v0.1.0

Then reload PI with /reload (or restart it). On the next session you should see a notification that Visual explainer ready.

Manage installed packages:

pi list    # show installed packages
pi update  # update non-pinned packages
pi remove npm:@the-forge-flow/visual-explainer-pi
pi config  # enable/disable individual extensions, skills, prompts, themes

For project-scoped installs, package filtering, and more, see the pi packages doc.

🚀 Usage

The extension registers a single tff-generate_visual tool that the LLM can call directly. It also exposes two slash commands to reopen recently generated files.

The tool id is namespaced with the tff- prefix so it can coexist with other pi packages that might ship a tool named generate_visual. The user-facing display label ("Generate Visual") stays readable — only the LLM-facing id is prefixed.

tff-generate_visual

// Render a technical architecture diagram
tff-generate_visual({
  type: "architecture",
  title: "Auth System Overview",
  aesthetic: "blueprint",
  content: {
    sections: [
      { label: "Edge", content: "<div class=\"inner-card\">API Gateway</div>" },
      { label: "Core", content: "<div class=\"inner-card\">Auth Service</div>", isHero: true },
    ],
  },
});

// Render a Mermaid flowchart
tff-generate_visual({
  type: "flowchart",
  title: "Data Pipeline",
  aesthetic: "editorial",
  content: "graph LR; A[Ingest] --> B[Transform] --> C[Store]",
});

// Render a comparison table
tff-generate_visual({
  type: "table",
  title: "API Endpoints",
  aesthetic: "paper",
  content: [
    { method: "GET", path: "/users", status: "stable" },
    { method: "POST", path: "/users", status: "beta" },
  ],
});

Tool Parameters

Parameter	Type	Description
type	enum	Visual type: architecture, flowchart, sequence, er, state, table, diff, plan, timeline, dashboard, slides, mermaid_custom
content	string | array	Raw content (mermaid syntax, markdown) or structured data rows
title	string	Title for the visualization
aesthetic	enum	Palette: blueprint, editorial, paper, terminal, dracula, nord, solarized, gruvbox
theme	enum	light, dark, or auto
filename	string	Optional output filename (auto-generated if omitted)

Slash Commands

• /visual-reopen <n> — re-open a recently generated visual by index (1-10)
• /visual-list — list recently generated visuals

Output Location

Generated HTML files are saved to ~/.agent/diagrams/ and automatically opened in your default browser.

🏗️ Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│  LLM Request│────▶│tff-generate_visual│───▶│   Browser   │
│  (via PI)   │     │  (defineTool)    │     │   (HTML)    │
└─────────────┘     └────────┬─────────┘     └─────────────┘
                             │
                    ┌────────▼─────────┐
                    │ Palette + Template│
                    │ HTML Generation   │
                    │ File Written      │
                    └───────────────────┘

Every tool call:

1. Validates parameters (type, content, aesthetic, theme).
2. Picks a template (architecture, mermaid, data-table) and a palette.
3. Generates a self-contained HTML document with embedded CSS/JS.
4. Truncates output to PI's ~50KB/2000-line limit via truncateHead.
5. Writes the file to ~/.agent/diagrams/ and opens it in the default browser.

🎨 Design Principles

Inherited from nicobailon/visual-explainer:

• Typography First — distinctive font pairings (never Inter as primary)
• Warm Palettes — terracotta, sage, teal, rose (never indigo/violet/pink defaults)
• Depth Hierarchy — hero → elevated → default → recessed visual weight
• No AI Slop — forbidden: gradient text, emoji headers, neon glows, animated shadows
• Accessibility — respects prefers-reduced-motion, semantic HTML tables

🧪 Development

# Install dependencies (also wires lefthook git hooks)
bun install

# Run tests
bun test

# Lint & format
bun run check

# Typecheck
bun run typecheck

# Build for publish
bun run build

📁 Project Structure

src/
├── index.ts              # Extension entry, tool registration, state
├── types.ts              # TypeScript type definitions
├── templates/
│   ├── architecture.ts   # CSS Grid card layout
│   ├── data-table.ts     # HTML table template
│   ├── mermaid.ts        # Mermaid diagram wrapper
│   └── shared.ts         # Palettes, fonts, CSS variables
└── utils/
    ├── browser-open.ts   # Cross-platform browser launcher
    ├── file-writer.ts    # Temp file + state management
    └── validators.ts     # Input validation

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing)
3. Commit with conventional commits (git commit -m "feat: add something")
4. Push to the branch (git push origin feat/amazing)
5. Open a Pull Request

🙏 Credits

This extension re-uses the visual design system (palettes, typography, layout primitives) from nicobailon/visual-explainer by Nico Bailon. The PI integration layer (tool API, validators, templates re-implementation, tests) is original work. Huge thanks to Nico for the beautiful aesthetic foundation.

📜 License

MIT © MonsieurBarti

---