![\"GitHub](\"https://img.shields.io/github/v/tag/Das-rebel/omniclaw?style=flat-square&logo=github&label=latest\")
\n\n## π What's New (June 2026)\n\n**Vault Hashtag Extraction + Entity Enrichment** β OmniClaw now auto-extracts hashtags and named entities from conversation history, enriching the persistent memory graph. **Why it matters:** Subhajit uses this when researching market signals β WhatsApp conversations about \"fintech\" or \"AI agents\" automatically tag and surface relevant past context. The `vault-control/` module runs this nightly across all session data, saving 30+ minutes of manual tagging per week.\n\n**12 Built-in Skills (Matt Pocock framework)** β OmniClaw now exposes 12 engineering skills as slash commands: `/diagnose`, `/grill-me`, `/tdd`, `/to-issues`, `/to-prd`, `/triage`, `/improve-codebase-architecture`, `/write-a-skill`, `/zoom-out`, `/caveman`, `/fusion`, `/brainstorming-research-ideas`. **Why it matters:** For growth teams managing complex multi-step workflows, these skills turn OmniClaw into a research partner β not just a bot. Subhajit uses `/diagnose` to debug WhatsApp message routing issues and `/brainstorming-research-ideas` to ideate on new data sources for the Growth Workflow OS pipeline.\n\n**GCP Production Deployment (8+ LLM providers)** β OmniClaw routes across OpenAI, Anthropic, Gemini, Groq, Cerebras, Ollama, LM Studio, and vLLM simultaneously. Production URL: `dasomni-bot-338789220059.asia-south1.run.app`. **Why it matters:** For teams running multi-channel campaigns (WhatsApp + Telegram + Alexa), this single orchestration layer means Subhajit changes the LLM provider in one config file and it propagates across all channels β no per-channel updates. Cost dropped 40% when switching from OpenAI-only to Groq-for-simple-queries routing.\n![\"License](\"https://img.shields.io/github/license/Das-rebel/omniclaw?style=flat-square&logo=github\")
\n![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/Das-rebel/omniclaw/ci.yml?style=flat-square&logo=github\")
\n![\"Repo](\"https://img.shields.io/github/repo-size/Das-rebel/omniclaw?style=flat-square&logo=github\")
\n![\"Language](\"https://img.shields.io/github/languages/code-size/Das-rebel/omniclaw?style=flat-square&logo=github\")
\n![\"Stars\"](\"https://img.shields.io/github/stars/Das-rebel/omniclaw?style=flat-square&logo=github\")
\n![\"npm](\"https://img.shields.io/npm/dt/adaptive-memory-multi-model-router?style=flat-square&logo=npm\")
\n\n> **Unified AI assistant platform with multi-channel support (Alexa, WhatsApp, Telegram, Hindi/Bengali/Hinglish). Multi-provider LLM orchestration: 8+ models (OpenAI, Anthropic, Gemini, Groq, Cerebras, Ollama, LM Studio, vLLM).**\n\n### π By the Numbers\n\n| Metric | Value |\n|--------|------:|\n| **npm downloads** | **31,184** |\n| Daily average | ~410/day |\n| Days active | 76 |\n| npm trend | π growing |\n\n```\nββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ OmniClaw Architecture β\nβ β\nβ βββββββββββ ββββββββββββ βββββββββββ βββββββββββ ββββββββββββ β\nβ β Alexa β β WhatsApp β βTelegram β β Web β β Telegramβ β\nβ β Skills β β Bridge β β Bot β β Interfaceβ β Bot β β\nβ ββββββ¬βββββ ββββββ¬ββββββ ββββββ¬βββββ ββββββ¬βββββ ββββββ¬ββββββ β\nβ β β β β β β\nβ ββββββββββββββββ΄βββββββββββββββ΄βββββββββββββββ΄ββββββββββββββββ β\nβ β β\nβ βββββββββββΌββββββββββ β\nβ β OmniClaw Core β β\nβ β SignalβPlanβ β β\nβ β ExecuteβRespond β β\nβ βββββββββββ¬ββββββββββ β\nβ β β\nβ ββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββ β\nβ β β β β\nβ ββββββΌβββββββββ ββββββββΌββββββββ βββββββββΌβββββββ β\nβ βLLM Routing β β MCP Servers β β Skills β β\nβ β Engine β β (Browser, β β (TDD,Grill, β β\nβ β β β TaskMaster, β β Diagnose, β β\nβ β β β TMLPD) β β ZoomOut...) β β\nβ ββββββ¬βββββββββ ββββββββ¬ββββββββ βββββββββ¬βββββββ β\nβ β β β β\nβ ββββββΌβββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββΌβββββββ β\nβ β 50+ API Clients β β\nβ β OpenAI β Anthropic β Gemini β Groq β Cerebras β Ollama β LMStudioβ β\nβ ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β\nββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n---\n\n## Table of Contents\n\n- [Why OmniClaw](#-why-omniclaw)\n- [Quick Start](#-quick-start)\n- [Architecture](#-architecture)\n- [Features](#-features)\n- [Comparison](#-comparison)\n- [AI Provider Routing](#-ai-provider-routing)\n- [Browser Automation (MCP)](#-browser-automation-mcp)\n- [Multi-Language Support](#-multi-language-support)\n- [Configuration](#-configuration)\n- [Deployment](#-deployment)\n- [API Reference](#-api-reference)\n- [When NOT to Use This](#-when-not-to-use-this)\n- [Roadmap](#-roadmap)\n- [Contributing](#-contributing)\n\n---\n\n## Why OmniClaw\n\nBuilt by a growth operator with 10 years at Axis Bank, Groww, and NIRO. Every automation workflow hit the same walls: locked into one AI provider's pricing, rate limits that didn't scale, and tools that didn't talk to each other.\n\nOmniClaw is the orchestration layer that fixes all three.\n\n| Feature | OmniClaw | Single-provider bot | Ad-hoc scripts |\n|---------|----------|---------------------|----------------|\n| **LLM Providers** | 8+ (OpenAI, Anthropic, Gemini, Groq, Cerebras, Ollama, LM Studio, vLLM) | 1 | 0 |\n| **Channels** | Alexa + WhatsApp + Telegram + Web | 1 | 0 |\n| **Languages** | 100+ (including Hindi, Bengali, Hinglish) | 1-2 | 0 |\n| **Browser Automation** | 18 MCP tools (navigate, click, screenshot, JS eval) | None | Fragile XPaths |\n| **Multi-turn Memory** | Persistent session context across turns | None | None |\n| **Fallback Chains** | Automatic failover if provider rate-limits | Manual retry | None |\n| **Cost Optimization** | Route by task type (cheap models for simple tasks) | No routing | No routing |\n| **Production-Ready** | GCP-deployed, rate limiting, input sanitization | Prototype | Prototype |\n| **Skills System** | 12 built-in skills (TDD, diagnose, grill-me, etc.) | None | None |\n| **MCP Integration** | Browser, TaskMaster AI, TMLPD servers | None | None |\n| **Audio Pipeline** | Whisper STT + TTS + wake word detection | None | None |\n| **Storage** | Google Drive (rclone), local filesystem | None | None |\n\n---\n\n## Quick Start\n\n### Method 1: Full Installation (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/Das-rebel/omniclaw.git\ncd omniclaw\n\n# Install Node.js dependencies (workspaces)\nnpm install\n\n# Install Python dependencies\npip install -e .\n\n# Copy environment template\ncp .env.example .env\n\n# Edit .env with your API keys (see Configuration section)\nnano .env\n\n# Run Alexa Skill Handler\nnpm run alexa\n\n# Run Telegram Bot\nnpm run telegram\n\n# Run tests\nnpm test\n```\n\n### Method 2: Docker\n\n```bash\n# Pull pre-built image\ndocker pull ghcr.io/das-rebel/omniclaw:latest\n\n# Run with environment file\ndocker run -it --env-file .env \\\n -p 3000:3000 \\\n ghcr.io/das-rebel/omniclaw:latest\n\n# Or use docker-compose for full stack\n# See docker-compose.yml in repository root\n```\n\n### Method 3: Development Mode (No TMLPD)\n\nFor local development without TMLPD integration:\n\n```bash\n# Start without TMLPD (faster startup)\nnpm run alexa:dev\n\n# Run unit tests only\nnpm run test:unit\n\n# Run integration tests\nnpm run test:integration\n```\n\n### Method 4: GCP Cloud Run\n\n```bash\n# Set GCP project\ngcloud config set project YOUR_PROJECT_ID\n\n# Deploy to Cloud Run\ngcloud run deploy omniclaw \\\n --source . \\\n --region asia-south1 \\\n --platform managed \\\n --allow-unauthenticated\n\n# Or use the deployment script\ncd infrastructure/gcp\n./deploy.sh\n```\n\n---\n\n## Architecture\n\n### High-Level System Design\n\n```\n βββββββββββββββββββββββββββββββββββββββββββββββ\n β USERS β\n ββββββββ¬βββββββββββ¬ββββββββββββ¬βββββββββββββββ\n β β β\n βββββββββββββββββΌββββββββββββΌββββββββββββΌββββββββββββββββ\n β β β β β\n βββββββΌββββββ ββββββββΌββββ βββββββΌβββββ βββββΌβββββ β\n β Alexa β β WhatsApp β β Telegram β β Web β β\n β Handler β β Bridge β β Bot β β App β β\n βββββββ¬ββββββ ββββββββ¬ββββ βββββββ¬βββββ βββββ¬βββββ β\n β β β β β\n ββββββββββββββββ΄ββββββββββββ΄ββββββββββββ β\n β β\n ββββββββββΌβββββββββββββββββββββββββββββββββββββΌβ\n β OmniClaw Core β\n β Signal β Plan β Execute β Respond β\n ββββββββββββββββββ¬βββββββββββββββββββββββββββββ\n β\n ββββββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββ\n β β β\n βββββββββββΌββββββββββ ββββββββββββΌβββββββββββ ββββββββββββΌβββββββββββ\n β LLM Router β β MCP Server Hub β β Skills Engine β\n β β β β β β\n β β’ Cost-based β β β’ Browser (sota) β β β’ LLM β\n β β’ Latency-aware β β β’ TaskMaster AI β β β’ TTS/STT β\n β β’ Task routing β β β’ TMLPD β β β’ Translation β\n β β’ Fallback chains β β β’ Memory β β β’ Search β\n β β’ Rate limit β β β β β’ Orchestration β\n βββββββββββ¬ββββββββββ ββββββββββββ¬βββββββββββ ββββββββββββ¬βββββββββββ\n β β β\n βββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββ\n β\n ββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ\n β β β\n βββββββββββΌββββββββββ ββββββββββΌβββββββββ βββββββββββΌββββββββββ\n β 50+ Clients β β Storage β β Audio Pipeline β\n β β β β β β\n β OpenAI β β Google Drive β β Whisper STT β\n β Anthropic β β (rclone mount) β β TTS (Sarvam/ β\n β Gemini β β Local filesystem β β Google/Amazon) β\n β Groq β β Session state β β Wake word detectionβ\n β Cerebras β β β β β\n β Ollama (local) β β β β β\n β LM Studio β β β β β\n β vLLM β β β β β\n βββββββββββββββββββββ ββββββββββββββββββββ βββββββββββββββββββββ\n```\n\n### Directory Structure\n\n```\nomniclaw/\nβββ apps/ # User-facing entry points (channel adapters)\nβ βββ alexa/ # ποΈ Alexa Skill Handler (Node.js)\nβ β βββ alexa_handler.js # Main handler (with TMLPD)\nβ β βββ alexa_handler_no_tmlpd.js\nβ β βββ alexa_intent_router.js # Intent-based routing\nβ β βββ alexa_response_builder.js\nβ β βββ language/localization.js # Hindi/Bengali/Hinglish\nβ β βββ package.json\nβ βββ whatsapp/ # π¬ WhatsApp Bridge (Baileys)\nβ β βββ whatsapp_relay.js\nβ β βββ session_manager.js\nβ β βββ message_processor.js\nβ βββ telegram/ # βοΈ Telegram Bot\nβ β βββ telegram_bot.js\nβ β βββ command_handlers.js\nβ β βββ inline_query_handler.js\nβ βββ web/ # π Web Interface (Express)\nβ βββ web_server.js\nβ βββ static/\nβ\nβββ skills/ # π§ AI Capabilities (Modular skill system)\nβ βββ browser/ # π Browser Automation (MCP)\nβ β βββ sota-browser/ # 18-tool MCP server\nβ β βββ mcp_server.py\nβ β βββ install.sh\nβ β βββ tools/\nβ β βββ navigate.py\nβ β βββ click.py\nβ β βββ snapshot.py\nβ β βββ ...\nβ βββ llm/ # Multi-provider LLM routing\nβ β βββ router.js # Cost + latency routing engine\nβ β βββ providers/\nβ β β βββ openai_client.js\nβ β β βββ anthropic_client.js\nβ β β βββ gemini_client.js\nβ β β βββ groq_client.js\nβ β β βββ cerebras_client.js\nβ β β βββ ollama_client.js\nβ β β βββ lmstudio_client.js\nβ β β βββ vllm_client.js\nβ β βββ fallback_chain.js\nβ βββ tts/ # Text-to-Speech\nβ β βββ sarvam_tts.js # Sarvam AI (India-focused)\nβ β βββ google_tts.js\nβ β βββ amazon_polly.js\nβ βββ stt/ # Speech-to-Text\nβ β βββ whisper_stt.js\nβ β βββ google_stt.js\nβ βββ translate/ # Translation\nβ β βββ translation_service.js\nβ βββ search/ # AI-powered search\nβ β βββ tavily_search.js\nβ β βββ wikipedia_search.js\nβ β βββ reddit_search.js\nβ βββ memory/ # Memory systems\nβ β βββ session_memory.js\nβ βββ orchestration/ # Workflow engine\nβ βββ pipeline.js # Signal β Plan β Execute β Respond\nβ βββ skill_dispatcher.js\nβ\nβββ clients/ # π‘ External API Clients (50+)\nβ βββ glm_client.js # ZhipuAI GLM (China)\nβ βββ sarvam_client.js # Sarvam AI (India)\nβ βββ spotify_client.js # Spotify\nβ βββ plex_client.js # Plex\nβ βββ kodi_client.js # Kodi\nβ βββ tavily_client.js # Tavily AI Search\nβ βββ wikipedia_client.js # Wikipedia\nβ βββ [40+ more clients]\nβ\nβββ services/ # βοΈ Backend services\nβ βββ api-gateway/ # Rate limiting + routing\nβ β βββ rate_limiter.js\nβ β βββ request_queue.js\nβ β βββ api_key_manager.js\nβ βββ tunnel/ # WhatsApp relay tunnel\nβ β βββ omniclaw-tunnel/\nβ β β βββ tunnel_server.js\nβ β β βββ start_tunnel.sh\nβ β βββ ngrok_manager.js\nβ βββ automation/ # Workflow orchestration\nβ βββ workflow_executor.js\nβ βββ trigger_manager.js\nβ\nβββ shared/ # π Shared utilities + security\nβ βββ security/\nβ β βββ input_sanitizer.js\nβ β βββ rate_limiter.js\nβ β βββ api_key_manager.js\nβ βββ utils/\nβ β βββ logger.js\nβ β βββ config_loader.js\nβ β βββ retry_handler.js\nβ βββ constants/\nβ βββ intent_definitions.js\nβ\nβββ infrastructure/ # βοΈ GCP Deployment\nβ βββ gcp/\nβ β βββ cloudrun/\nβ β β βββ Dockerfile\nβ β βββ cloud_build.yaml\nβ β βββ deploy.sh\nβ βββ docker/\nβ βββ docker-compose.yml\nβ βββ Dockerfile\nβ\nβββ tests/ # π§ͺ Test suites\nβ βββ unit/\nβ βββ integration/\nβ βββ run-tests.js\nβ\nβββ package.json # Node.js workspace root\nβββ .env.example # Environment template\nβββ docker-compose.yml # Full stack Docker\nβββ CONTRIBUTING.md\nβββ LICENSE\nβββ README.md\n```\n\n### OmniClaw Pipeline: Signal β Plan β Execute β Respond\n\n```\nββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ OmniClaw Pipeline β\nβ β\nβ βββββββββββ βββββββββββ βββββββββββ βββββββββββ βββββββββββββββ β\nβ β SIGNAL βββββΆβ PLAN βββββΆβ EXECUTE βββββΆβ RESPOND βββββΆβ COMPLETE β β\nβ β β β β β β β β β β β\nβ β β’ Parse β β β’ Route β β β’ Call β β β’ Build β β β’ Log β β\nβ β intentβ β LLM β β API β β voice β β β’ Store β β\nβ β β’ Extractβ β β’ Checkβ β β’ Run β β or β β memory β β\nβ β slots β β cache β β skill β β text β β β’ Cleanup β β\nβ β β’ Lang β β β’ Fall-β β β’ Check β β responseβ β β β\nβ β detectβ β back β β rate β β β β β β\nβ βββββββββββ βββββββββββ βββββββββββ βββββββββββ βββββββββββββββ β\nββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n---\n\n## Features\n\n### π€ AI Provider Orchestration\n\nOmniClaw routes requests across 8+ LLM providers based on cost, latency, and task type. Simple classification tasks use cheap models; complex reasoning uses premium models. Automatic fallback chains ensure reliability.\n\n| Provider | Models | Context | Cost Tier | Latency |\n|----------|--------|---------|-----------|---------|\n| **OpenAI** | GPT-4o, GPT-4o-mini, GPT-4-turbo, GPT-3.5-turbo | 128K | $$$$ | ~1-3s |\n| **Anthropic** | Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku | 200K | $$$$ | ~1-4s |\n| **Gemini** | Gemini 2.0 Flash, Gemini 1.5 Pro, Gemini 1.5 Flash | 1M | $$ | ~0.5-2s |\n| **Groq** | Llama 3.3 70B, Mixtral 8x7B, Whisper | - | $ | ~0.2-0.5s |\n| **Cerebras** | Llama 3.3 70B, Qwen 2.5 32B | 8K | $ | ~0.3-0.8s |\n| **Ollama** | Any GGUF model (local) | 8K | Free | ~0.1-2s |\n| **LM Studio** | Any GGUF model (local) | 8K | Free | ~0.1-2s |\n| **vLLM** | Any HuggingFace model (self-hosted) | - | Free | ~0.3-2s |\n\n### π Browser Automation (MCP Protocol)\n\n18 tools for full browser control via Model Context Protocol:\n\n| Tool | Signature | Description |\n|------|-----------|-------------|\n| `browser_create_session` | `(user_id: string) β Session` | Create isolated browser session |\n| `browser_create_tab` | `(session_id, url?) β Tab` | Open new tab (optionally navigate) |\n| `browser_navigate` | `(tab_id, url) β void` | Navigate to URL |\n| `browser_snapshot` | `(tab_id, screenshot?) β PageTree` | Get DOM tree + element refs + frame info |\n| `browser_screenshot` | `(tab_id, full?) β base64` | Capture screenshot (viewport or full-page) |\n| `browser_click` | `(tab_id, selector) β void` | Click element by CSS selector |\n| `browser_type` | `(tab_id, selector, text) β void` | Type text into input field |\n| `browser_press_key` | `(tab_id, key) β void` | Press keyboard key |\n| `browser_scroll` | `(tab_id, x, y) β void` | Scroll to position |\n| `browser_wait` | `(tab_id, selector, timeout?) β void` | Wait for element to appear |\n| `browser_evaluate` | `(tab_id, script, frame_index?) β any` | Execute JavaScript |\n| `browser_extract_images` | `(tab_id) β Image[]` | Get all images with src/alt/dims |\n| `browser_list_tabs` | `(session_id) β Tab[]` | List all open tabs |\n| `browser_close_tab` | `(tab_id) β void` | Close specific tab |\n| `browser_close_session` | `(session_id) β void` | End session + all tabs |\n| `browser_http_get` | `(url, headers?) β Response` | Direct HTTP GET (no browser) |\n| `browser_import_cookies` | `(tab_id, cookies) β void` | Set cookies for authenticated sessions |\n| `browser_info` | `() β BrowserStatus` | Get browser state |\n\n### π£οΈ Multi-Language Support\n\nBuilt for India's vernacular-first customer base:\n\n| Language | TTS | STT | Coverage |\n|----------|-----|-----|----------|\n| **English** | β
| β
| 100% |\n| **Hindi** | β
(Sarvam AI) | β
(Sarvam AI) | Native |\n| **Bengali** | β
(Sarvam AI) | β
(Sarvam AI) | Native |\n| **Hinglish** | β
(Sarvam AI) | β
(Sarvam AI) | Native |\n| **Tamil** | β
| β
| Native |\n| **Telugu** | β
| β
| Native |\n| **Marathi** | β
| β
| Native |\n| **100+ languages** | β
(Google TTS fallback) | β
(Google STT fallback) | via API |\n\n### π¬ Multi-Channel Messaging\n\n| Channel | Protocol | Features |\n|---------|----------|----------|\n| **Alexa Skills** | Alexa Skills Kit (ASK) | Voice, multi-language, in-skill purchasing |\n| **WhatsApp** | Baileys (WhatsApp Web) | Message relay, session persistence, media |\n| **Telegram** | Telegram Bot API | Commands, inline queries, groups, channels |\n| **Web** | Express.js | REST API, webhooks, static serving |\n\n### π― Skills System\n\n12 built-in skills for specialized tasks:\n\n| Skill | Command | Description |\n|-------|---------|-------------|\n| **Diagnose** | `/diagnose` | Disciplined bug diagnosis: reproduce β minimize β hypothesize β instrument β fix β regression-test |\n| **Grill-Me** | `/grill-me` | Relentless interview to resolve every branch of a design decision tree |\n| **Grill-With-Docs** | `/grill-with-docs` | Grilling that updates CONTEXT.md and ADRs inline as decisions crystallize |\n| **Improve Architecture** | `/improve-codebase-architecture` | Find deepening opportunities, propose refactors for testability and AI-navigability |\n| **TDD** | `/tdd` | Test-driven development with vertical tracer-bullet slices, red-green-refactor |\n| **To-Issues** | `/to-issues` | Break a plan/PRD into independently-grabbable vertical-slice issues |\n| **To-PRD** | `/to-prd` | Turn conversation context into a PRD and publish to issue tracker |\n| **Triage** | `/triage` | Move issues through a triage state machine (needs-triage β ready-for-agent) |\n| **Write-a-Skill** | `/write-a-skill` | Author new agent skills with proper structure and progressive disclosure |\n| **Zoom-Out** | `/zoom-out` | Step up abstraction layer, map relevant modules and callers |\n| **Caveman** | `/caveman` | Ultra-compressed communication mode (~75% token reduction) |\n| **Vault** | `/vault` | Search personal knowledge vault (bookmarks, tweets, Instagram posts) |\n\n### π MCP Server Integrations\n\n| Server | Protocol | Capabilities |\n|--------|----------|--------------|\n| **sota-browser** | MCP | 18 browser automation tools |\n| **TaskMaster AI** | MCP | Task management, agent deployment |\n| **TMLPD** | MCP | Parallel execution, cost tracking, intelligent routing |\n\n### π Security & Rate Limiting\n\n- **Input sanitization**: XSS/CSRF protection on all user inputs\n- **API key management**: Environment-based, never in code\n- **Rate limiting**: Per-user, per-endpoint, configurable windows\n- **Session isolation**: Each user session is sandboxed\n- **Telegram**: Bot token validation, /commands, webhook verification\n- **WhatsApp**: Baileys session encryption, QR-code auth\n\n### ποΈ Storage Options\n\n| Provider | Method | Use Case |\n|----------|--------|----------|\n| **Google Drive** | rclone mount | 135GB+ shared storage, cross-device |\n| **Local filesystem** | Node.js fs | Fast local reads, session state |\n| **Session persistence** | JSON files | Cross-request context memory |\n\n---\n\n## Comparison\n\n### OmniClaw vs Other Orchestration Frameworks\n\n| Feature | OmniClaw | LangChain | AutoGen | CrewAI |\n|---------|----------|-----------|---------|--------|\n| **Channels** | Alexa, WhatsApp, Telegram, Web | None | None | None |\n| **Browser automation** | 18 MCP tools (built-in) | Via tool calls | None | None |\n| **Multi-language** | 100+ (built-in) | Via adapter | None | None |\n| **Local models** | Ollama, LM Studio, vLLM | Via LangServe | Via AutoGen | Via crewAI |\n| **Skills system** | 12 built-in skills | Agents | Agents | Agents |\n| **India focus** | Hindi/Bengali/Hinglish | None | None | None |\n| **Production deploy** | GCP Cloud Run | Manual | Manual | Manual |\n| **Rate limiting** | Built-in | Via LangSmith | None | None |\n| **Fallback chains** | Automatic | Manual | Manual | Manual |\n| **Audio pipeline** | Whisper + TTS | Via adapter | None | None |\n| **Cost routing** | Automatic (8+ providers) | Manual | Manual | Manual |\n| **Complexity** | Medium | High | High | Medium |\n| **Learning curve** | Low | High | High | Medium |\n\n---\n\n## AI Provider Routing\n\n### Routing Decision Flow\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ Incoming Request β\nβ (intent, context, user_id) β\nββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββ\n β\n βββββββββββΌβββββββββββ\n β Task Classifier β\n β β\n β β’ Classification ββββlow_complexityβββ\n β β’ Intent detection β β\n β β’ Language ID β β\n βββββββββββ¬βββββββββββ β\n β β\n ββββββββββββββββΌβββββββββββββββ β\n β β β β\n ββββββββββββΌβββ βββββββββΌββββββ ββββββΌβββββββββββββ β\n β Simple β β Medium β β Complex β β\n β Task β β Task β β Task β β\n β β β β β β β\n β β Groq β β β Gemini β β β OpenAI GPT-4o β β\n β β Cerebras β β β Anthropic β β β Anthropic β β\n β β Ollama β β Haiku β β Opus β β\n ββββββββββββββββ βββββββββββββββ ββββββββββββββββββββ β\n β β\n βββββββββββΌβββββββββββββββββββββββββββββββ\n β Fallback Chain β\n β β\n β Primary β Secondary β Tertiary β Error β\n β (with rate limit + timeout handling) β\n ββββββββββββββββββββββββββββββββββββββββββββ\n β\n ββββββββββΌβββββββββββ\n β Response Cache β (optional, TTL-based)\n ββββββββββββββββββββββ\n```\n\n### Configuration Example\n\n```javascript\n// skills/llm/router.js - Routing configuration\nconst ROUTING_RULES = {\n // Simple tasks β cheap, fast models\n classification: {\n providers: ['groq', 'cerebras', 'ollama'],\n model: 'llama-3.3-70b',\n max_cost: 0.001, // $0.001 per call\n max_latency_ms: 500\n },\n \n // Medium tasks β balanced cost/latency\n summarization: {\n providers: ['gemini', 'anthropic-haiku'],\n model: 'gemini-1.5-flash',\n max_cost: 0.01,\n max_latency_ms: 2000\n },\n \n // Complex tasks β premium models\n reasoning: {\n providers: ['openai', 'anthropic'],\n model: 'gpt-4o',\n max_cost: 0.10,\n max_latency_ms: 10000\n },\n \n // Voice tasks β low latency critical\n speech_synthesis: {\n providers: ['sarvam', 'google'],\n model: 'sarvam-mono',\n max_cost: 0.005,\n max_latency_ms: 1000\n }\n};\n```\n\n---\n\n## Browser Automation (MCP)\n\n### Chrome CDP Mode (Connect to Existing Chrome)\n\n```bash\n# 1. Open Chrome with remote debugging enabled\nchrome --remote-debugging-port=60807\n\n# 2. Get WebSocket URL from chrome://inspect/#devices\n# Example: ws://localhost:60807/devtools/browser/abc123\n\n# 3. Set environment variable\nexport CHROME_CDP_URL=\"ws://localhost:60807/devtools/browser/abc123\"\n\n# 4. Run MCP browser server\ncd skills/browser/sota-browser\n./install.sh # Only needed once\npython3 mcp_server.py\n\n# 5. Test connection\ncurl -X POST http://localhost:3000/api/browser/connect\n```\n\n### Headless Chromium Mode (No Existing Chrome)\n\n```bash\n# 1. Install headless Chromium\n./skills/browser/sota-browser/install.sh\n\n# 2. Run MCP server (auto-launches headless)\ncd skills/browser/sota-browser\npython3 mcp_server.py\n\n# 3. The server will spawn its own Chromium process\n```\n\n### MCP Tool Usage Examples\n\n```javascript\n// Navigate and take screenshot\nconst tabId = await mcp.createTab();\nawait mcp.navigate(tabId, 'https://news.ycombinator.com');\nawait mcp.snapshot(tabId);\n\n// Click element and type\nawait mcp.click(tabId, '.login-btn');\nawait mcp.type(tabId, '#username', 'myuser');\nawait mcp.type(tabId, '#password', 'mypass');\nawait mcp.click(tabId, 'button[type=\"submit\"]');\n\n// Run JavaScript in page context\nconst title = await mcp.evaluate(tabId, \n \"document.querySelector('h1').textContent\"\n);\n\n// Get all images from page\nconst images = await mcp.extractImages(tabId);\nconsole.log(images.map(img => img.src));\n\n// Multi-tab management\nconst tabs = await mcp.listTabs(sessionId);\nawait mcp.closeTab(tabs[0].id);\n```\n\n---\n\n## Multi-Language Support\n\n### Language Detection & Routing\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ Language Routing β\nβ β\nβ User Input β\nβ β β\nβ βΌ β\nβ ββββββββββββββββββ β\nβ β Detect Languageβ β\nβ β (50+ langs) β β\nβ βββββββββ¬βββββββββ β\nβ β β\nβ βββββββΌββββββ¬βββββββββ¬βββββββββ¬βββββββββ β\nβ β β β β β β β\nβ English Hindi Bengali Tamil Telugu Others β\nβ β β β β β β β\nβ βΌ βΌ βΌ βΌ βΌ βΌ β\nβ ββββββ¬βββββ¬ββββ ββββββ¬βββββ ββββββ β\nβ βTTS βTTS βTTSβ βTTS βTTS β βTTS β β\nβ βen βhi βbn β βta βte β β.. β β\nβ ββββ¬ββ΄βββ¬ββ΄βββ ββββ¬ββ΄βββ¬β ββββ¬ββ β\nβ β β β β β β\nβ ββββΌβββββΌβββ βββββΌβββββΌβββ βββββΌβββββββ β\nβ β Sarvam β β Sarvam β β Google β β\nβ β (hi) β β (ta/te) β β (other) β β\nβ ββββββββββββ βββββββββββββ βββββββββββββ β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n### Sarvam AI Configuration (India-focused)\n\n```javascript\n// skills/tts/sarvam_tts.js\nconst SARVAM_CONFIG = {\n api_key: process.env.SARVAM_API_KEY,\n base_url: 'https://api.sarvam.ai',\n \n // Supported languages\n languages: {\n 'en': 'english',\n 'hi': 'hindi',\n 'bn': 'bengali',\n 'ta': 'tamil',\n 'te': 'telugu',\n 'mr': 'marathi',\n 'kn': 'kannada',\n 'ml': 'malayalam'\n },\n \n // Voice settings per language\n voice_presets: {\n 'hi': { voice_id: 'vidya', speed: 1.0, pitch: 0 },\n 'bn': { voice_id: 'avi', speed: 1.0, pitch: 0 },\n 'ta': { voice_id: 'kumar', speed: 1.0, pitch: 0 }\n }\n};\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# =============================================================================\n# AI PROVIDERS\n# =============================================================================\n\n# OpenAI\nOPENAI_API_KEY=sk-... # GPT-4o, GPT-4o-mini, GPT-3.5\n\n# Anthropic\nANTHROPIC_API_KEY=sk-ant-... # Claude 3.5 Sonnet, Claude 3 Opus\n\n# Google Gemini\nGEMINI_API_KEY=AIza... # Gemini 2.0 Flash, 1.5 Pro\n\n# Groq (fast inference)\nGROQ_API_KEY=gsk_... # Llama 3.3 70B, Mixtral\n\n# Cerebras (fast inference)\nCEREBRAS_API_KEY=cscr_... # Llama 3.3 70B\n\n# ZhipuAI GLM (China)\nGLM_API_KEY=...\n\n# =============================================================================\n# REGIONAL AI (INDIA)\n# =============================================================================\n\n# Sarvam AI (TTS/STT for Hindi, Bengali, Hinglish)\nSARVAM_API_KEY=...\n\n# Google TTS/STT (fallback)\nGOOGLE_TTS_API_KEY=...\nGOOGLE_STT_API_KEY=...\n\n# =============================================================================\n# MESSAGING PLATFORMS\n# =============================================================================\n\n# Telegram Bot\nTELEGRAM_BOT_TOKEN=123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ\n\n# WhatsApp (Baileys session directory)\nWHATSAPP_SESSION_DIR=./whatsapp_sessions\n\n# Alexa Skills\nALEXA_APP_ID=amzn1.ask.skill.xxx\nALEXA_SKILL_ID=amzn1.ask.skill.xxx\n\n# =============================================================================\n# BROWSER AUTOMATION\n# =============================================================================\n\n# Chrome CDP URL (for existing Chrome)\n# Format: ws://localhost:60807/devtools/browser/xxx\nCHROME_CDP_URL=ws://localhost:60807/devtools/browser/abc123\n\n# Or use headless Chromium (no existing Chrome needed)\nUSE_HEADLESS_CHROMIUM=true\n\n# =============================================================================\n# SEARCH & RESEARCH\n# =============================================================================\n\n# Tavily AI (AI-powered search)\nTAVILY_API_KEY=tvly-...\n\n# =============================================================================\n# STORAGE\n# =============================================================================\n\n# Google Drive (rclone mount path)\nGDRIVE_MOUNT_PATH=/mnt/gdrive\n\n# Local session storage\nSESSION_STORAGE_PATH=./sessions\n\n# =============================================================================\n# RATE LIMITING\n# =============================================================================\n\n# Telegram rate limit (requests per minute per user)\nTELEGRAM_RATE_LIMIT=10\n\n# Global concurrency limit\nGLOBAL_CONCURRENCY_MAX=5\n\n# =============================================================================\n# SERVER CONFIG\n# =============================================================================\n\n# Port for local server\nPORT=3000\n\n# GCP Cloud Run (if deployed)\nGCP_PROJECT_ID=your-project-id\nGCP_REGION=asia-south1\n\n# =============================================================================\n# LOGGING\n# =============================================================================\n\nLOG_LEVEL=info # debug, info, warn, error\nLOG_FORMAT=json # json, simple\n```\n\n---\n\n## Deployment\n\n### GCP Cloud Run\n\n```bash\n# 1. Set up GCP project\ngcloud config set project YOUR_PROJECT_ID\ngcloud config set region asia-south1\n\n# 2. Build and push container\ngcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/omniclaw:latest\n\n# 3. Deploy to Cloud Run\ngcloud run deploy omniclaw \\\n --image gcr.io/YOUR_PROJECT_ID/omniclaw:latest \\\n --platform managed \\\n --region asia-south1 \\\n --allow-unauthenticated \\\n --port 3000 \\\n --memory 2Gi \\\n --cpu 2 \\\n --timeout 300 \\\n --concurrency 80\n\n# 4. Set environment variables in Cloud Run\ngcloud run services update omniclaw \\\n --set-env-vars \"OPENAI_API_KEY=sk-...,ANTHROPIC_API_KEY=sk-ant-...\"\n\n# 5. Get service URL\ngcloud run services describe omniclaw --format 'value(status.url)'\n```\n\n### Docker Compose (Local Production)\n\n```yaml\n# docker-compose.yml\nversion: '3.8'\n\nservices:\n omniclaw:\n build:\n context: .\n dockerfile: infrastructure/docker/Dockerfile\n ports:\n - \"3000:3000\"\n env_file:\n - .env\n volumes:\n - ./sessions:/app/sessions\n - ./whatsapp_sessions:/app/whatsapp_sessions\n restart: unless-stopped\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:3000/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n\n mcp-browser:\n build:\n context: ./skills/browser/sota-browser\n dockerfile: Dockerfile\n ports:\n - \"3001:3001\"\n environment:\n - CHROME_CDP_URL=${CHROME_CDP_URL}\n volumes:\n - /tmp/chromium:/tmp/chromium\n restart: unless-stopped\n\nnetworks:\n default:\n name: omniclaw-network\n```\n\n### WhatsApp Tunnel (Production)\n\n```bash\n# Start WhatsApp tunnel service\ncd services/tunnel/omniclaw-tunnel\n\n# Start ngrok tunnel (or use your own domain)\n./start_tunnel.sh\n\n# This exposes WhatsApp webhook to your server\n# Configure webhook URL in Baileys config\n```\n\n---\n\n## API Reference\n\n### Telegram Bot Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `/start` | Start bot, show welcome message | `/start` |\n| `/help` | Show help and available commands | `/help` |\n| `/status` | Check bot and service status | `/status` |\n| `/search \n Built with β€οΈ for universal AI orchestration\n
\n\n\n β Star us on GitHub\n Β·\n Fork\n Β·\n Share\n
","readmeFilename":"README.md"}