Gently - AI Coding Agent for VS Code

Your affordable, local-first AI coding assistant — powered by DeepSeek, Claude, OPENAI GPT, and more via OpenRouter.

✨ Key Features

🤖 AI-Powered Coding Assistant

• Smart Chat Interface: Natural conversation with AI about your code
• Code Generation: Generate, explain, and refactor code with context awareness
• Streaming Responses: Real-time AI responses for instant feedback
• BYOK (Bring Your Own Key): Use your own OpenRouter API key — no account required

🛡️ Guardian System — Proactive Code Health

• Automated Analysis: Background scanning for code quality issues
• Multi-Analyzer Architecture:
  • Code Duplication Detection
  • Dead Code Identification
  • Security Pattern Analysis
  • Performance Issue Detection
  • Architectural Drift Monitoring
• Quick Fixes: Automated suggestions for common issues
• Configurable: Adjust severity thresholds, analysis intervals, and issue types

🧠 Advanced Retrieval & Memory

• Hybrid Search: Combines BM25 (lexical) and HNSW (semantic) search
• Cross-Encoder Reranking: Precision-optimized result ranking
• Persistent Memory: Context and decisions preserved across sessions
• Memory Bank: Structured storage for project knowledge

🔌 Extensible Plugin System

• Built-in Plugins: Git, Docker integration
• Custom Plugins: Extend functionality with your own plugins
• Mode System: Switch between Code and Architect modes

⚡ Performance Optimized

• Lazy Loading: Components loaded on demand
• Intelligent Caching: LRU cache for embeddings and search results
• Session Management: Optimized memory usage for long sessions

🚀 Quick Start

1. Installation

From VS Code Marketplace:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Gently"
4. Click Install

From VSIX:

code --install-extension gently-0.5.1.vsix

2. Configuration

1. Get an OpenRouter API Key:

   • Visit openrouter.ai
   • Create an account and generate an API key

2. Configure in VS Code:

   • Click the Gently icon in the Activity Bar
   • Click "Configure API Key"
   • Enter your OpenRouter API key

3. Select a Model (optional):

   • Default: deepseek/deepseek-chat
   • Alternatives: anthropic/claude-3.5-sonnet, openai/gpt-4o

3. Start Using

# Open chat
Ctrl+Shift+P → "Open Gently Chat"

# Example prompts:
"Explain this function"
"How can I optimize this code?"
"Write a unit test for this class"
"What does this error mean?"
"Refactor this to use async/await"

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                    VS Code Extension Host                    │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Agent      │  │   Guardian   │  │    Mode      │      │
│  │   Manager    │  │   Service    │  │   Service    │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                 │                 │               │
│  ┌──────▼─────────────────▼─────────────────▼───────┐      │
│  │              DI Container (ServiceProvider)        │      │
│  └──────┬─────────────────┬─────────────────┬───────┘      │
│         │                 │                 │               │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐      │
│  │    Tools     │  │   Retrieval  │  │    Memory    │      │
│  │   Registry   │  │   System     │  │   Manager    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │    Chat      │  │   Guardian   │  │   Plugin     │      │
│  │   Webview    │  │   Webview    │  │   Manager    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘

Core Components

Retrieval Pipeline

User Query
    │
    ▼
┌─────────────────────────────────────────────┐
│  Stage 1: Parallel Coarse Retrieval         │
│  ┌─────────────┐    ┌─────────────┐         │
│  │   HNSW      │    │    BM25     │         │
│  │  (Dense)    │    │  (Lexical)  │         │
│  └──────┬──────┘    └──────┬──────┘         │
└─────────┼─────────────────┼────────────────┘
          │                 │
          ▼                 ▼
┌─────────────────────────────────────────────┐
│  Stage 2: Reciprocal Rank Fusion (RRF)      │
│  Weighted combination of dense + lexical    │
└─────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────┐
│  Stage 3: Cross-Encoder Reranking           │
│  Precision optimization with bge-reranker   │
└─────────────────────────────────────────────┘
          │
          ▼
     Final Results

⚙️ Configuration

VS Code Settings

Guardian Issue Types

• code_duplication: Detects repeated code patterns
• dead_code: Identifies unused code
• architectural_drift: Monitors architectural consistency
• security_pattern: Scans for security vulnerabilities
• performance_issue: Detects performance bottlenecks
• maintainability: Code maintainability analysis
• test_coverage: Test coverage gaps

🛠️ Development

Prerequisites

• Node.js 18+
• VS Code 1.85+
• TypeScript 5.3+

Setup

# Clone repository
git clone https://github.com/gently-ai/gently-vscode-extension.git
cd gently-vscode-extension

# Install dependencies
npm install

# Build extension
npm run build

# Run tests
npm run test:unit
npm run test:guardian
npm run test:toolcall

# Watch mode for development
npm run watch

Project Structure

src/
├── agent/                 # AI Agent system
│   ├── agentManager/      # Agent orchestration
│   ├── memory/            # Memory & context management
│   ├── retrieval/         # Hybrid search system
│   ├── tools/             # Tool registry & implementations
│   ├── validation/        # Code validation
│   └── planning/          # Task planning
├── guardian/              # Code health monitoring
│   ├── analyzers/         # Issue detection analyzers
│   ├── views/             # Guardian webview
│   └── tests/             # Guardian tests
├── views/                 # Webview providers
│   └── chat/              # Chat interface
├── plugins/               # Plugin system
├── modes/                 # AI mode system
├── session/               # Session management
├── performance/           # Performance optimization
├── commands/              # Command handlers
└── utils/                 # Utility functions

Testing

# Unit tests
npm run test:unit

# Guardian tests
npm run test:guardian

# ToolCall tests
npm run test:toolcall

# All tests with coverage
npm run test:toolcall:coverage

# Watch mode
npm run test:toolcall:watch

Building

# Production build
npm run build

# Package for distribution
npm run package

🔒 Privacy & Security

• Direct Communication: All API calls go directly to OpenRouter
• Encrypted Communication: HTTPS for all API calls
• No Code Storage: Your code is never stored on external servers
• Local Settings: API keys stored securely in VS Code Secret Storage
• Guardian Security: Built-in security pattern analysis

📊 Performance

Benchmarks

Optimization Features

• Lazy Loading: Components loaded on demand
• Embedding Cache: LRU cache for embeddings
• Incremental Indexing: Only changed files re-indexed
• Session Optimization: Memory management for long sessions

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• TypeScript strict mode
• ESLint for linting
• Vitest for testing
• Conventional commits

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

• Email: info@illiria.eu
• GitHub Issues: Report a bug
• Documentation: Wiki

🙏 Acknowledgments

• OpenRouter for AI model access
• HNSWLib for vector search
• Transformers.js for embeddings
• Tree-sitter for AST parsing

Made with ❤️ by the Gently Team