Status : v2.1+ stable · 699 tests · CI à gates (bandit / gitleaks / pip-audit / coverage) · cerveau MLX Qwen3.6-35B-A3B · client et serveur MCP

La plupart des agents de code envoient ton code et tes données dans le cloud. Klody fait l'inverse : tout s'exécute sur ta machine. Le défi technique — faire d'un modèle local (plus petit que la frontière) un agent fiable — est résolu par l'orchestration, pas par la force brute : un routeur adaptatif, une boucle ReAct qui va au bout, un sandbox isolé, et une discipline de tests/sécurité de niveau production. Le tout extensible via MCP : Klody consomme des serveurs externes (Gmail, web…) et s'expose comme serveur pour d'autres agents.

flowchart TD
    U([👤 Utilisateur]) --> UI["🖥️ App desktop · Tauri 2 + React 19<br/>thème clair/sombre/auto"]
    UI <-->|WebSocket| API["⚡ FastAPI · :8000"]
    API --> ORCH

    subgraph ORCH["🧭 Adaptive Orchestrator — boucle ReAct"]
        R["Router · easy/medium/hard × 6 task_types"]
        L["Boucle auto-prolongée + anti-stall + Best-of-N"]
        R --> L
    end

    ORCH --> TOOLS
    ORCH --> MCPC["🔌 Client MCP"]
    ORCH --> LLM

    subgraph TOOLS["🧰 Outils natifs (69)"]
        direction LR
        T1["fichiers · sandbox<br/>multi-racines"]
        T2["code-aware<br/>tree-sitter + bge-m3"]
        T3["github · preview<br/>audio · skills · mémoire"]
        T4["macOS · MQTT<br/>automatisation · toolsmithing"]
    end

    MCPC -->|outils Gmail| GM["📧 Serveur MCP Gmail · :8084"]
    MCPC -->|outils Web| WB["🌐 Serveur MCP Web · :8085<br/>lecture seule · anti-SSRF"]

    subgraph LLM["🧠 LLM 100% local"]
        direction LR
        B["MLX cerveau<br/>Qwen3.6-35B · :8080"]
        C["MLX code<br/>Qwen3-Coder-30B · :8081"]
        O["Ollama fallback · :11434"]
    end

    TOOLS --> RAG["📚 LibraryBrain RAG · :8765"]
    API -.expose.-> MCPS["📡 Serveur MCP Klody · :8083<br/>(Cline · Zed · Continue le consomment)"]

pip install mlx-lm              # MLX-LM (Apple Silicon recommandé)
brew install ollama ripgrep     # Ollama (embeddings + fallback), ripgrep (recherche)
pip install sqlite-vec          # optionnel (LibraryBrain)

# Cerveau MLX (MoE 35B / ~3B actifs, multimodal)
huggingface-cli download unsloth/Qwen3.6-35B-A3B-MLX-8bit
# Spécialiste code (optionnel, port 8081)
huggingface-cli download mlx-community/Qwen3-Coder-30B-A3B-Instruct-8bit
# Embeddings (requis pour le retrieval)
ollama serve && ollama pull bge-m3

git clone https://github.com/klodynlov/klody-code-ai.git
cd klody-code-ai && python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # puis éditer (voir ci-dessous)

BACKEND=mlx
MLX_BASE_URL=http://localhost:8080/v1
MLX_MODEL=unsloth/Qwen3.6-35B-A3B-MLX-8bit
MLX_CHAT_TEMPLATE_ARGS='{"enable_thinking": false}'   # requis pour Qwen3.6 (thinking)

PROJECT_ROOT=/Users/ton-nom/mon-projet                # racine principale du sandbox
# ALLOWED_ROOTS=/Users/ton-nom/Projets:/Users/ton-nom/work   # racines supplémentaires

MAX_ITERATIONS=25                                     # plafond boucle ReAct
# Connecteurs MCP (optionnels) — Klody les découvre au démarrage
# KLODY_MCP_SERVERS={"gmail":"http://127.0.0.1:8084/mcp","web":"http://127.0.0.1:8085/mcp"}

./scripts/start-mlx.sh                 # 1. cerveau MLX (~30-60s de chargement)
ollama serve                           # 2. embeddings
python main.py                         # 3. CLI Rich  (--resume / --session <id>)
python api/server.py                   # 4. (option) API WebSocket pour l'UI Tauri
./scripts/start-klody-mcp.sh --http    # 5. (option) exposer Klody en serveur MCP (:8083)

