🚀 About

Viz Vibe is an open-source project that provides a graph-structured workflow as an interface for collaboration between humans and AI. By visualizing the coding process as an interactive graph, it enables intuitive and efficient "vibe coding" experiences.

💡 Vibe Coding — A new paradigm where developers and AI work together in harmony, guided by visual workflows and intuitive interactions.

🚀 Getting Started

For Claude Code Users

Run this one-liner in your project directory:

curl -fsSL https://raw.githubusercontent.com/NamHyeongKeol/viz-vibe/main/claude-code/install.sh | bash

This creates:

• .claude/settings.json — Claude Code settings with hooks
• .claude/hooks/update-vizvibe.js — Auto-update script
• vizvibe.mmd — Your work history graph (Mermaid format)
• VIZVIBE.md — AI instructions for trajectory management

That's it! Claude Code will automatically update vizvibe.mmd after each response.

Other Commands

# Update hook script to latest version
curl -fsSL https://raw.githubusercontent.com/NamHyeongKeol/viz-vibe/main/claude-code/update.sh | bash

# Uninstall (keeps vizvibe.mmd and VIZVIBE.md)
curl -fsSL https://raw.githubusercontent.com/NamHyeongKeol/viz-vibe/main/claude-code/uninstall.sh | bash

For VS Code / Cursor / Antigravity Users

Option 1: Install from Open VSX (Recommended)

• Install directly from Open VSX Registry
• Or search "Viz Vibe" in the Extensions panel

Option 2: Install from VSIX

1. Download the latest .vsix from Releases
2. Cmd+Shift+P → "Extensions: Install from VSIX..."
3. Select the downloaded file and reload

Setup:

1. Run Cmd+Shift+P → "Viz Vibe: Initialize Project"
2. Open vizvibe.mmd to see the graph visualization

Antigravity Users: Manual Updates Required

⚠️ Note: Antigravity doesn't support hooks yet, so automatic .mmd updates are not available.

When you want the AI to update your trajectory:

• Press Ctrl+Shift+Cmd+E to copy an update request to clipboard, then paste it into the chat
• Or simply ask: "Please update vizvibe.mmd with what we've done"

The extension automatically updates ~/.gemini/GEMINI.md during initialization, so the AI already knows how to manage the trajectory — no detailed explanation needed!

✨ Features

• 🔗 Graph-based Context — Visualize your coding journey as interconnected nodes
• 🤝 Human-AI Collaboration — Track decisions, blockers, and progress together
• 📊 Mermaid Native — Uses standard Mermaid syntax, viewable anywhere (GitHub, Notion, etc.)
• 🔄 Auto-Update — Trajectory updates automatically after AI responses (Claude Code)
• 📁 .mmd File Format — Human-readable, AI-editable Mermaid flowcharts
• 🤖 AI-Native Design — Built for AI assistants to read and modify

📁 File Format

Viz Vibe uses Mermaid flowchart syntax for trajectories:

flowchart TD
    %% @task_auth [ai-task, closed]: Implemented JWT authentication
    task_auth["JWT Authentication"]

    %% @task_tests [ai-task, opened]: Write integration tests
    task_tests["Integration Tests"]

    task_auth --> task_tests

    style task_auth fill:#334155,stroke:#475569,color:#f8fafc
    style task_tests fill:#334155,stroke:#475569,color:#f8fafc

Node States

Every node has a state:

• [opened] — TODO: Planned but not yet started
• [closed] — DONE: Completed, blocked, or no longer needed

Node Types

🤖 AI Integration

VIZVIBE.md — AI Instructions

The VIZVIBE.md file provides instructions for AI assistants on how to maintain the trajectory. It includes:

• Graph structure guidelines
• Node state management (opened/closed)
• When to add, close, or delete nodes
• Relationship modeling (dependencies vs parallel work)

See the full guide: VIZVIBE.md

How It Works

1. AI reads vizvibe.mmd to understand project context
2. AI works on your tasks
3. AI updates the trajectory with new nodes or state changes
4. Graph UI reflects changes in real-time (VS Code extension)

� Installation

Project Structure

viz-vibe/
├── vscode-extension/     # VS Code, Cursor, Antigravity
│   ├── src/
│   ├── package.json
│   └── ...
│
├── claude-code/          # Claude Code
│   ├── templates/
│   ├── install.sh
│   ├── uninstall.sh
│   └── update.sh
│
├── mcp-server/           # MCP Server (optional)
│
├── VIZVIBE.md            # AI instructions (shared)
└── README.md

Build VS Code Extension from Source

# Clone the repository
git clone https://github.com/NamHyeongKeol/viz-vibe.git
cd viz-vibe/vscode-extension

# Install dependencies
npm install

# Compile
npm run compile

# Package as .vsix
npx @vscode/vsce package

Development

cd vscode-extension

# Watch mode
npm run watch

# Debug: Press F5 in VS Code

🤝 Contributing

We welcome contributions! Whether it's:

• 🐛 Bug reports
• 💡 Feature suggestions
• 📝 Documentation improvements
• 🔧 Code contributions

Please open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License.