🚀 About

⚡ You don't need to read any documentation. Your AI handles everything — from setup to daily management.

Just pass the message below to your AI agent.

Read this link and set up vizvibe to analyze my project, not the example: https://github.com/NamHyeongKeol/viz-vibe

Whatever vibe coding tool you use, your AI will generate a vizvibe.mmd file in your project root. You just review the result.

The vizvibe.mmd file contains your project's graph — your trajectory, decisions, blockers, and TODOs. Your AI will manage this file alongside you, updating it as your project evolves.

Our mission: Make even the context file itself manageable through vibes. No manual editing, no learning curve — just seamless collaboration.

⚠️ Note: Viz Vibe does NOT visualize your repository's code structure or how your project works. Instead, it visualizes your work trajectory — what you've done, what's planned, your decisions, blockers, and the path of your coding journey as a graph.

🚀 Getting Started

For All Vibe Coders

Just pass the message below to your AI agent.

Read this link and set up vizvibe in my language to analyze my project, not the example: https://github.com/NamHyeongKeol/viz-vibe

For Claude Code Users

1. Install VizVibe Globally

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

What gets installed?

Location	Files
~/.vizvibe/	CLI (bin/vizvibe), browser viewer (bin/vizvibe-server.js), hook scripts, templates
~/.claude/	hooks/read-vizvibe.js, hooks/update-vizvibe.js, hooks/VIZVIBE.md, skills/vizvibe/SKILL.md, settings.json (merged)

2. Initialize in your Project

cd your-project
vizvibe init

What gets created?

• vizvibe.mmd — Your trajectory graph file
• .claude/hooks/ — Local hook scripts for Claude Code
• .claude/settings.json — Hook configuration (merges with existing settings if present)
• .vizvibe-state.json added to .gitignore — Runtime state (auto-generated)

3. View in Browser

vizvibe view

Opens at http://localhost:5125. Copy the setup prompt from the overlay.

4. Start Claude Code

claude

Paste: "Please setup vizvibe for this project. Write the trajectory in my language."

CLI Commands

Command	Description
vizvibe init	Initialize vizvibe.mmd
vizvibe view	Open in browser (port 5125)
vizvibe uninstall	Uninstall Viz Vibe and clean up config
vizvibe help	Show help

Uninstall:

You can uninstall anytime via CLI:

vizvibe uninstall

Alternatively, use the one-liner:

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

For Cursor / Antigravity / VS Code Users

1. Install Extension

Search "Viz Vibe" in the Extensions panel (`Cmd+Shift+X`) and Install Extension.

Alternative: 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

2. Initialize Project

When the "Initialize Viz Vibe?" prompt appears, click Yes.

3. Setup with AI

Open `vizvibe.mmd` — copy the setup prompt and ask your AI.

⚠️ Note: IDE-based AI assistants don't support automatic trajectory updates. When you want to update the graph, simply ask your AI: "Please update vizvibe.mmd with what we've done."

📁 File Format

Viz Vibe uses Mermaid flowchart syntax for trajectories:

⚠️ For AI Assistants: This is a FORMAT example only. Create the trajectory by analyzing the USER'S project (git history, README, conversation), NOT by copying this example.

flowchart TD
    %% === PROJECT GOALS ===
    %% Ultimate Goal: [Describe the user's project goal]

    %% === START ===
    %% @project_start [start, closed]
    project_start("Project Start<br/><sub>Brief description of what the<br/>project is about and its purpose</sub>")

    %% @ultimate_goal [end, opened]
    ultimate_goal("Project Goal<br/><sub>The main objective this project<br/>aims to achieve</sub>")

    %% === COMPLETED WORK ===
    %% @feature_a [ai-task, closed]
    feature_a("Feature A<br/><sub>Description of a completed feature<br/>or milestone in the project</sub>")

    %% @task_b [ai-task, closed]
    task_b("Task B<br/><sub>Another completed task with<br/>details about what was done</sub>")

    %% === FUTURE WORK ===
    %% @future_task [ai-task, opened]
    future_task("Future Task<br/><sub>Planned work that hasn't<br/>been started yet</sub>")

    %% === CONNECTIONS ===
    project_start --> feature_a
    feature_a --> task_b
    feature_a --> future_task
    future_task -.-> ultimate_goal

    %% === RECENT WORK HIGHLIGHT ===
    subgraph recent [RECENT]
        task_b
    end

    %% === STYLES ===
    %% Closed tasks (soft purple)
    style project_start fill:#1a1a2e,stroke:#a78bfa,color:#c4b5fd,stroke-width:1px
    style feature_a fill:#1a1a2e,stroke:#a78bfa,color:#c4b5fd,stroke-width:1px

    %% Recent node (highlighted purple)
    style task_b fill:#2d1f4e,stroke:#c084fc,color:#e9d5ff,stroke-width:2px

    %% Recent subgraph (dashed border)
    style recent fill:transparent,stroke:#c084fc,color:#c084fc,stroke-width:2px,stroke-dasharray:5 5

    %% Open tasks (soft green)
    style ultimate_goal fill:#1a1a2e,stroke:#4ade80,color:#86efac,stroke-width:1px
    style future_task fill:#1a1a2e,stroke:#4ade80,color:#86efac,stroke-width:1px

Node States

Every node has a state:

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

🤖 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)

🤝 Contributing

We welcome contributions! Whether it's:

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

Please open an issue or submit a pull request.

💡 Why We Built This

As AI advances, it's becoming harder for humans to keep up with the context of their AI's work during vibe coding. The challenge is that someone — both humans and AIs — still needs to understand and manage what the AI is doing. That's why we started this project.

Additionally, summarizing your project's state as a graph perfectly solves the context overload problem that occurs when AI conversations grow too long. What's the best way to maintain context when starting a new conversation without copy-pasting all previous history? Just use Viz Vibe.

📄 License

This project is licensed under the MIT License.