widdx 1.13.7

Autonomous AI Software Engineering Terminal — intelligent routing, 5 free models, 12 agents, fully automatic

⚡ WIDDX CLI

🤖 Autonomous AI Software Engineering OS

🚀 Powered by DeepSeek V4 + Google Gemini + 5 Free Models — No API Key Required

pip install widdx && python -m widdx

✨ One command. No config. No API key needed.

🌟 Features · 📦 Installation · 🖥️ Usage · 🤖 Agents · 🛠️ Skills · 🏗️ Architecture · 🔒 Security · عربي

---

🌟 Overview

WIDDX CLI is a fully autonomous AI software engineering environment that runs directly in your terminal. It orchestrates a team of specialized AI agents to plan, build, test, verify, and self-correct code — with zero human intervention required between steps.

✅ Works without an API key using 5 free models from opencode.ai. Upgrade to DeepSeek V4 or Google Gemini for higher-quality outputs.

---

✨ Features

🔀 Intelligent Multi-Provider Routing

Plan	Trigger	Models	Description
🟢 Plan A	DeepSeek key	deepseek-v4-pro + deepseek-v4-flash	Sequential planning + parallel execution
🟡 Plan B	Google key	gemini-2.5-pro + gemini-2.5-flash	Google Gemini architecture + execution
🔵 Plan C	No API key	5 free models via opencode.ai	Intelligent task-type routing

🔄 Automatic fallback chain: 429 / Timeout → instant switch to next provider — no user intervention required.

---

✅ Verification & Self-Correction

Three-level automatic verification after every code change:

📝 Write/Edit Code
    └─► 🔍 Syntax Check ──FAIL──► 🔧 Auto-fix (max 3 attempts)
              │
             PASS
              │
        🧪 Run Tests ──FAIL──► 🔧 Fix + Retest (max 3 attempts)
              │
             PASS
              │
            ✅ Done

Levels:

• 🔧 Tool-level — runs after every Write/Edit operation
• 🤖 Agent-level — runs after each agent completes
• 🏭 Pipeline-level — runs after all agents finish

---

🖥️ Professional Terminal UI

• ⏳ Animated thinking spinner with live streaming output
• 📝 Rich Markdown rendering in terminal
• 🔔 Toast notifications + bell on task completion
• 🌍 Full Arabic RTL support with contextual letter shaping
• 🖥️ 14 terminal types automatically detected (iTerm2, Windows Terminal, tmux, etc.)

---

🎁 Additional Capabilities

Feature	Description
🧠 Memory & Learning	SQLite-backed memory, self-learning engine, cached fix patterns
🔌 MCP Protocol	Built-in servers + external via stdio & HTTP, GitHub integration
🪝 Hooks System	PreToolUse / PostToolUse / SessionStart / TaskCompleted with security checker
⏰ Scheduler	Cron-based task scheduling with persistence
🔭 Bootstrapper	/bootstrap <tech> researches docs and auto-generates skills + agents
🌐 Web UI	FastAPI + SSE streaming dashboard on localhost:8520 (pip install widdx[web])
🌐 Arabic RTL	Full bidirectional text with contextual shaping
💻 Cross-Platform	Windows · macOS · Linux with automatic OS detection
🧠 Semantic Search	Local RAG: vector embeddings + ChromaDB, zero API cost

---

🧠 Semantic Code Search (RAG)

Local semantic search that finds relevant code without sending your codebase to any API:

• Embeddings: sentence-transformers (all-MiniLM-L6-v2) — runs entirely locally
• Storage: ChromaDB vector database — in-process, no server needed
• Integration: Auto-injects top 6 relevant code chunks into the AI's context window on every task
• Cost: Zero — no API calls for embeddings
• Command: /index builds both structural and semantic index
• Update: Automatic incremental updates when files change

Built-in — installed automatically with widdx.

---

📦 Installation

📋 Requirements

• 🐍 Python 3.10 or higher

⬇️ Install from PyPI

pip install widdx
python -m widdx

That's it. No API key. No configuration file. One command. ✅

For the web UI:

pip install widdx[web]        # Install web dependencies
widdx web                     # Start browser UI on http://localhost:8520

🔑 Optional: Add API Keys (higher quality)

DeepSeek V4:

# 🐧 Linux / macOS
export DEEPSEEK_API_KEY="sk-..."

# 🪟 Windows PowerShell
$env:DEEPSEEK_API_KEY = "sk-..."

Google Gemini:

# 🐧 Linux / macOS
export GOOGLE_API_KEY="AIza..."

# 🪟 Windows PowerShell
$env:GOOGLE_API_KEY = "AIza..."

