ContextLens Docs

Introduction

ContextLens is an AI context layer for your codebase. It captures the why behind every change — diffs, AI interactions, decisions — and exposes them to any MCP-compatible AI client.

Without ContextLens, every AI session starts cold: the model re-reads files, re-derives intent, repeats work. With ContextLens, your AI client can search_context, explain_diff, and summarize_episode against a structured, persistent store of your development history.

Installation

VS Code Extension

Install from the VS Code Marketplace:

$ code --install-extension Noventra-Labs.contextlens
# or search "ContextLens" in the Extensions panel

MCP Bridge (npm)

$ npm install -g @contextlens/cli
$ npx @contextlens/cli --version
1.0.0

Requirements

• VS Code 1.85+ or Node.js 18+ (for CLI-only mode)
• Loopback port 3012 available
• For cloud sync: a Firebase project + Gemini API key

Firebase & Gemini Setup

ContextLens uses Firebase for cloud synchronization and Gemini/Vertex AI for semantic embeddings and intent summaries.

1. Configure Firebase Cloud

Follow these steps to initialize your Firebase project:

1. Go to the Firebase Console and create a new project.
2. Enable Firestore Database in your project.
3. Enable Firebase Authentication and activate the Anonymous or Email/Password provider.
4. Retrieve your project credentials from the Project Settings and add them to your .contextlens.json configuration file.

2. Store Gemini API Key

Embeddings and semantic search require a Gemini API key. Setup options:

• VS Code: Run the command ContextLens: Store Gemini API Key from the Command Palette and paste your key. This caches it securely in your OS Keychain using VS Code Secret Storage.
• CLI Environment: Export the environment variable in your terminal:

  export GEMINI_API_KEY="your-api-key-here"

Quick start

1. Install the VS Code extension.
2. Open a workspace. Watch the status bar for the active episode indicator.
3. Run ContextLens: Auto-Setup MCP in AI Clients from the Command Palette.
   > ContextLens: Auto

   ContextLens: Auto-Setup MCP in AI Clients Configure Claude, Cursor, Gemini automatically

   ContextLens: Start Episode Open a new context tracking episode
4. Open Claude Desktop, Cursor, or your preferred MCP client.
5. Ask: "Explain the changes in the latest episode" — ContextLens answers with real context.

Supported MCP clients

Episodes

An episode is a logical unit of work — a feature, bugfix, or refactor — bounded by explicit start and close calls. Every artifact produced inside an episode (file edits, git commits, AI calls, terminal commands, TODOs) is associated with it.

// Initialize connection to ContextLens local MCP bridge
const mcp = new MCPClient({ transport: "stdio" });

// Start
await mcp.call("start_episode", { title: "Ship OAuth" });

// ... do work ...

// Close
await mcp.call("close_episode", { summary: "Adds Google + GitHub providers" });

Watchers

Autonomous watchers hook into the editor lifecycle and capture context without explicit user action:

• File watcher — diffs on save, scoped to the active episode.
• Selection watcher — captures active text selections for downstream summarization.
• Terminal watcher — records command + output, classified by exit status.
• TODO watcher — scans for TODO/FIXME/Issue #… markers.

Watchers are configured in your global or workspace-specific .contextlens.json configuration file:

// .contextlens.json
{
  "watchers": {
    "file": true,
    "selection": true,
    "terminal": false,
    "todo": true
  }
}

Sync engine

The sync engine pushes cached local episodes to Firestore, handling auth headers, conflict resolution, and offline modes. Sync is opt-in: if you disable it, ContextLens stays fully local.

// .contextlens.json
{
  "sync": {
    "enabled": true,
    "projectId": "your-firebase-project",
    "interval": "5m"
  }
}

Offline & Merge Strategy: When offline, ContextLens writes files, diffs, and AI transactions directly to a local SQLite store. When the network is re-established, the sync engine automatically performs a batch synchronization. Conflict resolution uses a last-write-wins (timestamp-based) strategy at the individual transaction level, ensuring your cloud dashboard stays updated without dropping local contributions.

CLI install

$ npm install -g @contextlens/cli
$ contextlens --help

Commands

Security

• Rotating tokens — 30-minute TTL with a 1-minute grace window.
• Loopback binding — the bridge exposes 127.0.0.1 only.
• Token bucket — per-client rate limiting with burst protection.
• Schema validation — every tool call validated against an explicit JSON schema before execution.
• Secret storage — third-party API keys live in VS Code Secrets (OS keychain).

Troubleshooting

MCP Bridge fails to start

$ npx @contextlens/cli mcp doctor
✘ port 3012 in use — another MCP server is bound
fix: stop the conflicting process or set CONTEXTLENS_PORT=3013

AI client can't see tools

1. Confirm the bridge is healthy: contextlens mcp doctor.
2. Re-run ContextLens: Auto-Setup MCP in AI Clients from the VS Code palette.
3. Restart the AI client.

MCP Tools Reference

ContextLens exposes 9 primary tools for AI clients to inspect and write developer context. Use the interactive MCP Explorer to view detailed JSON schemas and example requests.

Tool Name	Parameters	Description
get_status	None	Returns bridge health, version, uptime, and active primitives counts.
start_episode	title (required)	Opens a new episode and binds it to the current workspace.
close_episode	summary (optional)	Closes the active episode with an optional intent summary.
log_ai_call	prompt, response, model	Records prompt/response pairs inside the active episode.
explain_diff	ref (default: HEAD)	Summarizes a git diff in plain English with file-level impact.
search_context	query (required), limit	Performs a semantic query across episodes, diffs, and AI logs.
get_episode_details	id (required)	Returns full payload details for a single episode by ID.
get_recent_episodes	limit	Lists recent episodes in the active workspace.
explain_past_changes	path (required)	Provides a natural-language audit of historical edits to a path.

MCP Resources Reference

Resources represent read-only context structures that AI clients can load directly as text documents.

URI Template	Kind	Description
workspace://current	Workspace	Current workspace metadata, active episode ID, and tracking state.
workspace://git-diff	Git	The combined staged and unstaged diff for the current branch.
workspace://episodes	Episodes	List of recent episodes with timestamps and summaries.
workspace://diagnostics	Diagnostics	Active problems, errors, and warning markers in the workspace.
workspace://symbols	Workspace	Indexed symbols, functions, and classes across the codebase.

MCP Prompts Reference

Prompts are reusable templates for guiding AIs through common software engineering flows.

Prompt Name	Category	Description
explain_diff	Review	Guides the AI to explain a git diff with focus on risk assessment.
review_code	Review	Generates a structured review against the intent of the active episode.
generate_tests	Test	Generates unit or integration tests for the current code path.
security_audit	Security	Performs threat-modeling and finds vulnerabilities in a given file.
summarize_episode	Episodes	Creates a concise recap of all work done inside the current episode.

Edit this page on GitHub