widdx 1.6.0

Autonomous AI Software Engineering Terminal — 3 AI providers, 12 agents, Arabic RTL, no API key needed

WIDDX CLI

Autonomous AI Software Engineering OS — Powered by DeepSeek V4

Author: Muhammad Muslih — Founder of Widdx

---

Features

• 3 AI Providers — DeepSeek (paid) + OpenCode + Kilo (free, no API key needed). Fallback routing with 5 internal models. Toggle providers at runtime via /providers interactive manager
• Super Agent Capabilities — DeepSeek thinking mode, multi-level self-review, auto-fix loop, pre-flight health checks, business logic understanding (spec → architecture → plan)
• 12 Built-in Agents — Software Architect, Backend, Frontend, Laravel, DevOps, QA, Security, Data Engineer, Database Architect, Systems Architect, Code Reviewer, Full-Stack + Registry with 50+ aliases
• 17 Built-in Skills — Code Review, TDD, Bugfix, Feature Dev, Security Review, API Design, Deploy, DB Migration, UI Design, Docs, Refactoring, Debugging, Laravel, Testing, Database Design, Caching, Queue Jobs
• Self-Learning Bootstrapper — /bootstrap <technology> researches docs, generates project-specific skills + agents + hooks automatically
• Verification + Self-Correction — Write → Test → Fix → Retest loop with automatic rollback on failure (3 levels: tool, agent, pipeline)
• Token-Aware Skill Loading — Only top-3 relevant skills loaded per task via keyword matching
• Multi-Agent Pipeline — Automatic team assembly, dependency-aware parallelism, structured handoffs for complex tasks (complexity ≥ 3)
• Interactive Provider Boot Screen — Choose which providers to activate on first launch with checkboxes (↑↓ Space Enter)
• Professional Terminal UI — Animated thinking spinner, live streaming output, Rich markdown rendering, toast notifications, bell sound on completion, colored toolbar with real-time tokens/cost
• Arabic RTL Support — Full bidirectional text with letter joining, 14 detected terminal types across Windows/macOS/Linux
• Memory & Learning — SQLite-backed memory store, self-learning engine, repair memory with cached fix patterns, /knowledge search
• MCP Protocol — Built-in servers (project-info, utility) + external via stdio & HTTP, GitHub integration framework
• Hooks System — PreToolUse/PostToolUse/SessionStart/TaskCompleted with security checker
• Scheduled Tasks — Cron-based task scheduling with persistent schedules
• Cross-Platform — Windows, macOS, and Linux support with automatic OS detection
• 512 pytest Tests — 19 test files covering router, UI, agents, hooks, MCP, permissions, skills, scheduler, repair memory, self-learning, preflight, bootstrap, and more

---

Installation

Requirements

• Python 3.10+

Quick Start

pip install widdx
python -m widdx

That's it. No API key needed. No PATH configuration. No clone. One command.

After install, you can also just type widdx if Python Scripts is in your PATH.

For DeepSeek (paid, higher quality) — type /key inside WIDDX, or:

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

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

No API key needed! 2 free AI providers (OpenCode + Kilo) work immediately.

For DeepSeek (paid, higher quality):

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

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

---

Usage

Interactive REPL

widdx                              # Start REPL
widdx "fix the auth bug"           # Run task directly

Commands

/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 multi-agent team on a complex task
/plan <desc>         Create and run a phased project plan
/skills              List available skills (shows auto vs manual)
/hooks               Show registered hooks grouped by event
/mcp                 Manage MCP servers (list/add/remove)
/learn               Show self-learning ledger and draft assets
/knowledge <query>   Search past project memory
/compact             Summarize history to save tokens
/llm <prompt>        Direct LLM call
/memory              Show WIDDX.md/CLAUDE.md content
/resume              Resume last incomplete task
/model               Show model info and session cost
/tasks               Show task history
/git                 Show git status
/search <q>          Search codebase
/index               Re-scan project files
/undo                Undo last change
/save <name>         Save session to disk
/sessions            List saved sessions
/clear               Clear conversation
/approve             Approve all permissions for session
/deny                Block shell commands for session
/help                Show help
/exit                Exit
/<skill-name>        Run a skill directly

