# DEV_SETUP — Guide développeur

Ce document recense les tâches d'administration du dépôt qui ne sont pas couvertes
par `README.md` (destiné aux utilisateurs) mais nécessaires au quotidien.

## Sommaire

- [Environnement Python](#environnement-python)
- [Services locaux](#services-locaux)
- [Worktrees Claude Code](#worktrees-claude-code)
- [Build du package Windows](#build-du-package-windows)

---

## Environnement Python

- Venv du projet : `.venv/` (à la racine du repo)
- Python supporté : 3.10 à 3.12

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Services locaux

Utiliser `./svc.sh` pour piloter tous les services. La carte des ports est
dans `services.conf`.

```bash
./svc.sh status          # État de tous les services
./svc.sh start streaming # Démarrer le serveur Agent V1 (port 5005)
./svc.sh restart api     # Redémarrer l'API (port 8000)
./svc.sh stop            # Tout arrêter
```

## Worktrees Claude Code

La CLI Claude Code peut créer des worktrees git dans `.claude/worktrees/` pour
exécuter des agents parallèles sur des branches isolées. Ces dossiers peuvent
occuper plusieurs centaines de Mo chacun et polluer les grep.

### Vérifier l'état des worktrees

```bash
# Worktrees actifs vs branches git
git worktree list
git branch | grep worktree

# Espace disque consommé
du -sh .claude/worktrees/* 2>/dev/null
```

### Supprimer un worktree proprement

```bash
# 1) Retirer l'entrée git (libère le lock dans .git/worktrees/)
git worktree remove .claude/worktrees/agent-<hash>

# 2) Si le dossier persiste (worktree orphelin), forcer le retrait
git worktree remove --force .claude/worktrees/agent-<hash>

# 3) Supprimer les branches worktree abandonnées
git branch -D worktree-agent-<hash>
```

### Nettoyage global

```bash
# Supprimer TOUS les worktrees et leurs branches associées
for wt in .claude/worktrees/*/; do
    hash=$(basename "$wt")
    git worktree remove --force "$wt" 2>/dev/null
done
git branch | grep worktree-agent- | xargs -r git branch -D
git worktree prune -v

# Nettoyer les branches orphelines (worktree supprimé mais branche subsiste)
git branch | grep worktree-agent- | xargs -r git branch -D
```

Le dossier `.claude/` est gitignoré — il ne sera jamais committé.

## Build du package Windows

Le package de déploiement pour le PC Windows des utilisateurs est généré par
`deploy/build_package.sh`. Il embarque `agent_v0/agent_v1/` directement (pas
de staging intermédiaire).

```bash
./deploy/build_package.sh          # Build standard
./deploy/build_package.sh --clean  # Nettoyer avant de builder
```

Le script vérifie la présence de tous les fichiers Python requis via la liste
`REQUIRED_FILES`. Si vous ajoutez un nouveau module Python critique côté agent
(ex: dans `agent_v1/core/` ou `agent_v1/network/`), **ajoutez-le à
`REQUIRED_FILES`** pour qu'un fichier manquant fasse échouer le build plutôt
que de produire un zip incomplet.

### Note historique : `agent_v0/deploy/windows_client/`

Ce dossier a été créé par `agent_v0/deploy_windows.py` comme staging de build
et s'est désynchronisé. Il a été supprimé en avril 2026 — le build officiel
passe désormais par `deploy/build_package.sh` qui lit directement
`agent_v0/agent_v1/`.