afk.sh

À propos du projet

Travailler avec un agent de code se heurte vite à la même limite : il faut rester devant. afk.sh est la boucle qui manque autour. On lui donne une liste de tickets, il ouvre une session par ticket, la laisse travailler, vérifie le résultat, pousse la branche et étiquette le ticket. Entre le lancement et la relecture, on dort.

Le nom vient de là : away from keyboard.

Aucun modèle dans l'orchestrateur. Il ne réfléchit pas, il ordonne, lance, vérifie, pousse et étiquette. Toute l'intelligence reste dans les sessions qu'il pilote, ce qui le rend lisible et prévisible.

Le principe

un ticket  =  une session neuve  =  un worktree  =  une PR vérifiée

Chaque ticket part d'un contexte vierge, dans son propre worktree git, ce qui évite qu'une session pollue la suivante et permet de tout lancer en parallèle.

Ce qu'il fait

Ordonnancement : lit les dépendances entre tickets (« bloqué par ») et en déduit les vagues exécutables ; -n affiche le plan sans rien lancer
Parallélisme : plusieurs sessions simultanées partout où le graphe le permet
Porte de vérification : chaque ticket n'est « fini » que si la commande de vérification du dépôt passe, déclarée dans un .afk.env versionné à côté du code
Reprise : un ticket qui échoue est rejoué une fois, en session neuve plutôt qu'en tentant de rattraper la précédente
Attente de CI après ouverture de la PR, puis étiquetage selon le résultat
Passe d'intégration en fin de run : les branches vertes sont combinées et revérifiées ensemble

Le piège du faux vert

La leçon la plus utile du projet ne vient pas du code mais d'un run réel. Un cache de build peut rendre une porte de vérification creuse : si la clé de cache ne tient compte que des fichiers suivis par git, un worktree qui n'a pas produit un fichier généré présente la même empreinte que celui qui l'a produit. Le cache répond, les logs sont rejoués, rien n'est réellement exécuté, et la porte affiche un succès sans avoir compilé une ligne.

Huit tickets sont passés au vert sur un défaut que seule la passe d'intégration a vu : elle présentait une combinaison de contenus jamais rencontrée, donc un vrai calcul. D'où la séparation entre la porte des tickets et celle de l'intégration, et une règle simple : le nombre d'entrées servies par le cache est une ligne de sécurité, pas une statistique de performance.

Testé sans consommer un seul appel

Le script embarque deux harnais : l'un teste les analyseurs (parsing des tickets, des labels, des dépendances), l'autre l'orchestrateur complet avec l'agent et l'API GitHub bouchonnés. Le comportement se vérifie donc en quelques secondes, sans réseau et sans dépenser un jeton.