{
  "markdown": "# VisualCave — Interactive Diagram Generator for AI Agents\n\n![Validate Diagrams](https://github.com/varkart/visualcave/actions/workflows/ci.yml/badge.svg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nVisualCave is an agentic custom skill and plugin that enables AI assistants (**Claude Code**, **Cursor**, **Codex CLI**, and **Gemini CLI**) to design and render gorgeous, fully-interactive technical diagrams as standalone HTML files or embeddable Astro/MDX components.\n\nPowered by **[Mermaid.js](https://mermaid.js.org)**, it supports 11 diagram types including flowcharts, sequence diagrams, ER diagrams, class diagrams, git graphs, mind maps, and more.\n\nEvery output automatically includes:\n\n- **Presentation Tools:** Step-through reveal for guided slideshow walkthroughs and dynamic hover-highlighting.\n- **Design Customization:** Smooth dark/light mode toggle and four distinct theme presets (Default, Minimal, Pastel, Print).\n- **One-Click Client Export:** Direct SVG, PNG, and PDF downloads right from the browser controls bar — with absolutely no server or local build step required.\n\n**[View Showcase Site →](https://varkart.github.io/visualcave)**\n\n![VisualCave demo](assets/visual-cave.gif)\n\n---\n\n## Installation\n\n**Claude Code (global)**\n\n```bash\ngit clone https://github.com/varkart/visualcave ~/.claude/skills/visualcave\n```\n\n**Claude Code (per-project)**\n\n```bash\ngit clone https://github.com/varkart/visualcave .claude/skills/visualcave\n```\n\n**Cursor — global skill**\n\n```bash\ngit clone https://github.com/varkart/visualcave ~/.cursor/skills-cursor/visualcave\n```\n\n**Cursor — project rules only**\n\nCopy `.cursor/rules/visualcave.mdc` into your project's `.cursor/rules/` directory.\n\n**Codex CLI — skill (git)**\n\n```bash\ngit clone https://github.com/varkart/visualcave ~/.codex/skills/visualcave\n```\n\n**Codex CLI — plugin (marketplace)**\n\n```bash\ncodex plugin marketplace add varkart/visualcave\ncodex plugin add visualcave\n```\n\n**Gemini CLI — extension (git)**\n\n```bash\ngit clone https://github.com/varkart/visualcave ~/.gemini/extensions/visualcave\n```\n\n**Gemini CLI — extension (install command)**\n\n```bash\ngemini extensions install https://github.com/varkart/visualcave\n```\n\n**Google Antigravity CLI (`agy`) — skill (git)**\n\n```bash\ngit clone https://github.com/varkart/visualcave ~/.gemini/antigravity-cli/skills/visualcave\n```\n\n**Google Antigravity CLI (`agy`) — plugin (git)**\n\n```bash\ngit clone https://github.com/varkart/visualcave ~/.gemini/antigravity-cli/plugins/visualcave\nagy plugin install ~/.gemini/antigravity-cli/plugins/visualcave\n```\n\n**Kiro — skill (git)**\n\n```bash\ngit clone https://github.com/varkart/visualcave ~/.kiro/skills/visualcave\n```\n\n**Kiro — Power**\n\nAdd as a Power in Kiro settings using the GitHub URL `https://github.com/varkart/visualcave`. For project-level steering, copy `.kiro/steering/visualcave.md` into your project's `.kiro/steering/` directory.\n\nNo restart required after installation.\n\n---\n\n## Usage\n\nSee **[EXAMPLES.md](EXAMPLES.md)** for real prompts and patterns showing what to ask for and what output to expect.\n\nInvoke with `/visualcave` in your AI assistant, then describe your diagram:\n\n```text\n/visualcave — how OAuth 2.0 works\n/visualcave — interactive walkthrough of a RAG pipeline\n/visualcave — Transformer architecture \"Attention Is All You Need\"\n/visualcave — order lifecycle state machine with all edge cases\n/visualcave — GitFlow branching strategy with release and hotfix branches\n```\n\nOutputs a single self-contained `.html` file. Open it in any browser — no build step, no server.\n\n---\n\n## Quick Start\n\n1. Install (Claude Code global): `git clone https://github.com/varkart/visualcave ~/.claude/skills/visualcave`\n2. In your Claude Code session, type `/visualcave` followed by what you want:\n   ```text\n   /visualcave — how OAuth 2.0 works\n   ```\n3. Claude generates a `.html` file. Open it in any browser.\n4. Use the controls bar in the diagram to switch themes, toggle dark mode, step through phases, or export as SVG/PNG/PDF.\n\n---\n\n## Key Features\n\n- **11 diagram types** — flowchart, sequence, class, ER, state machine, quadrant, timeline, mind map, git graph, pie, gantt\n- **Interactive step-through** — click to reveal phases one by one; ideal for architecture walkthroughs and presentations\n- **Hover highlight** — mousing over a node dims unrelated nodes to focus attention\n- **Design theme selector** — four themes (Default, Minimal, Pastel, Print) switchable from the controls bar; each theme adjusts both Mermaid's color scheme and all `classDef` node colors simultaneously; selection persisted to `localStorage`\n- **Dark / light mode toggle** — smooth CSS transition, respects `prefers-color-scheme` on first load\n- **Copy Mermaid source** — one-click copy of the raw diagram source for reuse or editing\n- **In-page export** — SVG, PNG, and PDF download buttons in every diagram's controls bar; fully client-side, no server or Node.js required\n- **CLI export** — animated GIF, OG social card (1200×630), and headless batch export via `capture.js` (requires Node.js 18+)\n- **Astro / React component output** — generate site-ready `.astro` or `.tsx` components for embedding diagrams into blog posts and articles, with full dark/light token alignment\n- **Living diagram animation** — two modes on request: CSS flow (flowing edges + node glow on any Mermaid diagram, zero deps) or Canvas (full custom particles, physics, signal propagation — no Mermaid needed)\n- **Zero runtime dependencies** — Mermaid loaded from CDN; all other logic is inlined in the HTML file\n\n---\n\n## Diagram Type Reference\n\n| Intent                                        | Mermaid keyword         |\n| --------------------------------------------- | ----------------------- |\n| Flow, pipeline, architecture, system overview | `graph TD` / `graph LR` |\n| Sequence, API calls, actor interactions       | `sequenceDiagram`       |\n| Class / object / domain model (UML)           | `classDiagram`          |\n| State machine, lifecycle, status transitions  | `stateDiagram-v2`       |\n| Database schema, tables, entity relationships | `erDiagram`             |\n| 2×2 priority / effort-impact matrix           | `quadrantChart`         |\n| History, milestones, roadmap dates            | `timeline`              |\n| Brainstorm, concept map, topic overview       | `mindmap`               |\n| Git branching, commits, merges                | `gitGraph`              |\n| Distribution, percentage breakdown            | `pie`                   |\n| Project schedule, sprint plan                 | `gantt`                 |\n\n---\n\n## Examples\n\nAll examples are in [`examples/`](examples/) and live at the [showcase site](https://varkart.github.io/visualcave).\n\n**Architecture & Flow**\n\n- [Transformer Architecture (step-through)](examples/transformer-deep-dive.html) — step-through reveal, dark mode\n- [OAuth 2.0 Flow](examples/oauth-flow.html) — sequence diagram\n- [API Gateway Architecture](examples/architecture-api-gateway.html)\n- [CI/CD Pipeline](examples/pipeline-cicd.html)\n- [E-commerce Order Flow](examples/ecommerce-order-flow.html)\n- [Event-Driven Microservices](examples/event-driven-microservices.html)\n- [Kubernetes Deployment](examples/kubernetes-deployment.html)\n- [Multi-Region Failover](examples/multi-region-failover.html)\n- [RAG Pipeline](examples/rag-pipeline.html)\n- [API Lifecycle](examples/api-lifecycle.html)\n\n**Object & Data Models**\n\n- [E-Commerce Domain Model](examples/class-diagram.html) — `classDiagram`\n- [Blog Database Schema](examples/er-diagram.html) — `erDiagram`\n- [Order Lifecycle](examples/state-machine.html) — `stateDiagram-v2`\n\n**Planning & Analysis**\n\n- [Feature Priority Matrix](examples/quadrant-chart.html) — `quadrantChart`\n- [API Traffic Distribution](examples/pie-chart.html) — `pie`\n- [Release Sprint Plan](examples/gantt-chart.html) — `gantt`\n- [Monthly Active Users](examples/xy-chart.html) — `xychart-beta`\n- [Data Center Energy Flow](examples/sankey-diagram.html) — `sankey-beta`\n- [Internet Banking System Context](examples/c4-context.html) — `C4Context`\n- [Web App Infrastructure](examples/architecture-diagram.html) — `architecture-beta`\n- [Sprint Board](examples/kanban-board.html) — `kanban`\n\n**Knowledge & History**\n\n- [Evolution of the Web](examples/timeline.html) — `timeline`\n- [AI Evolution Timeline](examples/ai-evolution-timeline.html) — custom CSS timeline\n- [System Design Topics](examples/mindmap.html) — `mindmap`\n- [GitFlow Strategy](examples/git-graph.html) — `gitGraph`\n\n**Transformer Architecture Variants**\n\n- [Transformer Animated](examples/transformer-animated.html)\n- [Transformer Architecture](examples/transformer-architecture.html)\n- [Transformer Pro](examples/transformer-pro.html)\n- [Transformer Ultra](examples/transformer-ultra.html)\n\n---\n\n## Color Palette\n\nApply these `classDef` classes in `graph` and `classDiagram` diagrams:\n\n| Class       | Use for                            |\n| ----------- | ---------------------------------- |\n| `:::yellow` | Users, browsers, entry points      |\n| `:::blue`   | Services, APIs, compute            |\n| `:::green`  | Databases, storage, success states |\n| `:::purple` | Auth, AI models, security          |\n| `:::orange` | Queues, events, pipelines          |\n| `:::teal`   | Caching, CDN, external APIs        |\n| `:::note`   | Annotations, callouts              |\n\n---\n\n## Export\n\n### In-page buttons (no install required)\n\nEvery diagram includes **SVG**, **PNG**, and **PDF** download buttons in the controls bar alongside Dark Mode and Copy Code. All client-side:\n\n- **SVG** — serializes the rendered inline SVG with a white background\n- **PNG** — renders at 2x canvas resolution for crisp screenshots\n- **PDF** — triggers `window.print()` with print CSS that hides the controls\n\n### CLI export (`capture.js`)\n\nFor headless/batch use, animated GIFs, and OG social cards (requires Node.js 18+):\n\n```bash\nnode capture.js diagram.html                    # animated GIF\nnode capture.js diagram.html --format=png       # PNG screenshot\nnode capture.js diagram.html --format=svg       # extracted SVG\nnode capture.js diagram.html --format=pdf       # A4 PDF\nnode capture.js diagram.html --format=og        # 1200×630 OG image\n```\n\n---\n\n## Development\n\nRequires **Node.js 18+** (for `capture.js` / puppeteer).\n\n```bash\nnpm install\nnpx playwright install chromium\nnpm test             # run all diagram validation tests\nnpm run test:ui      # Playwright UI mode\nnpm run test:headed  # headed browser\n```\n\n---\n\n## Contributing\n\nSee [CLAUDE.md](CLAUDE.md) for contribution guidelines — what's accepted, what won't be merged, and how to run tests.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 10698,
  "sha": "ce33c71cb46084c602983ed92700cbe83395534fc9fc2ede93b65eb70b71ba68",
  "repo_slug": "varkart/visualcave",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_varkart_visualcave_80c9db9d/readme"
}