Bootstrapper — Self-Learning

widdx> /bootstrap flutter
  Bootstrapping: flutter
  Researching best practices, conventions, and patterns...
  Done. Created:
  + .widdx/skills/flutter.md
  + .widdx/agents/flutter.md
  Ready to work with flutter. Reload to activate.

---

Architecture

widdx-cli/
├── widdx/
│   ├── cli.py                    # CLI entry point (Click)
│   ├── config.py                 # Config with deep merge
│   ├── orchestrator.py           # Direct command coordinator
│   ├── pipeline.py               # 7-step execution pipeline
│   ├── memory.py                 # SQLite memory store
│   ├── evolution.py              # Self-optimizing weights
│   ├── permissions.py            # Command whitelist + approval
│   ├── indexer.py                # Project context for agents
│   ├── git_ops.py                # Safe git operations
│   ├── agent_factory/            # Team generation + parallel execution
│   ├── agents/                   # 14 built-in agents + registry
│   │   ├── registry.py           # AgentRegistry with 50+ aliases
│   │   ├── architect.py          # Software Architect
│   │   ├── backend.py            # Backend (framework-agnostic)
│   │   ├── frontend.py           # Frontend Developer
│   │   ├── laravel.py            # Laravel Architect
│   │   ├── devops.py             # DevOps Automator
│   │   ├── qa.py                 # QA Engineer
│   │   ├── security.py           # Security Reviewer
│   │   ├── fullstack.py          # Full-Stack Developer
│   │   ├── data_engineer.py      # Data Engineer
│   │   ├── database_architect.py # Database Architect
│   │   ├── systems_architect.py  # Systems Architect
│   │   └── code_reviewer.py      # Code Reviewer
│   ├── skills/                   # Skills system
│   │   ├── loader.py             # Frontmatter parser
│   │   └── builtin/              # 17 built-in skills (.md)
│   ├── hooks/                    # Hooks system
│   │   ├── events.py             # HookEvent enum
│   │   ├── handlers.py           # Command + Prompt handlers
│   │   ├── security_check.py     # PreToolUse: block dangerous commands
│   │   ├── lint_check.py         # PostToolUse: auto-lint
│   │   └── session_log.py        # SessionStart/TaskCompleted logger
│   ├── verifier/                 # Verification + Self-Correction
│   │   └── __init__.py           # ProjectVerifier with auto-fix loop
│   ├── bootstrap/                # Self-learning bootstrapper
│   │   └── __init__.py           # BootstrapManager: research -> generate -> save
│   ├── repl/                     # Interactive REPL
│   ├── router/                   # API routing (DeepSeek)
│   ├── tool_loop/                # Tool execution loop
│   ├── mcp/                      # MCP Protocol
│   ├── tools/                    # 8 local tools
│   └── ui/                       # Terminal UI (Rich)
├── tests/                        # pytest suite (300+ tests)
├── README.md
├── QUICKSTART.md
├── CHANGELOG.md
└── pyproject.toml

---

How It Works

For Any Task (Simple or Complex)

User: "build a REST API with Laravel"
  |
  v
1. SkillManager.match_skills()
   Keywords: "build", "rest", "api", "laravel"
   Matches: laravel, api-design, tdd-workflow (top 3)
  |
  v
2. Pipeline._analyze_input()
   "build" + "api" = complexity 2 -> simple path
  |
  v
3. ToolLoop executes with matched skills injected
   Model: DeepSeek V4 Flash
   Tools: Read, Write, Edit, Bash, Grep, Glob
  |
  v
4. After every Write/Edit: ProjectVerifier
   Syntax check -> Run tests -> Auto-fix -> Retest
  |
  v
