Reservoir AI

Reservoir AI embeds a senior software architect directly into your editor. It analyzes your codebase, generates dependency-aware navigation maps, answers contextual questions with full project awareness, and autonomously diagnoses and rewrites broken code through a specialized four-stage self-healing pipeline.

Features

Context-Aware AI Chat

Streams responses through a Project Assistant that reads your navigation map, attached workspace files, uploaded documents, and compressed conversation history before answering. Every response is grounded in your actual codebase.

Automated Code Mapping

Scans your workspace in batches of 5 files, prompting the Navigation Mapper to write one precise sentence per file describing exported symbols, key functions, and how each file differs from similarly named ones. The resulting navigation_map.txt serves as shared context for all agents.

Self-Healing Pipeline

A four-stage autonomous repair system:

1. Root Coordinator - reads the navigation map and returns the exact files that need editing
2. Diagnostician - confirms whether a real bug exists before writing anything
3. Child Healer - rewrites the target file using all selected files as cross-context
4. Change Summarizer - diffs the original vs updated file and produces a 3-5 bullet summary

Supercharge Menu

Self-Healing Mode and Memory Mode live inside the lightning bolt input button.

Scaffold Insert

Every code block in the AI response has an Insert button that detects filenames from surrounding headings and generates PowerShell commands to write the full response to disk automatically.

File and Document Attachments

Attach workspace files via checklist or upload documents to a persistent SQLite knowledge base.

Persistent Memory

Store project preferences and context that the agent recalls across sessions.

Safety Guardrails

A line-count safety check blocks any heal output shorter than 60% of the original file. Administrative shell commands are detected and blocked before terminal execution.

Requirements

• Python 3.10+ installed and available on PATH
• An OpenRouter API key (free at openrouter.ai)

Dependencies are installed automatically on first activation. To install manually:

pip install agno python-dotenv

Getting Started

1. Install the extension from the VS Code Marketplace
2. Open a workspace folder in VS Code
3. Click the Reservoir AI icon in the Activity Bar
4. Go to Settings, API Key and enter your OpenRouter API key
5. Click Generate Map to index your codebase
6. Start chatting or enable Self-Healing Mode to let the agents fix your code autonomously

Architecture

Python Backend

• tree.py - Core engine managing all agents, chat streaming, and self-healing orchestration
• navi.py - Workspace scanner and navigation map generator
• memory.py - Reads, writes, and deletes persistent user memory entries
• documents_db.py - SQLite document store
• setup_check.py - Runs on activation and auto-installs missing dependencies

Frontend

• extension.js - VS Code provider registering the sidebar webview and spawning Python subprocesses
• state.js - Webview state management
• render.js - Markdown renderer with per-block Insert, Run, and Copy buttons
• events.js - Event wiring with global delegation
• message-handler.js - Handles streamed output and document lifecycle events
• utils.js - Scaffold command generation from AI responses

License

MIT (c) 2026 Daniel Pool