╭─────────────────────────────────────────────────────────────────╮
│                                                                 │
│    ╭───╮     ╭─────╮    ╭───╮    ╭───╮                        │
│   ╱     ╲   ╱       ╲  ╱     ╲  ╱     ╲                       │
│  ╱  VS   ╲ ╱  ConnAI ╲╱   AI   ╲╱ Web   ╲                      │
│  ╲ Code  ╱ ╲ Protocol╱╲ Bridge ╱╲Browser╱                      │
│   ╲_____╱   ╲_______╱  ╲_____╱  ╲_____╱                       │
│       ╲         │         │         ╱                          │
│        ╲________│_________│________╱                           │
│                 │    🔗   │                                    │
│               Real-time Bridge                                 │
│                                                                 │
╰─────────────────────────────────────────────────────────────────╯

• Multi-package workspace with pnpm workspaces
• Shared protocol (@connai/protocol) for cross-package communication
• Unified build system and development workflow
• Cross-package type safety and dependency management

• Standardized ConnAI Protocol for editor-agnostic communication
• HTTP RESTful API with auto-discovery and health monitoring
• Smart port management with automatic detection (6718-6817, 8080-8090)
• Auto-connect functionality - zero configuration required
• WebSocket support (coming soon) for real-time push notifications

• Universal web integration - works on any website
• Smart input detection - type # in any input field to trigger
• Context menu integration with rich UI and visual feedback
• Auto-connect to VS Code with intelligent port scanning
• Background connection management with health checks and reconnection
• Manual server configuration when auto-detection fails

• HTTP protocol server on configurable ports
• Multi-workspace support with automatic port assignment
• Real-time context extraction from active editor
• Rich context types: focused file, selected text, open tabs, problems, file tree
• File operations and workspace management
• Health monitoring and diagnostic endpoints

• Token-aware processing for AI model optimization
• Smart file filtering with .gitignore support
• Metadata enrichment with file types and structure analysis
• Configurable context depth and scope control

ConnAI is built as a modern Monorepo with four main packages:

📦 ConnAI Monorepo
├── 🔌 protocol/          # Core protocol layer & communication contracts
├── 🖥️ vscode-extension/  # VS Code integration & HTTP server
├── 🌐 browser-extension/ # Browser extension (Chrome/Edge) with React UI
└── 📦 shared/           # Shared utilities, types & constants

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  🌐 Browser     │    │  🔗 ConnAI      │    │  🖥️ VS Code    │
│   Extension     │◄──►│   Protocol      │◄──►│   Extension     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
   🔍 Auto-discovery        🚀 HTTP/WebSocket       📄 Context extraction
   🔄 Smart reconnect       ⚡ Health monitoring      🗂️ File operations
   🎨 User interface        🛡️ Error handling        📊 Workspace info
   📝 Input detection       🔧 Port management       🏗️ Multi-workspace

The heart of ConnAI is its standardized protocol layer that provides:

• Editor-agnostic interface for future extensibility (Cursor, WebStorm, etc.)
• Type-safe message contracts for reliable communication
• Transport abstraction supporting HTTP and WebSocket
• Capability negotiation for feature discovery
• Error handling with detailed diagnostics and retry logic

// Example protocol usage
import { createProtocolClient } from '@connai/protocol';

const client = createProtocolClient({
  serverUrl: 'http://localhost:6797',
  timeout: 10000,
  maxReconnectAttempts: 5
});

await client.connect();
const context = await client.sendRequest('get_context', {
  type: 'focused_file',
  workspaceId: 'default'
});

# Clone the repository
git clone <repository-url>
cd connai

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Build VS Code extension
cd packages/vscode-extension
pnpm run compile

# Install in VS Code
# Method 1: Development mode
# - Press F5 to launch Extension Development Host
# Method 2: Install VSIX
# - Package: pnpm run package
# - Install via Extensions: "Install from VSIX"

# Build browser extension
cd packages/browser-extension
pnpm build

# Install in Chrome/Edge
# 1. Open chrome://extensions/
# 2. Enable "Developer mode"
# 3. Click "Load unpacked"
# 4. Select packages/browser-extension/.output/chrome-mv3/

1. Start VS Code with a project open
2. Activate ConnAI extension (starts automatically on first use)
3. Install browser extension (auto-connects to VS Code)
4. Go to any webpage with text inputs
5. Type # in any input field → Context menu appears
6. Select context type → VS Code data is inserted automatically

• ChatGPT/Claude Integration: Easily share code context with AI assistants
• Code Review Assistance: Provide full context for AI-powered code reviews
• Documentation Generation: Share project structure for AI documentation tools
• Debugging Help: Include relevant code and error context in AI queries

• Issue Reporting: Automatically include relevant code context in bug reports
• Code Sharing: Share code snippets with full context on forums/chat
• Pair Programming: Remote collaboration with shared context
• Technical Support: Provide complete context when asking for help