5. Done: verified output

For Unfamiliar Technology

User: "build a Flutter app with Firebase"
  |
  v
SkillManager.missing_domains() detects: flutter, firebase
  |
  v
System prompt includes:
  "Unfamiliar Technologies Detected: flutter, firebase
   Ask user about /bootstrap flutter"
  |
  v
User: /bootstrap flutter
  -> BootstrapManager researches Flutter docs
  -> Generates .widdx/skills/flutter.md
  -> Generates .widdx/agents/flutter.md
  -> Reload skills
  |
  v
Now ready. Next Flutter task matches the new skill.

For Complex Multi-Agent Tasks

User: /agents "build a SaaS platform with Laravel and Vue"
  |
  v
AgentFactory.generate_team()
  Architect model designs team from 14 domains:
  -> Systems Architect (overall design)
  -> Laravel Architect (backend)
  -> Database Architect (schema)
  -> Frontend Developer (Vue)
  -> QA Engineer (tests)
  |
  v
execute_team() with dependency-aware parallelism
  Agents run in waves. Independent agents run concurrently.
  Handoffs pass context between agents.
  |
  v
Pipeline verifier: syntax check all files + run test suite
  If failed: auto-fix loop (max 3 cycles)
  If still failed: rollback to snapshots

---

Agents (14)

Agent	Domain	Specialization
Software Architect	architect	System design, API contracts, task breakdown
Systems Architect	systems	Cross-service architecture, scalability
Backend Architect	backend	Framework-agnostic API development
Laravel Architect	laravel	PHP, Eloquent, Blade, Artisan, Queues
Database Architect	database	Schema design, indexing, migrations
Frontend Developer	frontend	React, Vue, TypeScript, accessibility
Full-Stack Developer	fullstack	End-to-end feature development
DevOps Automator	devops	Docker, CI/CD, Kubernetes
QA Engineer	qa	Testing, code review, bug verification
Security Reviewer	security	OWASP Top 10, vulnerability assessment
Data Engineer	data	ETL pipelines, query optimization
Code Reviewer	reviewer	Code review with constructive feedback

---

Skills (17 built-in)

Skill	Description
code-review	Security, performance, quality review checklist
tdd-workflow	RED -> GREEN -> REFACTOR cycle
bugfix	Reproduce -> root cause -> fix -> prevent
feat-dev	Plan -> implement bottom-up -> test
security-review	OWASP Top 10 security audit
api-design	REST and GraphQL API design principles
deploy	Production deployment with rollback
db-migrate	Safe database migration management
ui-design	Professional web interface principles
docs-generate	API, function, and README documentation
refactor	Safe step-by-step code restructuring
debug	Systematic debugging approach
laravel	Laravel conventions, Eloquent, Blade, Artisan
testing	Test pyramid, unit/integration/E2E strategy
database-design	Schema design, indexing, query optimization
caching	Multi-level caching strategy and patterns
queue-jobs	Background job processing patterns

---

Verification + Self-Correction

Write/Edit Code
  |
  v
Syntax Check (Python/JSON/PHP)
  |-- FAIL -> Auto-fix -> Re-check (max 3)
  v
Run Test Suite
  |-- FAIL -> Analyze errors -> Fix code -> Re-test (max 3)
  |           |-- Still failing -> Rollback to snapshots
  v
PASS -> Done

Operates at 3 levels: tool (after every Write/Edit), agent (after agent finishes), pipeline (after all agents).

---

Configuration

~/.widdx/config.yaml:

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

pipeline:
  complex_threshold: 3

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

evolution:
  enabled: true
  decay_factor: 0.9

---

Testing

python -m pytest tests/ -v
python -m pytest tests/ --cov=widdx --cov-report=term-missing

---

License

MIT License — see LICENSE.

---

Built by Muhammad Muslih — Founder of Widdx using DeepSeek V4