# Connecteurs MCP (option) :
./scripts/start-gmail-mcp.sh --http    # Gmail  (:8084) — voir .env.example
./scripts/start-web-mcp.sh   --http    # Web    (:8085) — lecture seule

Le module le plus puissant : plutôt que de seulement utiliser des outils, Klody en construit de neufs, prêts à l'emploi et livrés avec leur test.

scaffold_tool(kind="mcp_server", name="capteurs maison", target_dir="~/Projets")
→ capteurs_maison/capteurs_maison_server.py  (serveur MCP FastMCP)
  capteurs_maison/test_capteurs_maison_server.py
  capteurs_maison/requirements.txt + README.md

• Sandbox fichiers : accès limité aux racines autorisées (PROJECT_ROOT + ALLOWED_ROOTS) ; ..//symlinks bloqués ; fichiers sensibles refusés partout (.env .key .pem .p12 .pfx .cer .crt .ppk .p8) ; 1 Mo max/écriture.
• Sandbox exécution : confirmation en TTY ; blocklist pré-confirmation (sudo, rm -rf /, mkfs, exfil SSH/AWS…) ; run_in_sandbox dans un venv jetable isolé.
• SQL sandboxé (run_sql) : base SQLite confinée aux racines autorisées, lecture seule par défaut (SQL_WRITE_ENABLED) ; authorizer sqlite3 default-deny, ATTACH/VACUUM INTO/load_extension bloqués, verrou SQLITE_LIMIT_ATTACHED=0, anti-DoS (limites + échéance wall-clock), une seule instruction par appel. Contrôles issus d'un threat-model adversarial.
• Ops en lecture seule (docker_control, kubectl_control, git_control) : introspection uniquement (Docker : ps/images/inspect/logs/stats… ; k8s : get/describe/logs/top… ; Git : status/log/diff/show/blame…), aucune mutation ; subprocess en argv (pas de shell), sous-commandes/verbes hardcodés, entrées (cible, resource, name, namespace, ref, fichier) validées par charset strict — pas d'injection de commande ni de flag (-o jsonpath, --kubeconfig, --output…) ; dépôt Git confiné aux racines autorisées ; sortie plafonnée, timeout borné. Les mutations Git (add/commit, locales et réversibles) sont désactivées par défaut (GIT_WRITE_ENABLED) ; push/pull et les opérations destructives (reset/checkout/clean/rebase) restent hors de l'outil. Le docker run (mutation) est doublement borné — DOCKER_WRITE_ENABLED et une allowlist d'images non vide — et impose un durcissement figé (aucun flag utilisateur : --network none, --cap-drop ALL, no-new-privileges, limites ressources, pas de montage) ; build/exec/rm restent exclus.
• Web en lecture seule : fetch_url/web_search en GET, http/https only, anti-SSRF (IP privées/loopback/link-local refusées, y compris via redirection), taille plafonnée.
• Pilotage macOS : garde plateforme (hors macOS → message clair, jamais d'exception) ; blocklist AppleScript (suppression, vidage corbeille, extinction, do shell script, contrôle UI synthétique refusés) ; reveal_in_finder/Spotlight confinés aux racines autorisées ; timeouts + sortie plafonnée.
• Automatisation & toolsmithing : opérations de masse en dry_run par défaut (montrent le plan avant d'agir) ; fichiers sensibles exclus partout ; destinations confinées aux racines autorisées ; refus d'écraser un dossier existant. MQTT borné (écoute à timeout dur, payload plafonné, broker local par défaut).
• Secrets : .env gitignoré, jamais hardcodés ni loggés. Commits signés (ED25519), branch protection sur main.
• CI : bandit (HIGH), gitleaks, pip-audit --strict, gate coverage 75 %, snapshots contrat MCP/OpenAPI.

python -m pytest tests/ -q                        # 699 passing
BACKEND=mlx python -m bench.run --category easy    # bench reproductible
BACKEND=mlx python -m bench.router_eval            # précision du routeur (F1 macro)

python main.py --resume               # reprend la dernière session
python main.py --session <id-court>   # reprend une session précise

• 📐 Étude de cas technique — les décisions d'ingénierie (routeur, MCP, sandbox, la saga max_tokens).
• 🛠️ OPS — exploitation, services permanents (LaunchAgents).
• 💼 Pour les entreprises — agents IA privés / local-first.

MIT © 2026 klodynlov