Or type /key inside the WIDDX REPL at any time — the tool auto-detects whether it's a DeepSeek or Google key.

---

🖥️ Usage

💬 Interactive REPL

widdx                          # 🚀 Start interactive REPL
widdx "fix the auth bug"       # ⚡ Run a task directly

📋 Commands

Command	Description
🔀 /providers	Interactive provider manager (↑↓ Space to toggle)
🎯 /provider <name>	Switch to one provider exclusively
🔭 /bootstrap <tech>	Research a technology and generate project skills/agents/hooks
👥 /agents <task>	Run a multi-agent team on a complex task
🗺️ /plan <desc>	Create and execute a phased project plan
🛠️ /skills	List all available skills
🪝 /hooks	Show registered hooks grouped by event
🔌 /mcp	Manage MCP servers (list / add / remove)
📚 /learn	Show the self-learning ledger and draft assets
🔍 /knowledge <query>	Search past project memory
📦 /compact	Summarize conversation history to save tokens
🤖 /model	Show current model info and session cost
📋 /tasks	Show task execution history
🌿 /git	Show git status
🔎 /search <query>	Search codebase
↩️ /undo	Undo the last file change
💾 /save <name>	Save current session to disk
🧹 /clear	Clear conversation
🖥️ widdx web	Start Web UI in browser
🔄 widdx self-upgrade	Clean upgrade (uninstall old → install new)
✅ /self-check	Run full system diagnostics
❓ /help	Show help
🚪 /exit	Exit

🔭 Bootstrapper — Self-Learning

The /bootstrap command researches a technology, then automatically generates a skill file and agent profile for it:

widdx> /bootstrap flutter

  ◆ Bootstrapping: flutter
  🔍 Researching best practices, conventions, and patterns...
  ✅ Created: .widdx/skills/flutter.md
  ✅ Created: .widdx/agents/flutter.md
  🚀 Ready to work with flutter.

---

🌐 Web UI

WIDDX includes a professional browser-based interface with SSE streaming, tool execution display, and file preview:

pip install widdx[web]          # Install web dependencies (fastapi + uvicorn)
widdx web                       # Open http://localhost:8520
widdx web --port 9000           # Custom port
widdx web --no-open             # Don't open browser automatically

Clean upgrade (removes old files, preserves your config/skills):

widdx self-upgrade              # Check → uninstall old → install new
widdx self-upgrade --yes        # Skip confirmation prompt

Features:

• 💬 Chat interface with real-time SSE streaming responses
• 🔧 Live tool execution display with diffs and progress
• 📁 File browser and preview
• 📊 Session stats and cost tracking
• 🌙 Dark theme with professional design
• 🔄 Automatic reconnection on disconnect

---

🤖 Agents

12 specialized agents are built in and ready to use:

Agent	Specialization
🏗️ Software Architect	System design, API contracts, task breakdown
⚙️ Backend Developer	Framework-agnostic API development
🎨 Frontend Developer	React, Vue, TypeScript, accessibility
🐘 Laravel Architect	PHP, Eloquent, Blade, Artisan, Queues
🐳 DevOps Automator	Docker, CI/CD, Kubernetes
🔬 QA Engineer	Testing, code review, bug verification
🛡️ Security Reviewer	OWASP Top 10, vulnerability assessment
📊 Data Engineer	ETL pipelines, query optimization
🗄️ Database Architect	Schema design, indexing, migrations
🏛️ Systems Architect	Cross-service architecture, scalability
👁️ Code Reviewer	Constructive code feedback
⚡ Full-Stack Developer	End-to-end feature development

---

🛠️ Skills

17 built-in skills cover the full software development lifecycle:

🔍 code-review    🧪 tdd-workflow    🐛 bugfix          🚀 feat-dev
🛡️ security-review  📐 api-design   🚢 deploy          🗃️ db-migrate
🎨 ui-design      📚 docs-generate   ♻️ refactor        🔧 debug
🐘 laravel        ✅ testing         🗄️ database-design  ⚡ caching
📬 queue-jobs

Custom skills can be created manually in .widdx/skills/ or generated automatically via /bootstrap.

---

🏗️ Architecture

