SMARAN.AI Codex 🚀

✨ Overview

SMARAN.AI Codex is a production-grade AI coding assistant that runs as a VS Code extension, connecting to your local SMARAN.AI backend or cloud model providers. Built with privacy-first architecture, approval-gated actions, and configurable model routing.

🎯 One-click install → Connect to localhost:3003 → Start coding with AI

🎨 Key Features

🧠 Intelligent Code Assistance

Feature	Description
💬 Chat Console	Full-featured chat interface in VS Code sidebar
🔍 Code Explanation	Select code → Get detailed explanations
🔧 Smart Refactoring	AI-powered code refactoring with diff preview
🧪 Test Generation	Auto-generate unit test suites
🐛 Auto-Fix Diagnostics	Fix errors and warnings with one click
✨ Code Generation	Generate code from natural language instructions

🔐 Security & Privacy First

✅ Approval-gated actions — Every file write and terminal command requires explicit confirmation
✅ Workspace-bounded — Operates only within your opened workspace
✅ Local-first — Runs on your hardware, no data leaves your machine
✅ VS Code permissions — Respects Workspace Trust and OS permissions

🌐 Flexible Model Routing

┌─────────────────────────────────────────────────────────────┐
│  LOCAL MODELS (Ollama)          │  CLOUD PROVIDERS          │
├─────────────────────────────────┼────────────────────────────┤
│  qwen2.5-coder:7b              │  OpenAI (GPT-4, GPT-3.5)   │
│  deepseek-coder:6.7b           │  Anthropic (Claude 3.5)    │
│  codellama:7b                  │  Google (Gemini)           │
│  llama3.1:8b                   │  Groq, Together, OpenRouter│
│  ...and 50+ more               │  NVIDIA NIM, Mistral, etc. │
└─────────────────────────────────┴────────────────────────────┘

🎙️ Voice & Dictation (Optional)

Microphone button → Dictate prompts using Web Speech API
Speaker button → Read-aloud last response
Auto-read → Optional automatic read-aloud of responses
Language selector → Shared across dictation, response, and read-aloud locales

📎 Attachment Support

Text files (up to 50K chars/file)
Image files (metadata only in current version)
Workspace file manifest (60 entries max)

🚀 Quick Start

🎯 One-Command Install (Recommended)

Windows PowerShell (Admin):

irm https://raw.githubusercontent.com/shashwatmishra997/SMARAN.AI/main/install-smaran.ps1 | iex

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/shashwatmishra997/SMARAN.AI/main/install-smaran.sh | sh

⚡ What the installer does:

🔍 Detects Docker & installs Docker Desktop if missing

📦 Pulls latest SMARAN.AI image (shashwatmishra062/smaran-ai:latest)

🔧 Configures Ollama + starter model (qwen2.5:1.5b)

🌐 Starts container on localhost:3003 with health checks

🌍 Opens browser automatically when ready

📊 Starts Windows Host Telemetry Bridge for real GPU/CPU metrics

🐳 Manual Docker Start

docker run -d \
  --name smaran-ai \
  -p 3003:3003 \
  -v smaran_data:/app/data \
  --restart unless-stopped \
  shashwatmishra062/smaran-ai:latest

Then open: http://localhost:3003

⚙️ Extension Configuration

Open VS Code Settings (Ctrl+,) → Search SMARAN.AI:

Setting	Default	Description
`smaran.backendUrl`	`http://localhost:3003`	Backend endpoint URL
`smaran.defaultModel`	`auto`	Default model (auto, deepseek-coder, claude-3.5-sonnet, qwen-2.5-coder)
`smaran.enableHeadroomCompression`	`true`	Enable context preparation
`smaran.autoApplyDiffs`	`false`	Auto-apply file edits without diff preview

🎮 Usage Guide

🎯 Opening the Console

Command Palette (Ctrl+Shift+P) → SMARAN.AI: Open Console
Click SMARAN.AI icon in Activity Bar
Keyboard shortcut: Configure in Keyboard Shortcuts → smaran.startAgent

💻 Editor Integration

Right-click in editor → SMARAN.AI submenu:

