Vivian 
Vivian is an intelligent code analysis tool designed to visualize the codebase as an interactive graph, making it easier for both developers and AI agents to read, follow, and understand code structure. While it includes vulnerability management capabilities, its primary focus is on structural visualization and agentic interaction. It consists of a VS Code extension (Client) and a Python backend service (Server).
Inspiration
We wanted to solve the problem of navigating and understanding complex, large-scale codebases. Traditional file explorers don't show how everything connects, and standard AI coding assistants often lack deep structural context. We envisioned a tool that visually maps out your entire workspace and pairs it with an intelligent, agent-based AI to analyze architecture and detect vulnerabilities seamlessly.
The Cursor Approach (Text Search):
When you point tools like Cursor at a folder, they open every file and read the raw text. They chop all that text into small paragraphs and save them into a hidden search database. When you ask a question, it simply runs a massive, smart keyword search across those chopped-up text blocks to find the closest match. This approach completely loses the "big picture" architecture.
The Antigravity Approach (Summary Notes):
Other tools look at how your directories are organized. They read the files inside each folder and write plain-English summaries about what that specific folder does. Meaning auto-generating a giant "table of contents" for your whole project. When you ask a question, it reads its own summaries to figure out which folder has the answer. This is often too high-level and misses granular function-to-function dependencies.
The Vivian Approach (Graph Architecture):
We realized that code is inherently relational, not just a collection of text documents. Vivian solves this by mapping out the actual structural relationships between files, classes, and functions. Instead of brute-forcing context by stuffing massive chunks of raw text into a prompt (which is highly token-inefficient) or relying on vague folder summaries, Vivian feeds our AI agent an optimized structural graph. This makes our method dramatically more token-efficient, faster, and cheaper, while giving the AI a native understanding of how your entire architecture connects.
Demo
🎥 Watch the Demonstration Video
What it does
Vivian is an interactive VS Code extension that turns your codebase into a living, visual map:
- Structural Analysis: It maps out and displays the intricate relationships between files, classes, and functions across your entire workspace.
- Intuitive UI: It visualizes this data as an interactive graph, making it incredibly easy to track dependencies and follow code logic.
- Integrated AI Chatbot: Users can chat with an AI assistant that natively understands the graph structure, allowing for deep, context-aware codebase analysis.
- Security Scanning: It directly scans files and Git commit histories to detect vulnerabilities and potential security flaws right within the editor.
- Supported Languages: Out-of-the-box support for
TypeScript/JavaScript, Python, Go, Rust, Java, and C/C++/C#.
How we built it
We built Vivian using a modern, multi-layered tech stack:
- VS Code Extension: Built with TypeScript and the VS Code API for seamless editor integration.
- Graph Display: We used D3.js to render the interactive, force-directed code relationship graphs.
- AI Backend: A robust Python backend powered by FastAPI and WebSockets for real-time communication.
- Agents: We utilized LangGraph to orchestrate our AI agents.
- LLM: Powered by the Google Gemini API to handle deep reasoning and codebase analysis.
Prerequisites
Before running the setup scripts, please ensure you have the following installed on your machine:
- Node.js (required to build the VS Code extension)
- Python 3.8+ (required for the backend server)
Installation and Setup
The easiest way to install Vivian is directly from the VS Code Marketplace.
Alternatively, if you'd like to install this from Github, run the following commands in your terminal after cloning the repo:
1. Setup Client (VS Code Extension)
npm install
npm run package
2. Setup Server (Python Backend)
cd Server
python3 -m venv venv
source venv/bin/activate # On Windows use `venv\Scripts\activate`
pip install -r ../requirements.txt
cd ..
Once the package is built:
- Open the Extensions view in VS Code (
Cmd+Shift+X or Ctrl+Shift+X).
- Click the
... (Views and More Actions) button at the top right of the Extensions panel.
- Select Install from VSIX...
- Choose the newly generated
.vsix file located in your project root directory.
How to Use
Once the extension is installed, you can launch Vivian's graph in several ways:
Click the Vivian button located in:
2. Command Palette
If you don't see the button, open the Command Palette (Cmd+Shift+P on Mac or Ctrl+Shift+P on Windows), type Vivian, and select Vivian: Open Graph.
3. AI Chat & Vulnerability Scan (vulnTab)
Vivian features a built-in AI assistant and vulnerability scanner accessible via the AI Chat and vulnTab sections. To enable these features, you must turn the Built-in AI toggle on.
Accessing Settings:
Click the Settings gear icon / tab in the Vivian interface to open settings.
Providing the Gemini API Key:
Input your Google Gemini API key to activate reasoning capabilities, project-wide scans, and vulnerability checks in the vulnTab.
4. MCP Server Integration
Vivian MCP Server Integration provides powerful tools to external agents:
get_workspace_graph: Retrieves the cached Vivian knowledge graph. Requires a prior scan from the Vivian panel.get_project_stats: Get a quick overview of lines of code, file counts, and language distribution.get_file_details: Reads the literal text of a file utilizing Vivian's existing robust file-reading utilities.find_symbol: Searches Vivian's parsed graph nodes (functions, classes, interfaces, records, etc.) for a specific name or text.get_callers: Finds all files and functions that call a specific function id across your entire repository.
[!NOTE]
Prerequisite: Launch your graph first.
Vivian's MCP tools read from a pre-built cache.
Open VS Code and press Cmd+Shift+P (or Ctrl+Shift+P).
Search for and run the command: Vivian: Open MCP Setup Instructions or click on:
Follow the next few steps detailed in the panel.
Project Structure
Vivian/
├── Client/ # VS Code Extension (TypeScript)
│ └── src/ # Extension source code
├── Server/ # Python Backend (FastAPI / WebSockets)
│ ├── core/ # Core business logic and LLM agents
│ ├── handlers/ # Request and WebSocket handlers
│ ├── sidecar.py/ # Server entry point
│ └── mcp.py # MCP entry point for user agents
├── package.json # Extension manifest and dependencies
└── README.md
Credits
