CrazyClaude/README.md

# CrazyClaude

Configuration Claude Code pour orchestrer des tâches de développement en déléguant les tâches atomiques à **Qwen3-Coder** via [aichat](https://github.com/sigoden/aichat).

Ce dépôt est conçu pour être intégré comme sous-répertoire `.claude/` dans n'importe quel projet. Il fournit agents, hooks, skills, un serveur MCP et une collection d'outils prêts à l'emploi.

Pour le détail de l'architecture, voir [`rapport-orchestration-claude-code.md`](./rapport-orchestration-claude-code.md).

---

## Architecture

```
Claude Code (orchestrateur)
    │
    └── MCP qwen3  (stdio)
            │
            └── aichat --serve (port dynamique)
                        │
                        └── LM Studio → Qwen3-Coder-Next
                                    + outils llm-functions
                                      (fs, shell, web, ...)
```

Le serveur MCP lance aichat au démarrage sur un port libre. Qwen3 dispose d'outils filesystem, shell et web fournis par [llm-functions](https://github.com/sigoden/llm-functions) — sans aucune logique d'outil dans le serveur lui-même.

---

## Prérequis

- [Claude Code](https://claude.ai/code) (`claude` dans le PATH)
- [aichat](https://github.com/sigoden/aichat) (`aichat` dans le PATH)
- [LM Studio](https://lmstudio.ai/) avec le modèle `qwen/qwen3-coder-next` chargé et accessible depuis aichat
- [argc](https://github.com/sigoden/argc) — runner de scripts pour llm-functions
- [jq](https://jqlang.github.io/jq/) — requis par llm-functions
- Python 3.11+ (pour le serveur MCP)
- Outils selon votre stack : `cargo` + `clippy` (Rust), `golangci-lint` (Go)

---

## Installation dans un projet existant

`.claude/` n'est pas commité dans le projet hôte — il est installé localement comme un venv.
Chaque développeur lance `install.sh` une fois.

### 1. Cloner CrazyClaude

```sh
git clone https://gargoton.petite-maison-orange.fr/eric/CrazyClaude.git .claude
```

### 2. Lancer le script d'installation

```sh
bash .claude/install.sh
```

Le script clone automatiquement `llm-functions` si absent.

Le script :
- crée le virtualenv Python
- construit les outils llm-functions
- rend les hooks exécutables
- enregistre le serveur MCP dans Claude Code
- ajoute `.claude/` au `.gitignore` du projet

### 4. Adapter CLAUDE.md à votre projet

Éditez `.claude/CLAUDE.md` : mettez à jour la section `## Stack` et les heuristiques de délégation.

---

## Structure

```
.claude/
├── CLAUDE.md                    # contexte projet + heuristiques de délégation
├── settings.json                # hooks et permissions
├── agents/
│   ├── qwen3-worker.md          # délégation vers Qwen3 via MCP
│   ├── code-reviewer.md         # révision code (Claude Haiku)
│   └── task-planner.md          # planification complexe (Claude Opus)
├── skills/
│   ├── delegation-rules.md      # quand déléguer à Qwen3
│   └── rust-go-conventions.md   # conventions Rust/Go
├── hooks/
│   ├── post-write-lint.sh       # lint automatique après écriture
│   ├── subagent-stop-log.sh     # log des décisions de délégation
│   └── pre-bash-guard.sh        # blocage des commandes dangereuses
├── mcp/
│   └── qwen3-mcp/
│       ├── server.py            # serveur MCP stdio : lance aichat + gère tool_calls
│       ├── agent_lm.py          # agent loop CLI autonome (usage direct sans MCP)
│       └── requirements.txt
├── llm-functions/               # collection d'outils pour Qwen3 (sous-repo)
│   ├── tools.txt                # outils activés
│   ├── functions.json           # déclarations générées (lues par server.py)
│   ├── bin/                     # binaires générés par argc build
│   └── tools/                   # scripts sources (.sh, .py, .js)
├── logs/                        # produits par les hooks (ignorés par jj/git)
└── venv/                        # virtualenv Python (ignoré par jj/git)
```

---

## Outils disponibles pour Qwen3

Les outils sont définis dans `.claude/llm-functions/tools.txt` et buildés avec `argc build`.

| Outil | Description |
|-------|-------------|
| `fs_cat` | Lit un fichier |
| `fs_ls` | Liste un répertoire |
| `fs_mkdir` | Crée un répertoire |
| `fs_write` | Écrit/crée un fichier |
| `fs_patch` | Modifie un fichier par patch |
| `execute_command` | Exécute une commande shell |
| `fetch_url_via_curl` | Requête HTTP GET |
| `web_search_aichat` | Recherche web |
| `execute_py_code` | Exécute du code Python |

Pour ajouter un outil : éditez `tools.txt` et relancez `argc build`.

---

## Configuration du modèle

Le modèle Qwen3 est configuré dans `.claude/mcp/qwen3-mcp/server.py` :

```python
QWEN3_MODEL = "LMStudio:qwen/qwen3-coder-next"
```

Le format `Provider:model-id` suit la convention aichat. Adaptez selon votre installation LM Studio.

---

## Fichiers à ignorer (jj / git)

```
.claude/venv/
.claude/logs/
.claude/llm-functions/bin/
.claude/llm-functions/cache/
```

Avec Jujutsu :

```sh
printf ".claude/venv/\n.claude/logs/\n.claude/llm-functions/bin/\n.claude/llm-functions/cache/\n" >> .gitignore
```

---

## Mise à jour

```sh
bash .claude/update_crazyclaude.sh
```

Le script fait `git pull` sur `.claude/` et `.claude/llm-functions/` puis reconstruit les outils.
L'historique du projet hôte n'est pas affecté.