widdx-cli/
├── widdx/
│   ├── 🚪 cli.py                 # CLI entry point
│   ├── 🎛️  orchestrator.py       # Central coordinator
│   ├── 🔀 router/                # Intelligent multi-provider routing
│   ├── 🏭 pipeline/              # 7-step execution pipeline
│   │   ├── preflight.py          # Health checks + auto-install tools
│   │   └── execution.py          # Retry-based execution
│   ├── 🧠 memory/                # SQLite memory store
│   ├── 👥 agent_factory/         # Team generation + parallel execution
│   ├── 🛠️  skills/               # 17 built-in skills
│   ├── 🪝 hooks/                 # Event system
│   ├── ✅ verifier/              # 3-level verification + auto-fix
│   ├── 💬 repl/                  # Interactive REPL
│   ├── 🔁 tool_loop/             # Tool execution loop
│   ├── 🔌 mcp/                   # MCP Protocol
│   ├── 🔧 tools/                 # 8 local tools
│   ├── 🏗️  scaffolder/           # Automatic project scaffolding
│   ├── 🩹 repair_memory.py       # Cached fix pattern memory
│   ├── 🖥️  ui/                   # Professional Rich terminal UI
│   └── 🌐 web/                   # FastAPI web server + SSE frontend
└── 🧪 tests/                     # 895 tests

---

⚙️ Configuration

Default config location: ~/.widdx/config.yaml

models:
  architect:
    model: deepseek-v4-pro
    thinking: false
  executor:
    model: deepseek-v4-flash
    max_tokens: 32768

pipeline:
  complex_threshold: 3
  scaffold_enabled: true

memory:
  db_path: ~/.widdx/memory.db

---

🧪 Testing

# ▶️ Run all tests
python -m pytest tests/ -v

# 📊 Run with coverage report
python -m pytest tests/ --cov=widdx --cov-report=term-missing

---

🔒 Security

WIDDX is designed with security as a first principle:

• 🚫 No shell=True for AI shell execution — agent-issued shell commands use parsed argument lists; narrow Windows UI/hook compatibility paths are isolated
• 🔐 File permissions 600 — sensitive config files are restricted to owner read/write only
• 🛡️ Hooks security checker — blocks dangerous commands from the hook execution pipeline
• 📋 Full audit logging — complete error logging for traceability and post-incident review

---

📄 License

Proprietary — All Rights Reserved. © 2026 Muhammad Muslih — Widdx.

• Personal use is permitted free of charge
• Commercial use requires a written license agreement with revenue share
• Modification and redistribution are prohibited without prior written permission
• Attribution to Muhammad Muslih — Widdx is mandatory in all permitted uses

See LICENSE for full terms. For commercial licensing, contact: [e-mail]

---

🛠️ Built by Muhammad Muslih — Founder of Widdx using DeepSeek V4

⭐ If you find this project useful, please give it a star!

---

---

⚡ WIDDX CLI

🤖 نظام تشغيل هندسة برمجيات ذاتي القيادة

🚀 مدعوم بـ DeepSeek V4 + Google Gemini + 5 نماذج مجانية — لا يحتاج API Key للبدء

---

🌟 نظرة عامة

WIDDX CLI بيئة هندسة برمجيات ذاتية القيادة تعمل مباشرة في الطرفية. تنسّق فريقاً من الوكلاء الذكيين المتخصصين للتخطيط والبناء والاختبار والتحقق وتصحيح الأخطاء ذاتياً — دون تدخل يدوي بين الخطوات.

✅ تعمل بدون API Key باستخدام 5 نماذج مجانية من opencode.ai. يمكن الترقية إلى DeepSeek V4 أو Google Gemini للحصول على جودة أعلى.

---

📦 التثبيت

📋 المتطلبات

• 🐍 Python 3.10 أو أحدث

⬇️ التثبيت من PyPI

pip install widdx
python -m widdx

خلاص. بدون API Key. بدون إعدادات. أمر واحد. ✅

لواجهة الويب:

pip install widdx[web]              # تثبيت مكونات الويب
widdx web                           # فتح الواجهة على http://localhost:8520

🔑 اختياري: إضافة API Keys

DeepSeek V4:

# 🐧 Linux / macOS
export DEEPSEEK_API_KEY="sk-..."

# 🪟 Windows PowerShell
$env:DEEPSEEK_API_KEY = "sk-..."

Google Gemini:

# 🐧 Linux / macOS
export GOOGLE_API_KEY="AIza..."

# 🪟 Windows PowerShell
$env:GOOGLE_API_KEY = "AIza..."

أو اكتب /key داخل WIDDX في أي وقت — الأداة تكتشف تلقائياً نوع المفتاح.

---

✨ المميزات

🔀 توجيه ذكي متعدد المزودين

الخطة	الشرط	النماذج	الوصف
🟢 خطة A	مفتاح DeepSeek	deepseek-v4-pro + deepseek-v4-flash	تخطيط تسلسلي + تنفيذ متوازي
🟡 خطة B	مفتاح Google	gemini-2.5-pro + gemini-2.5-flash	معمارية Google Gemini + تنفيذ
🔵 خطة C	بدون API Key	5 نماذج مجانية من opencode.ai	توجيه ذكي حسب نوع المهمة