• Technical Writing: Include live code examples in documentation
• Tutorials/Courses: Dynamic code context for educational content
• Blog Posts: Embed current project state in technical articles
• Code Reviews: Share context-rich code snippets for review

{
  "connai.server.port": 6797,
  "connai.server.host": "127.0.0.1",
  "connai.workspace.basePort": 6718,
  "connai.workspace.portRange": 100,
  "connai.cache.ttl": 300000,
  "connai.ignore.useGitignore": true,
  "connai.ignore.customPatterns": ["*.log", "tmp/", "node_modules/"]
}

The browser extension automatically detects VS Code servers but can be manually configured:

• Auto-detect servers: Scans ports 6718-6817 and 8080-8090
• Manual configuration: Set specific server URL and port in popup
• Connection timeout: Configurable timeout for server connections (default: 10s)
• Reconnection settings: Automatic reconnection with exponential backoff

• Node.js 18+ (with pnpm)
• VS Code 1.101.0+
• TypeScript 5.8+
• Chrome/Edge for browser extension testing

# Clone and setup
git clone <repository-url>
cd connai
pnpm install

# Build all packages
pnpm run build

# Watch mode for development
pnpm run dev

# Run specific package in watch mode
cd packages/vscode-extension && pnpm run watch
cd packages/browser-extension && pnpm run dev
cd packages/protocol && pnpm run build:watch

# Run all tests
pnpm test

# Run tests for specific package
cd packages/protocol && pnpm test
cd packages/vscode-extension && pnpm test

# Integration testing
# 1. Start VS Code Extension Development Host (F5)
# 2. Load browser extension in development mode
# 3. Open test-integration.html for end-to-end testing

connai/
├── packages/
│   ├── protocol/                    # Core protocol implementation
│   │   ├── src/
│   │   │   ├── core/               # Protocol core (message, transport)
│   │   │   ├── contracts/          # API contracts (context, file, workspace)
│   │   │   ├── adapters/           # Editor adapters (VS Code, future: Cursor)
│   │   │   └── index.ts            # Public API
│   │   └── package.json
│   │
│   ├── vscode-extension/           # VS Code extension
│   │   ├── src/
│   │   │   ├── extension.ts        # Main extension entry
│   │   │   ├── server/             # HTTP protocol server
│   │   │   ├── context/            # Context providers
│   │   │   ├── commands/           # VS Code commands
│   │   │   └── utils/              # Utilities and helpers
│   │   └── package.json
│   │
│   ├── browser-extension/          # Browser extension (WXT + React)
│   │   ├── entrypoints/
│   │   │   ├── background.ts       # Service worker
│   │   │   ├── content.ts          # Content script
│   │   │   └── popup/              # Extension popup UI
│   │   ├── src/utils/              # Protocol client, port scanner
│   │   └── wxt.config.ts
│   │
│   └── shared/                     # Shared utilities
│       ├── src/
│       │   ├── types.ts            # Common types
│       │   ├── constants.ts        # Shared constants
│       │   └── utils.ts            # Helper functions
│       └── package.json
│
├── examples/                       # Example implementations
├── docs/                          # Documentation
├── pnpm-workspace.yaml            # Monorepo configuration
└── package.json                   # Root package configuration

# Package for distribution
cd packages/vscode-extension
pnpm run package

# Publish to marketplace (requires vsce)
pnpm run publish

# Build for production
cd packages/browser-extension
pnpm run build

# Package for Chrome Web Store
pnpm run package

• Monorepo architecture with pnpm workspaces
• Core protocol layer (@connai/protocol)
• VS Code extension with HTTP server
• Browser extension with auto-connect
• Smart port management and discovery
• Rich context extraction (file, selection, tabs, problems, tree)
• Background connection management
• Multi-workspace support
• Protocol integration between browser and VS Code
• End-to-end testing setup

• WebSocket protocol implementation
• Real-time push notifications
• Enhanced error handling and user feedback
• Performance optimization and caching

• Support for additional editors (Cursor, WebStorm)
• Advanced AI context optimization
• Team collaboration features
• Plugin architecture for custom context providers
• Performance monitoring and analytics

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Add tests for new functionality
5. Ensure tests pass: pnpm test
6. Submit a pull request

• Use TypeScript for all new code
• Follow existing code style and patterns
• Add tests for new features
• Update documentation as needed
• Use conventional commit messages

• Keep packages focused and loosely coupled
• Use the shared package for common utilities
• Maintain clean public APIs
• Document all public interfaces

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

For support and questions:

• GitHub Issues: Create an issue
• Discussions: GitHub Discussions
• Documentation: Check the /docs folder for detailed guides

• Built with VS Code Extension API
• Browser extension powered by WXT Framework
• UI components using React and modern web standards
• Monorepo management with pnpm workspaces

🖥️ ───── 🔗 ───── 🌐 ───── 🤖
VS Code   ConnAI   Browser   AI
  ↕       Protocol    ↕       ↕
Your      Bridge    Web     AI
Project             App   Assistant