Vibe-Audit

Autonomous DOM Lifecycle Auditor -- built on the principles of the Kaggle 5-Day Gen AI Intensive Course.

A multi-agent system that scans a JavaScript or TypeScript source file for unbalanced addEventListener calls, flags memory-leak vectors, and produces a validated patch via a Gemini LLM. Every output passes through a deterministic security handrail before it is surfaced.

---

Problem

DOM event listeners registered without a matching cleanup call are one of the most common memory leak vectors in long-running single-page applications. Each time a component mounts without calling removeEventListener on unmount, the listener and its closure are retained in memory indefinitely. Standard linters catch the most obvious cases but miss the framework-specific teardown patterns -- React's useEffect cleanup return, Vue's onUnmounted hook, and the AbortController signal pattern -- that account for the majority of leaks in modern codebases.

Vibe-Audit addresses this gap with a dedicated MCP tool that performs a structural scan of any source file and, when a leak is detected, delegates to an LLM-powered patching agent to generate a corrected version. Every generated patch is screened by a deterministic validation layer before it is returned.

---

Table of Contents

1. Architecture Overview
2. Execution Flow
3. Course Concept Mapping
4. Security Layers
5. Installation and Local Execution
6. Project Structure
7. Sample Pipeline Output
8. Demonstration Video
9. Roadmap

---

Architecture Overview

The system runs as two separate processes. The orchestrator process hosts the agent logic. The MCP server process hosts the diagnostic tool. They communicate over stdio using the JSON-RPC transport defined by the Model Context Protocol.

graph TB
    subgraph orchestrator["Orchestrator Process (src/orchestrator.ts)"]
        A["Auditor Agent\nrunAuditorAgent()"]
        R["Router\nrouterDecision()"]
        P["Patching Agent\nrunPatchingAgent()"]
        V["Validation Handrail\nrunValidationHandrail()"]

        A --> R
        R -- "requiresPatch = true" --> P
        R -- "requiresPatch = false" --> done1["Return PipelineContext"]
        P --> V
        V -- "passed = true" --> done2["Return PipelineContext"]
        V -- "passed = false" --> done3["Return PipelineContext (flagged)"]
    end

    subgraph mcp["MCP Server Process (src/index.ts)"]
        T["Tool: analyze_dom_lifecycles\n1. Sanitize filePath\n2. Read file\n3. Pattern scan\n4. Return CRITICAL or OK"]
    end

    subgraph gemini["External"]
        G["Gemini 2.5 Flash API"]
    end

    A -- "stdio JSON-RPC" --> T
    T -- "diagnostic string" --> A
    P -- "HTTPS" --> G
    G -- "raw patch text" --> P

---

Execution Flow

sequenceDiagram
    participant CLI
    participant Orchestrator
    participant MCPServer as MCP Server
    participant Gemini

    CLI->>Orchestrator: executeAuditPipeline(filePath, source)
    Orchestrator->>MCPServer: tools/call analyze_dom_lifecycles
    MCPServer-->>Orchestrator: "CRITICAL: Memory leak vector detected..."
    Orchestrator->>Orchestrator: routerDecision() -- requiresPatch = true
    Orchestrator->>Gemini: generateContent(structuredPrompt + source)
    Gemini-->>Orchestrator: patched source text
    Orchestrator->>Orchestrator: runValidationHandrail()
    alt validation passes
        Orchestrator-->>CLI: PipelineContext (validationResult.passed = true)
    else validation fails
        Orchestrator-->>CLI: PipelineContext (validationResult.passed = false, flaggedPatterns)
    end

---

Course Concept Mapping

Rubric Criterion	Course Day	Implementation	File
Agent / Multi-agent system (ADK)	Day 5	PerformanceOrchestrator is the ADK router. runAuditorAgent and runPatchingAgent are specialist agents with single responsibilities. State passes through an immutable PipelineContext object -- the ADK context-enrichment pattern.	src/orchestrator.ts
MCP Server	Day 5	McpServer with StdioServerTransport. Tool analyze_dom_lifecycles is registered with a Zod-validated filePath input. The orchestrator uses an adapter function so the mock and the live Client session share the same interface.	src/index.ts
Structured prompting	Day 2	buildPatchPrompt() produces a multi-section system prompt with explicit role, mandatory rules, absolute prohibitions, and an output contract. The prompt is separated from the invocation call so it can be versioned and tested independently.	src/orchestrator.ts
Security features	Day 4	Three independent layers: (1) API key pre-flight in constructor, (2) directory-traversal guard in MCP server via path.resolve and prefix check, (3) six-category regex scan of every LLM output before it is returned.	src/index.ts, src/orchestrator.ts
Deployability	Day 5	ESM project with type: module, strict tsconfig.json, single npm run build step. Launchable by any MCP host (Claude Desktop, Continue, ADK runtime) via a one-entry JSON config block.	package.json, tsconfig.json
Evaluation / Critic agent	Day 5	runValidationHandrail() is a pure synchronous function with no LLM dependency. It checks the generated patch against a defined safety rubric and returns a structured ValidationResult with a per-flag audit trail.	src/orchestrator.ts

---

Security Layers

Layer 1 -- API Key Pre-flight

