Metadata-Version: 2.4
Name: widdx
Version: 1.7.3
Summary: Autonomous AI Software Engineering Terminal — 3 AI providers, 12 agents, Arabic RTL, no API key needed
Author-email: Muhammad Muslih <mem3071990@gmail.com>
Project-URL: Homepage, https://github.com/widdx1990/widdx-cli
Project-URL: Repository, https://github.com/widdx1990/widdx-cli
Project-URL: Issues, https://github.com/widdx1990/widdx-cli/issues
Project-URL: Changelog, https://github.com/widdx1990/widdx-cli/blob/main/CHANGELOG.md
Keywords: ai,deepseek,cli,orchestration,agent,autonomous,coding-agent,terminal,arabic
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov<7.0,>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot<22.0,>=20.0; extra == "telegram"
Dynamic: license-file

# WIDDX CLI

**Autonomous AI Software Engineering OS — Powered by DeepSeek V4**

> **Author:** Muhammad Muslih — Founder of Widdx

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![DeepSeek](https://img.shields.io/badge/DeepSeek-V4-purple.svg)](https://www.deepseek.com/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/Version-1.4.0-brightgreen.svg)](CHANGELOG.md)
[![Tests](https://img.shields.io/badge/Tests-512%20passed-brightgreen.svg)]()
[![mypy](https://img.shields.io/badge/mypy-0%20errors-blue.svg)]()
[![Platforms](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-orange.svg)]()

---

## 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

```bash
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:
```bash
# 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):
```bash
# Windows PowerShell
$env:DEEPSEEK_API_KEY = "sk-..."

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

---

## Usage

### Interactive REPL

```bash
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`:

```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

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

---

## License

MIT License — see [LICENSE](LICENSE).

---

**Built by [Muhammad Muslih](https://github.com/widdx1990) — Founder of [Widdx](https://widdx.com) using DeepSeek V4**
