LoopX — le guide complet

août 2026 · 6 min de lecture

LoopX — le guide complet

Le repo : https://github.com/huangruiteng/loopx Licence : MIT (gratuit, open source)

1. C'est quoi, en une phrase

Claude Code, c'est l'ouvrier. LoopX, c'est la tour de contrôle au-dessus.

LoopX n'exécute rien. Il ne lance aucun agent. Il garde l'état de ton objectif entre chaque tour : ce que tu veux, ce qui est hors périmètre, ce qui a été validé, ce qui attend une décision de toi, et combien tu as déjà dépensé.

C'est ce qu'on appelle du loop engineering.

2. Le problème qu'il règle

Les tâches courtes échouent parce que le modèle fait un mauvais choix. Les loops longs échouent différemment : l'état dérive.

Concrètement, au bout de quelques heures ton agent ne sait plus répondre à ça :

C'est quoi l'objectif exact, et qu'est-ce qui est explicitement hors sujet ?
Qu'est-ce qui fait autorité : ta dernière décision, un doc, un résultat de test ?
Qu'est-ce que le tour précédent a réellement fait, et comment ça a été vérifié ?
La prochaine action, c'est à toi ou à lui ?
Ce que tu as dit hier, ça survit comment au tour de ce soir ?

Tant que ces réponses vivent dans la fenêtre de contexte, elles se dégradent. Et ça ne plante pas franchement : ça continue de tourner sur une version légèrement déformée de ce que tu voulais. C'est ça le piège.

3. Est-ce que t'en as besoin ? (lis ça avant d'installer)

Tu n'en as pas besoin si :

ton loop dure moins d'une session
tu bosses seul, sur un seul projet, en restant devant
t'as juste envie de tester un truc vite fait

Dans ces cas-là, /loop et une routine Claude Code suffisent largement. LoopX serait de la complexité pour rien.

Ça devient utile si :

ton objectif s'étale sur plusieurs jours ou plusieurs semaines
t'as des tours automatiques récurrents (heartbeat, monitoring)
plusieurs agents touchent le même repo et se marchent dessus
il y a des décisions qui doivent rester humaines (validation, mise en prod, publication)
tu veux pouvoir auditer avant de lâcher plus d'autonomie
tu attends une preuve (un benchmark, un test) avant de continuer

4. Prérequis

Python 3.11 ou plus
curl et tar
macOS ou Linux (shell)
Node.js seulement si tu veux le dashboard

Le package Python n'a aucune dépendance externe à la stdlib. C'est léger.

5. Installation

Option A — tu laisses ton agent le faire (le plus simple)

Ouvre Claude Code dans ton projet et colle ça :

Installe et connecte LoopX pour ce projet, de bout en bout. Ne t'arrête pas à
un plan. Si `loopx` n'est pas présent, installe-le avec l'installeur GitHub
officiel (sans clone). Ensuite lance doctor, connecte ou bootstrap ce repo,
assure-toi que l'état local LoopX est bien ignoré par git, et affiche-moi
le goal id, le user gate actuel, le todo agent prioritaire et la prochaine
action safe avant de bosser plus longtemps.

Option B — à la main

curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor

Le clone git n'est utile que si tu veux contribuer au projet. Pour un usage normal, reste sur l'installeur.

6. Connecter ton projet

cd /chemin/vers/ton-projet

loopx bootstrap \
  --goal-id mon-projet-goal \
  --objective "Faire avancer ce projet par segments bornés et vérifiés." \
  --goal-doc GOAL.md

La connexion est réussie quand :

loopx doctor passe
le projet a un .loopx/registry.json
le projet a un .codex/goals/<goal-id>/ACTIVE_GOAL_STATE.md
loopx status t'affiche qui doit agir ensuite
l'état local est ignoré par git, pas commité

7. Les commandes du quotidien

Le loop de tous les jours est volontairement minuscule :