Checked in the constructor before any object is instantiated. If GEMINI_API_KEY is absent or empty, the process throws immediately.

const apiKey = process.env.GEMINI_API_KEY;
if (!apiKey || apiKey.trim() === "") {
  throw new Error(
    "[FATAL] GEMINI_API_KEY environment variable is not set."
  );
}

Layer 2 -- Path Traversal Guard

Runs inside the MCP server before any file I/O. The resolved path must remain within PROJECT_ROOT. A trailing separator is appended before the prefix check to prevent sibling-directory collisions.

const resolved = path.resolve(PROJECT_ROOT, rawPath);
const rootWithSep = PROJECT_ROOT + path.sep;
if (!resolved.startsWith(rootWithSep) && resolved !== PROJECT_ROOT) {
  throw new Error("Path traversal attempt detected.");
}

Layer 3 -- Output Validation Handrail

Scans every LLM-generated patch with six regex categories. Any match fails the pipeline and returns a flagged ValidationResult without discarding the pipeline context.

Category	Detects
shell-exec	child_process, .exec(), .spawn()
eval-variant	eval(), new Function(), setTimeout("string")
filesystem-nuke	rm -rf, fs.unlinkSync, fs.rmdirSync
network-exfil	curl, wget, external fetch() calls
proto-pollution	__proto__, constructor.prototype mutations
env-exfiltration	process.env.* variable piped into a network call

Required logic anchors (patterns that must survive the patch, e.g. addEventListener) are checked separately. A missing anchor is treated as a validation failure.

---

Installation and Local Execution

Prerequisites

• Node.js 18 or later
• npm 9 or later
• A Gemini API key from Google AI Studio

---

Step 1 -- Clone

git clone https://github.com/your-username/vibe-audit.git
cd vibe-audit

Step 2 -- Install dependencies

npm install

Installs:

• @modelcontextprotocol/sdk -- MCP server runtime
• @google/generative-ai -- Gemini API client
• typescript, @types/node -- TypeScript toolchain

Step 3 -- Set the API key

# Linux / macOS
export GEMINI_API_KEY="your-key-here"

# Windows PowerShell
$env:GEMINI_API_KEY = "your-key-here"

For .env file support, install dotenv and add import 'dotenv/config' at the top of src/orchestrator.ts.

Step 4 -- Build

npm run build

Compiles src/ to dist/. The build has zero warnings under strict TypeScript settings.

Step 5 -- Run the MCP server standalone

npm start

The server writes its startup message to stderr and then waits for JSON-RPC messages on stdin.

Step 6 -- Run the orchestrator pipeline

# Against a leaky fixture
GEMINI_API_KEY="your-key" npx ts-node src/orchestrator.ts leaky.js

# Against a clean fixture
GEMINI_API_KEY="your-key" npx ts-node src/orchestrator.ts clean.js

Step 7 -- Integrate with Claude Desktop

Add the following to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vibe-audit": {
      "command": "node",
      "args": ["/absolute/path/to/vibe-audit/dist/index.js"]
    }
  }
}

Restart Claude Desktop. The analyze_dom_lifecycles tool will appear in the tool list.

---

Project Structure

vibe-audit/
├── src/
│   ├── index.ts          # MCP server -- analyze_dom_lifecycles tool
│   └── orchestrator.ts   # Multi-agent ADK pipeline
├── dist/                 # Compiled output (generated by tsc)
│   ├── index.js
│   └── orchestrator.js
├── leaky.js              # Test fixture: addEventListener with no cleanup
├── clean.js              # Test fixture: addEventListener with removeEventListener
├── package.json
├── tsconfig.json
└── README.md

---

Sample Pipeline Output

Run against leaky.js:

[Orchestrator] Initialized. Environment pre-flight: PASSED

[Auditor Agent] Invoking MCP tool: analyze_dom_lifecycles
[Auditor Agent] Diagnostic: CRITICAL: Memory leak vector detected -- addEventListener
                is used but no cleanup was found.

[Router] Requires patch: YES -- handing off to Patching Agent

[Patching Agent] Constructing structured repair prompt
[Patching Agent] Prompt built. Invoking Gemini LLM
[Patching Agent] LLM response received.

[Validation] Running safety scan on LLM-generated patch
[Validation] VALIDATION PASSED: Patch is clean. No dangerous patterns.
             All core logic anchors preserved.

---

Demonstration Video

A walkthrough video showing Vibe-Audit deployed end-to-end using the Antigravity IDE is in production. The video will cover:

• Starting the MCP server and orchestrator from a cold clone using Antigravity agentic scaffolding
• Live pipeline execution with Auditor, Patcher, and Validator log output
• Claude Desktop MCP tool integration auditing a real React component

Link will be added here when published.

---

Roadmap

• [ ] Replace mock MCP adapter with a live @modelcontextprotocol/sdk Client session
• [ ] Add dotenv support
• [ ] Expand diagnostic patterns: Vue 3 onUnmounted, Svelte onDestroy, RxJS unsubscribe
• [ ] GitHub Actions CI with fixture-based tests
• [ ] Docker image for isolated server deployment
• [ ] Web UI for pipeline run history and diff view

---

License

MIT 2026 -- built during the Kaggle 5-Day Gen AI Intensive.

TANUSH Bhootra ✨