Démarrer avec Stitch 2.0

Stitch 2.0 est une CLI local-first. Il lit la config CI déjà dans votre dépôt, exécute les mêmes jobs sur votre machine et passe tout échec à un agent IA (Claude Code ou Codex) pour correction. Ce post est la version cinq minutes de la documentation.

Prérequis

• Un dépôt avec un fichier .gitlab-ci.yml ou .github/workflows/*.yml. Stitch lit le pipeline que vous avez déjà.
• Node 20 ou plus récent (ou Bun, si c’est ce que vous utilisez).
• Claude Code ou Codex installé et authentifié sur votre machine. Vous l’avez déjà si vous utilisez l’un de ces outils au quotidien.

Voilà toute la liste de dépendances. Stitch n’a pas besoin de clé API, d’image Docker ou de token de plateforme. Il tourne en tant que vous, sur votre machine, avec l’agent déjà connecté.

Installer et lancer

Il n’y a pas d’étape d’installation. Le package est publié sur npm. Lancez-le directement :

npx stitch-agent run claude

Ou, si vous préférez Codex :

npx stitch-agent run codex

Au premier lancement, Stitch détecte quelle config CI vous avez, la parse et vous montre les jobs qu’il s’apprête à lancer. Les jobs d’infrastructure (deploy, publish, release, pushes d’images) sont filtrés automatiquement. Les jobs de vérification (lint, typecheck, test, build) sont ceux qui tournent en local.

Le terminal bascule en TUI interactif. Vous verrez :

• Un stepper de pipeline en haut, qui avance à travers les phases parse, execute, fix.
• Une table de jobs au milieu, avec le statut en direct par job.
• Un panneau driver sur le côté, qui montre ce que fait l’agent quand une correction est en cours.

Vous pouvez regarder ou partir. Stitch s’arrête au premier pipeline complet vert, au plafond de tentatives (trois par job par défaut) ou à la première chose qu’il décide de vous escalader.

Ce qui se passe quand un job échoue

Stitch passe le job en échec à votre agent avec un court prompt et le contexte pertinent. L’agent fait son truc : il lit les fichiers dans l’erreur, il tente une correction, il dit à Stitch de relancer le job. Stitch valide en relançant réellement le même job. Si la relance passe, la tentative compte comme un fix. Sinon, l’agent réessaie, jusqu’au plafond par job.

La boucle est bornée volontairement. Si trois tentatives ne débouchent pas sur un correctif, Stitch s’arrête et vous montre l’état : le dernier diagnostic, le dernier patch, le dernier log. Vous prenez le relais avec tout le contexte.

Commit et push

Quand un cycle de correction se termine avec tous les jobs en vert, Stitch peut commiter et pousser le résultat. Ça n’arrive que si deux conditions sont vraies :

1. Vous étiez sur une branche propre quand Stitch a démarré. S’il y avait des changements non commités, Stitch laisse l’arbre de travail tranquille. Votre travail en cours n’est jamais touché.
2. Vous avez demandé l’auto-commit. Désactivé par défaut. Le flag est --auto-commit.

C’est volontairement conservateur. La façon la plus rapide de perdre confiance dans un outil comme Stitch, c’est qu’il écrase votre travail local. On préfère que vous l’activiez explicitement plutôt que vous vous demandiez ce qui s’est passé.

Mode watch

Pour les boucles d’itération serrées, Stitch peut rester lancé et re-vérifier à la modification de fichier :

npx stitch-agent run claude --watch

En mode watch, sauvegarder un fichier déclenche une relance des jobs affectés. Vous éditez, vous sauvegardez, vous voyez vert ou rouge dans la TUI en quelques secondes, sans quitter votre éditeur. Ça remplace l’habitude “je pousse pour voir si la CI est contente” par “je sauvegarde et je vois”.

Configuration, si vous en voulez

Zéro config est le défaut et ça couvre la plupart des dépôts. Si vous voulez ajuster le comportement, déposez un .stitch.yml à la racine du dépôt :

max_attempts: 3
auto_fix: [lint, format, simple_types, config_ci]
escalate: [logic_errors, breaking_changes, dependency_conflicts]

Vous n’avez pas besoin de ce fichier pour utiliser Stitch. Il existe pour les équipes qui veulent une politique explicite.

Ce que Stitch n’est pas

Stitch ne remplace pas votre CI. Le pipeline distant tourne toujours au push. Stitch vous donne juste une version plus rapide, locale et assistée par IA de la même chose, pour que vous arriviez au push avec de la confiance plutôt qu’avec de l’espoir.

Stitch ne s’entraîne pas sur votre code. Il ne rentre pas à la maison. Il n’y a pas de télémétrie à désactiver parce qu’il n’y a rien qui rapporte quelque part. Les logs et les correctifs restent en local, sauf si vous configurez explicitement un canal de notification.

Stitch n’a pas besoin d’abonnement pour lui-même. Le seul service payant dans la boucle est l’agent (Claude Code ou Codex), et c’est facturé sur le compte que vous avez déjà.

Pour aller plus loin

Le dépôt est sur GitHub à x24labs/stitch. Les issues s’y suivent. Le package npm est stitch-agent. Le reste est dans le code et dans les posts précédents de cette série, qui expliquent pourquoi v2 a la tête qu’elle a.

Si vous l’essayez et quelque chose casse, ouvrez une issue. L’intérêt du local-first, c’est que vous avez tout ce qu’il faut pour reproduire le problème sous les yeux.