Vibe-Graph

A local-first neural OS for software projects, where specs, code, and collaboration live in one evolving system—with Git as the fossil record.

Vibe-Graph maintains a living SourceCodeGraph that captures structure, relationships, and historical vibes (human + machine intents). It scans your codebase, detects cross-file references, and provides interactive visualization—all running locally.

Quick Start

# Install
cargo install vibe-graph-cli

# Analyze your codebase
cd your-project
vg sync

# Build the dependency graph
vg graph

# Launch interactive visualization
vg serve
# Open http://localhost:3000

# Start MCP Server for AI Agents
vg serve --mcp

Features

• 🤖 Model Context Protocol (MCP) — Native MCP server for AI agents to semantically explore code
• ⚡ GPU Acceleration — WebGPU-powered Barnes-Hut layout for large graphs (>10k nodes)
• 🔍 Auto-detection — Recognizes single repos, multi-repo workspaces, or plain directories
• 📊 SourceCodeGraph — Builds a graph of files, directories, and cross-file references
• 🌐 Interactive Visualization — D3.js or embedded egui/WASM graph explorer
• 💾 Local-first Persistence — All data stored in .self/ folder, works offline
• 📝 Documentation Generation — Export markdown or JSON from your codebase structure
• 🐙 GitHub Integration — Clone and analyze entire organizations

Installation

From crates.io (recommended)

cargo install vibe-graph-cli

From source

git clone https://github.com/pinsky-three/vibe-graph
cd vibe-graph
make build
# Binary at: target/release/vg

Commands

Sync Options:

• --cache — Clone to global cache instead of current directory
• --ignore <repo> — Skip specific repos when syncing an org
• --snapshot — Create timestamped snapshot

Run vg --help for full command reference.

🤖 Model Context Protocol (MCP)

Vibe-Graph acts as a Semantic Intelligence Layer for your AI agents (Claude, Cursor, etc.). By running the MCP server, you give your agents "eyes" to see the codebase structure.

Capabilities:

• Gateway Mode: Serve multiple local projects from a single endpoint.
• Impact Analysis: Ask "what breaks if I touch User.rs?" -> Returns sorted list of dependents (ranked by centrality).
• Semantic Search: Find files by concept/module rather than just regex.
• Context Awareness: Get the "neighborhood" of a file (imports + usage) in one shot.

Graph Visualization

The serve command provides an interactive force-directed graph with REST + WebSocket API:

vg sync && vg serve

Features:

• 🎨 egui WASM visualization — Interactive graph explorer with pan/zoom
• ⚡ GPU Layout — High-performance WebGPU compute for massive graphs
• 📡 Live git status — Change indicators on modified files (auto-refresh via WebSocket)
• 📊 PageRank Sizing — Nodes sized by structural importance
• 🔌 REST API — Programmatic access to graph data

API Endpoints

Build Variants

Architecture

vibe-graph/
├── crates/
│   ├── vibe-graph-core        # Domain model: graphs, nodes, edges, references
│   ├── vibe-graph-automaton   # Temporal state evolution & rule-driven automaton
│   ├── vibe-graph-cli         # CLI entry point (vg command)
│   ├── vibe-graph-api         # REST + WebSocket API (Axum-based)
│   ├── vibe-graph-mcp         # Model Context Protocol server implementation
│   ├── vibe-graph-viz         # egui/WASM visualization
│   ├── vibe-graph-git         # Git status and fossilization
│   └── ...                    # Additional crates (ssot, semantic, llmca, etc.)
└── frontend/                  # TypeScript/Vite host for WASM visualization

Graph Automaton (vibe-graph-automaton)

The automaton crate enables temporal state evolution on graphs—a foundation for "vibe coding" where code structure evolves over time via rule-driven transitions.

use vibe_graph_automaton::{GraphAutomaton, Rule, StateData, TemporalGraph};

// Each node tracks: history: Vec<(rule, state)>, current: (rule, state)
let mut automaton = GraphAutomaton::new(temporal_graph)
    .with_rule(Arc::new(MyRule));

// Evolve the graph
automaton.tick()?;

Features:

• 🕰️ Temporal State — Each node maintains full transition history
• 🔄 Pluggable Rules — Implement Rule trait for custom evolution logic
• 🧠 LLM-Powered Rules — Use --features llm for AI-driven state transitions via Rig
• 🎮 Examples — Conway's Game of Life (deterministic & LLM-powered)

# Run Game of Life example
cargo run --example game_of_life -p vibe-graph-automaton

# LLM-powered version (requires API key)
export OPENAI_API_URL="https://openrouter.ai/api/v1"
export OPENAI_API_KEY="sk-or-..."
export OPENAI_MODEL_NAME="anthropic/claude-3.5-sonnet"
cargo run --example llm_game_of_life -p vibe-graph-automaton --features llm

The .self Folder

Analysis results persist in .self/:

.self/
├── manifest.json   # Workspace metadata
├── project.json    # Full analysis data
├── graph.json      # SourceCodeGraph with references
└── snapshots/      # Historical snapshots

Add .self/ to your .gitignore.

Configuration

Configuration is stored in ~/.config/vibe-graph/config.toml. Use vg config show to view.

Development

# First-time setup
make setup

# Development (two terminals)
make dev-api       # Terminal 1: API server on :3000
make dev-frontend  # Terminal 2: Vite dev server on :5173

# Or with tmux
make dev-all

# Run native egui app (for local debugging)
make ui-dev

Build Commands

make check        # Check all crates compile
make build        # Build minimal CLI (D3.js fallback)
make build-wasm   # Build WASM to frontend/public/wasm/
make build-full   # Full production build (frontend + CLI)

Quality

make test         # Run all tests
make lint         # Clippy
make fmt          # Format code
make ci           # Full CI checks (fmt + lint + test + typecheck)

Status

This is early-stage research code. Expect rapid iteration, incomplete features, and evolving abstractions. The core graph analysis and visualization are functional—use them to explore your codebases.

License

MIT

lib.rs:

Vibe-Graph Operations Layer

This crate provides a clean, typed API for all vibe-graph operations. It can be consumed by both the CLI and REST API, ensuring consistent behavior and type-safe interactions.

Architecture

The ops layer follows hexagonal architecture principles:

• Requests: Typed input DTOs for each operation
• Responses: Typed output DTOs with all relevant data
• OpsContext: The main service that executes operations

Usage

use vibe_graph_ops::{OpsContext, SyncRequest, Config};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = Config::load()?;
    let ctx = OpsContext::new(config);
    
    let request = SyncRequest::local(".");
    let response = ctx.sync(request).await?;
    
    println!("Synced {} repositories", response.project.repositories.len());
    Ok(())
}