The AI context layer for your codebase.
Track coding intent, capture AI interactions, and expose your development history to any MCP-compatible AI client.
Installation · Features · Quick Start · Architecture · Documentation · Contributing
Warning
ContextLens is under active development. Some features are in preview and may change without notice.
Every coding session generates context that AI tools lose between conversations. ContextLens captures the why behind every change — diffs, AI interactions, decisions — and makes it available to any AI client through the Model Context Protocol (MCP).
Without ContextLens: Each AI session starts from scratch, re-analyzing your code. With ContextLens: AI tools access your full development history, past decisions, and project context.
- Organize work into logical episodes (features, bugfixes, refactors)
- Automatically capture diffs and AI interactions
- Build a semantic history of your project
- 9 Tools: Status, episodes, AI logging, diff explanation, context search
- 5 Resources: Workspace state, git diff, episodes, diagnostics, symbols
- 5 Prompts: Code review, test generation, security audit, diff explanation
- Works with Claude Desktop, Cursor, Antigravity IDE, Gemini CLI, and more
- Rotating authentication tokens (30-min TTL)
- Per-client rate limiting with burst protection
- Input validation on all tool calls
- Local-only binding (127.0.0.1)
- Visual timeline of project progress
- AI-generated PR descriptions and impact assessments
- Branch-level analysis
| Client | Status | Setup |
|---|---|---|
| Claude Desktop | ✅ Supported | Auto-setup or manual |
| Cursor | ✅ Supported | Auto-setup or manual |
| Antigravity IDE | ✅ Supported | Manual config |
| VS Code Agent | ✅ Built-in | Automatic |
| Gemini CLI | ✅ Supported | Manual config |
| OpenAI Agents SDK | ✅ Supported | Python integration |
# From VS Code Marketplace
ext install Noventra-Labs.contextlensOr search "ContextLens" in the VS Code Extensions panel.
npm install -g @contextlens/mcp- Install the VS Code extension
- Open Command Palette → ContextLens: Auto-Setup MCP in AI Clients
- Done! Your AI client can now access ContextLens tools.
Add to your AI client's MCP configuration:
{
"contextlens": {
"command": "node",
"args": ["/path/to/mcp-bridge.js"]
}
}Use ContextLens: Copy MCP Configuration to get the correct path.
The canonical ContextLens flow is: install → sign in → start an episode → code with your AI → close the episode → review context.
Ask your AI client:
"Use the start_episode tool to begin tracking my work on the login feature"
Or run the ContextLens: New Episode command in VS Code. Episodes are also auto-created when you switch branches.
ContextLens automatically captures:
- Git diffs (redacted, truncated to 6000 chars)
- Git commit messages
- File changes (workspace-relative paths)
- Branch switches (closing/opening episodes)
Ask your AI client:
"What changes have I made in this episode? Use explain_diff to analyze them."
AI actions — explain_diff, explain_past_changes, summarize_branch,
search_context — are manual triggers only. ContextLens never invokes an
AI model automatically, so you control AI cost.
"Search my past episodes for anything related to authentication using search_context"
| Captured automatically | Manual (AI-triggered) actions |
|---|---|
| Diffs, commits, file saves, branch switches | log_ai_call, explain_diff, explain_past_changes, search_context |
| Paused with ContextLens: Pause / Resume Capture | Always opt-in via your AI client |
- Local only: diffs and AI prompts are redacted before they leave the
machine; the offline sync queue (
cl_queue.json) is local to VS Code. - Uploaded (after sign-in): redacted episode metadata, diff summaries, and AI prompt/response text are synced to your authenticated Firebase project. See Privacy.
┌─────────────────────┐ ┌─────────────────────────────────┐
│ AI Client │ │ VS Code Extension │
│ (Claude, Cursor) │ │ │
└────────┬────────────┘ │ ┌───────────────────────────┐ │
│ stdio JSON-RPC │ │ ToolRegistry (9 tools) │ │
▼ │ ├───────────────────────────┤ │
┌────────┴────────────┐ │ │ Resources (5 URIs) │ │
│ mcp-bridge.js │◄───HTTP─│ ├───────────────────────────┤ │
│ (MCP Server) │ :3012 │ │ Prompts (5 templates) │ │
└─────────────────────┘ │ ├───────────────────────────┤ │
│ │ Security Layer │ │
│ │ ├── TokenManager │ │
│ │ ├── RateLimiter │ │
│ │ └── InputValidator │ │
│ └───────────────────────────┘ │
└─────────────────────────────────┘
| Component | Path | Description |
|---|---|---|
| VS Code Extension | /vscode-extension |
Primary client with MCP server |
| MCP Implementation | /vscode-extension/src/mcp/ |
Tools, resources, prompts, security |
| MCP Bridge | /vscode-extension/mcp-bridge.js |
stdio JSON-RPC bridge for AI clients |
| Web Dashboard | /contextlens-dashboard |
React-based visual interface |
| Backend | /src |
Firebase Cloud Functions + Firestore |
| Documentation | /docs |
Architecture, API, tutorials |
| Document | Description |
|---|---|
| Getting Started | Installation and first steps |
| Architecture | System design and data flow |
| Security | Authentication, rate limiting, error codes |
| Examples | Client configuration examples |
| API Reference | Tools, resources, prompts reference |
| Data Model | Episode lifecycle, fields, sync & edge cases |
| Privacy Policy | How ContextLens handles codebase data and secrets |
| Troubleshooting | Common issues and solutions |
| FAQ | Frequently asked questions |
We welcome contributions! See CONTRIBUTING.md for:
- Development setup
- Branch naming and commit conventions
- How to add new MCP tools and resources
- Testing requirements
Found a vulnerability? Please see SECURITY.md for responsible disclosure.
See ROADMAP.md for planned features and milestones.
This project is licensed under the MIT License — see LICENSE for details.
Built with ❤️ by Noventra Labs