loopx status                                    # qui doit agir maintenant
loopx history --goal-id mon-projet-goal         # ce qui s'est passé
loopx quota should-run --goal-id mon-projet-goal # est-ce qu'un tour auto doit tourner

Ajouter une tâche à l'agent :

loopx todo add --goal-id mon-projet-goal --role agent \
  --text "Lance la prochaine tranche de validation bornée."

Préparer une revue / rafraîchir l'état :

loopx review-packet --goal-id mon-projet-goal
loopx refresh-state --goal-id mon-projet-goal

Tu n'es pas censé diagnostiquer LoopX à la main. Si un truc coince, demande à ton agent :

Diagnostique LoopX pour ce projet de bout en bout. Ne me demande pas de lancer
des commandes shell. Lance loopx diagnose, dis-moi si le projet peut
s'auto-piloter, ce qui le bloque, la question exacte à me poser s'il y en a une,
et ce que tu vas faire ensuite.

8. Les tours automatiques (heartbeat)

C'est le cœur du truc : un tour automatique vérifie son quota avant de bosser, et ne dépense qu'une fois après une écriture validée.

loopx quota should-run --goal-id mon-projet-goal
loopx heartbeat-prompt --thin --goal-id mon-projet-goal
loopx quota spend-slot --goal-id mon-projet-goal --slots 1 --source heartbeat --execute

Règles à respecter :

Pas de dépense sur un skip silencieux, un échec de préflight ou un dry-run.
Si le quota renvoie un gate_prompt ou un operator_question, le tour doit te poser cette question concrètement.
S'il reste des todos utilisateur ouverts, le tour n'a pas le droit de dire "rien à faire côté user".

9. Le dashboard (optionnel, local)

loopx serve-status --global-registry --port 8766 --limit 80
cd ~/loopx/apps/dashboard && npm install && npm run dev

Tu y vois tes projets, les todos, les décisions en attente, les lanes d'agents et les preuves — sans lire des logs bruts.

Il est volontairement conservateur : le CLI reste la source de vérité, et l'écriture depuis le navigateur demande un opt-in local explicite.

10. Avant de publier quoi que ce soit

LoopX scanne la frontière public / privé :

loopx check \
  --scan-path README.md \
  --scan-path docs/ \
  --scan-path examples/

Et surtout : ne commite jamais .loopx/, .codex/goals/, un ACTIVE_GOAL_STATE.md vivant, ou tes traces de benchmark.

11. Ce qu'il faut savoir avant de se lancer

Je préfère être clair plutôt que de te vendre du rêve :

C'est jeune. Le projet l'assume lui-même dans son README. C'est un socle local utile, pas une plateforme d'agents finie. C'est exactement pour ça que t'es en avance — mais attends-toi à des aspérités.

Ce n'est pas un contrôleur de prod autonome. C'est un substrat de coordination local. La propriété du projet et les permissions dangereuses restent chez toi.

C'est pensé Codex-first. L'automatisation la plus poussée (les heartbeats) est câblée pour Codex. Avec Claude Code, Cursor ou un autre agent, ça marche à condition que ton agent ait au moins un point d'accroche : exécution shell, commande de tâche, hook d'automatisation, ou son propre scheduler. Sinon LoopX suit quand même l'état du projet, mais c'est toi qui lances les commandes.

Une partie est reproductible à la main. Avec un bon fichier d'instructions, un fichier d'état que tu maintiens et deux hooks, tu refais une bonne partie du comportement. LoopX, c'est cette pratique formalisée avec un CLI et un dashboard — pour ne pas la réinventer à chaque projet.

12. Pour aller plus loin

Getting started : docs/guides/getting-started.md
Architecture : docs/architecture.md
Contrat de quota : docs/quota-allocation.md
Frontière public/privé : docs/public-private-boundary.md
Cas d'usage démontrés : docs/showcases/README.md
Vitrine en ligne : https://huangruiteng.github.io/loopx/frontstage/

"Keep the loop moving. Keep the judgment human."