Explain Selected Code 📖
Refactor Selection 🔧
Generate Unit Tests 🧪
Auto-Fix Error 🐛

⌨️ Keyboard Shortcuts (Customizable)

Action	Default	Command ID
Open Console	None	`smaran.startAgent`
Generate Code	None	`smaran.generateCode`
Explain Code	None	`smaran.explainCode`
Refactor Code	None	`smaran.refactorCode`
Generate Tests	None	`smaran.generateTests`
Fix Diagnostics	None	`smaran.fixDiagnostics`

💡 Tip: Bind shortcuts in File → Preferences → Keyboard Shortcuts → Search smaran

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        VS CODE EXTENSION                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │  Sidebar    │  │  Webview    │  │  Extension Host         │ │
│  │  (Activity  │  │  (Chat UI)  │  │  • Context Builder      │ │
│  │   Bar)      │  │             │  │  • Action Validator     │ │
│  └──────┬──────┘  └──────┬──────┘  │  • Model Router         │ │
│         │                │         │  • Telemetry Client     │ │
│         └────────┬───────┘         └───────────┬─────────────┘ │
│                  │                              │              │
│                  ▼                              ▼              │
│         ┌─────────────────────────────────────────────────┐   │
│         │           HTTP / WebSocket                      │   │
│         └─────────────────────────────────────────────────┘   │
└────────────────────────────────┬──────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                      SMARAN.AI BACKEND                          │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐  │
│  │ Ollama  │ │ vLLM    │ │ RAG     │ │ Web     │ │ Plugins │  │
│  │ Local   │ │ Cloud   │ │ Engine  │ │ Search  │ │ (MCP)   │  │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘  │
└─────────────────────────────────────────────────────────────────┘

📊 Real Hardware Telemetry (Windows)

For accurate GPU/CPU/RAM metrics matching Windows Task Manager:

# Run once to enable real hardware detection
.\run-host-telemetry.ps1

What it does:

Runs telemetry bridge natively on Windows (not in Docker VM)
Detects: NVIDIA RTX (VRAM, temp, usage), AMD, Intel GPUs
CPU: Real cores, threads, usage %, frequency
RAM: Total/used/available, disk I/O, network
Writes to %LOCALAPPDATA%\SMARAN.AI\telemetry\host_stats.json
Docker container reads via bind mount → Shows in Performance Panel

🎨 Screenshots

🛠️ Development

Prerequisites

Node.js 18+
VS Code 1.90+
TypeScript 5.9+

Build & Run

cd vscode-smaran-coding-agent
npm install
npm run compile          # Compile TypeScript
npm run watch            # Watch mode for development

Package for Marketplace

npm install -g @vscode/vsce
vsce package
# Creates: smaran-ai-codex-1.3.4.vsix

Publish to Marketplace

vsce publish
# Or: vsce publish patch/minor/major

📁 Project Structure

vscode-smaran-coding-agent/
├── src/
│   ├── extension.ts          # Main entry point
│   ├── chatView.ts           # Webview panel provider
│   ├── contextBuilder.ts     # Workspace context gathering
│   ├── modelRouter.ts        # Local/cloud model routing
│   ├── actionValidator.ts    # Approval-gated actions
│   ├── telemetryClient.ts    # Real-time metrics
│   └── utils/
├── media/
│   ├── agent.svg             # Extension icon
│   └── agent.png             # Marketplace icon
├── out/                      # Compiled JavaScript
├── package.json              # Extension manifest
├── tsconfig.json             # TypeScript config
└── README.md                 # This file

🤝 Contributing

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push branch: git push origin feature/amazing-feature
Open Pull Request

📄 License

MIT License — Free for personal and commercial use.

👨‍💻 Developer

Created with ❤️ by Shashwat Mishra

🙏 Acknowledgments

VS Code Team — Extensible editor platform
Ollama — Local LLM runtime
vLLM — High-throughput inference
Lucide — Beautiful icons
Tailwind CSS — Utility-first styling
All Contributors — Issues, PRs, feedback

⭐ Star the repo if you find it useful!