🔄 سلسلة Fallback تلقائية: 429 / Timeout → انتقال فوري للمزود التالي بدون تدخل المستخدم.

---

✅ التحقق والتصحيح الذاتي

ثلاثة مستويات من التحقق التلقائي بعد كل تغيير في الكود:

📝 كتابة/تعديل الكود
    └─► 🔍 فحص الصيغة ──فشل──► 🔧 إصلاح تلقائي (3 محاولات كحد أقصى)
              │
            نجاح
              │
        🧪 تشغيل الاختبارات ──فشل──► 🔧 إصلاح + إعادة (3 محاولات)
              │
            نجاح
              │
            ✅ تم

المستويات:

• 🔧 مستوى الأداة — يعمل بعد كل عملية كتابة أو تعديل
• 🤖 مستوى الوكيل — يعمل بعد انتهاء كل وكيل
• 🏭 مستوى خط الأنابيب — يعمل بعد انتهاء جميع الوكلاء

---

🤖 الوكلاء

12 وكيلاً متخصصاً مدمجاً وجاهزاً للاستخدام:

الوكيل	التخصص
🏗️ Software Architect	تصميم النظم، عقود API، تقسيم المهام
⚙️ Backend Developer	تطوير خلفي متعدد الأطر
🎨 Frontend Developer	React, Vue, TypeScript، إمكانية الوصول
🐘 Laravel Architect	PHP, Eloquent, Blade, Artisan, Queues
🐳 DevOps Automator	Docker, CI/CD, Kubernetes
🔬 QA Engineer	اختبار، مراجعة كود، تدقيق الأخطاء
🛡️ Security Reviewer	OWASP Top 10، تقييم الثغرات
📊 Data Engineer	خطوط ETL، تحسين الاستعلامات
🗄️ Database Architect	تصميم المخططات، الفهارس، الترحيل
🏛️ Systems Architect	معمارية الخدمات المتقاطعة، قابلية التوسع
👁️ Code Reviewer	مراجعة كود مع تغذية راجعة بناءة
⚡ Full-Stack Developer	تطوير شامل من البداية للنهاية

---

🛠️ المهارات

17 مهارة مدمجة تغطي دورة تطوير البرمجيات الكاملة:

🔍 code-review    🧪 tdd-workflow    🐛 bugfix          🚀 feat-dev
🛡️ security-review  📐 api-design   🚢 deploy          🗃️ db-migrate
🎨 ui-design      📚 docs-generate   ♻️ refactor        🔧 debug
🐘 laravel        ✅ testing         🗄️ database-design  ⚡ caching
📬 queue-jobs

---

📋 الأوامر

الأمر	الوصف
🔀 /providers	إدارة المزودين تفاعلياً
🎯 /provider <اسم>	تبديل لمزود واحد حصرياً
🔭 /bootstrap <تقنية>	بحث عن تقنية وتوليد مهارات/وكلاء/Hooks
👥 /agents <مهمة>	تشغيل فريق وكلاء على مهمة معقدة
🗺️ /plan <وصف>	إنشاء وتنفيذ خطة مشروع متعددة المراحل
🛠️ /skills	عرض المهارات المتاحة
🪝 /hooks	عرض hooks المسجلة حسب الحدث
🔌 /mcp	إدارة خوادم MCP
📚 /learn	عرض سجل التعلم الذاتي
🔍 /knowledge <استعلام>	بحث في ذاكرة المشروع
📦 /compact	تلخيص المحادثة لتوفير tokens
🤖 /model	عرض معلومات النموذج وتكلفة الجلسة
📋 /tasks	عرض سجل المهام
🌿 /git	عرض حالة git
🔎 /search <بحث>	بحث في قاعدة الشيفرة
↩️ /undo	تراجع عن آخر تغيير
💾 /save <اسم>	حفظ الجلسة
🧹 /clear	مسح المحادثة
🖥️ widdx web	فتح واجهة الويب في المتصفح
✅ /self-check	تشغيل تشخيص كامل للنظام
❓ /help	عرض المساعدة
🚪 /exit	خروج

---

🔭 التعلم الذاتي

أمر /bootstrap يبحث في وثائق التقنية ويولد تلقائياً ملف مهارة وملف وكيل:

widdx> /bootstrap flutter

  ◆ Bootstrapping: flutter
  🔍 جاري البحث عن أفضل الممارسات والأنماط...
  ✅ تم: .widdx/skills/flutter.md
  ✅ تم: .widdx/agents/flutter.md
  🚀 جاهز للعمل مع flutter.

---

🌐 واجهة الويب

WIDDX تتضمن واجهة ويب احترافية مع بث SSE وعرض أدوات التنفيذ ومعاينة الملفات:

pip install widdx[web]               # تثبيت مكونات الويب (fastapi + uvicorn)
widdx web                            # فتح http://localhost:8520
widdx web --port 9000                # منفذ مخصص
widdx web --no-open                  # بدون فتح المتصفح تلقائياً

المميزات:

• 💬 واجهة محادثة مع بث مباشر عبر SSE
• 🔧 عرض حي لتنفيذ الأدوات مع الفروقات والتقدم
• 📁 تصفح الملفات ومعاينتها
• 📊 إحصائيات الجلسة وتتبع التكاليف
• 🌙 واجهة داكنة بتصميم احترافي
• 🔄 إعادة اتصال تلقائية عند انقطاع الاتصال

---

🏗️ الهيكل المعماري

widdx-cli/
├── widdx/
│   ├── 🚪 cli.py                 # مدخل CLI
│   ├── 🎛️  orchestrator.py       # منسق مركزي
│   ├── 🔀 router/                # توجيه ذكي متعدد المزودين
│   ├── 🏭 pipeline/              # خط أنابيب تنفيذ 7 خطوات
│   │   ├── preflight.py          # فحص صحي + تثبيت تلقائي للأدوات
│   │   └── execution.py          # تنفيذ مع إعادة المحاولة
│   ├── 🧠 memory/                # مخزن SQLite
│   ├── 👥 agent_factory/         # توليد الفرق + تنفيذ متوازي
│   ├── 🛠️  skills/               # 17 مهارة مدمجة
│   ├── 🪝 hooks/                 # نظام الأحداث
│   ├── ✅ verifier/              # تحقق وتصحيح ذاتي (3 مستويات)
│   ├── 💬 repl/                  # واجهة تفاعلية
│   ├── 🔁 tool_loop/             # حلقة تنفيذ الأدوات
│   ├── 🔌 mcp/                   # بروتوكول MCP
│   ├── 🔧 tools/                 # 8 أدوات محلية
│   ├── 🏗️  scaffolder/           # إنشاء مشاريع تلقائياً
│   ├── 🩹 repair_memory.py       # ذاكرة إصلاح بأنماط مخزنة
│   ├── 🖥️  ui/                   # واجهة Rich احترافية
│   └── 🌐 web/                   # خادم FastAPI + واجهة SSE
└── 🧪 tests/                     # 895 اختباراً

---

⚙️ الإعدادات

~/.widdx/config.yaml:

models:
  architect:
    model: deepseek-v4-pro
    thinking: false
  executor:
    model: deepseek-v4-flash
    max_tokens: 32768

pipeline:
  complex_threshold: 3
  scaffold_enabled: true

memory:
  db_path: ~/.widdx/memory.db

---

🔒 الأمان

• 🚫 لا يوجد shell=True في تنفيذ أوامر الذكاء الاصطناعي — أوامر الوكيل تستخدم قوائم وسائط آمنة، مع حالات Windows/UI/hooks محدودة ومعزولة
• 🔐 صلاحيات الملفات 600 — ملفات الإعدادات الحساسة محمية بصلاحيات مقيدة
• 🛡️ مدقق أمني للـ Hooks — يمنع الأوامر الخطيرة من خط التنفيذ
• 📋 تسجيل كامل للأخطاء — للتتبع والتدقيق

---

🧪 الاختبارات

# ▶️ تشغيل جميع الاختبارات
python -m pytest tests/ -v

# 📊 مع تقرير التغطية
python -m pytest tests/ --cov=widdx --cov-report=term-missing

---

📄 الترخيص

احتكاري — جميع الحقوق محفوظة. © 2026 محمد مصلح — Widdx.

• الاستخدام الشخصي مسموح مجاناً
• الاستخدام التجاري يتطلب اتفاقية ترخيص مكتوبة مع حصة من الأرباح
• التعديل وإعادة التوزيع ممنوع بدون إذن كتابي مسبق
• ذكر الاسم — محمد مصلح — Widdx إلزامي في كل الاستخدامات المسموحة

راجع LICENSE للشروط الكاملة. للترخيص التجاري: [e-mail]

---

🛠️ بناه محمد مصلح — مؤسس Widdx باستخدام DeepSeek V4

⭐ إذا أعجبك المشروع، لا تنسَ إضافة نجمة!