Décomposer la boucle agent de Codex

• Codex CLI est conçu comme un agent capable d’effectuer des modifications logicielles de haute qualité de manière sûre et efficace dans un environnement local
• Sa structure centrale, la boucle agent (agent loop), relie de façon cyclique l’entrée utilisateur, le raisonnement du modèle et les appels d’outils afin d’accomplir des tâches utiles
• Lors de cette boucle, la composition des prompts, la gestion de la fenêtre de contexte et le cache de prompts jouent un rôle clé pour les performances et la stabilité
• Codex communique avec le modèle via la Responses API ; chaque requête est constituée d’une charge utile JSON complète, ce qui maintient un fonctionnement sans état (stateless)
• Cette architecture permet des fonctionnalités avancées comme Zero Data Retention (ZDR), le cache de prompts et la compaction automatique, et sert de base à la conception d’agents à grande échelle

---

Vue d’ensemble de la boucle agent de Codex

• Codex CLI fonctionne autour d’une structure en boucle qui orchestre les interactions entre l’utilisateur, le modèle et les outils
  • il reçoit l’entrée de l’utilisateur et construit le prompt à transmettre au modèle
  • si le modèle génère une réponse ou demande un appel d’outil (tool call), l’agent l’exécute puis ajoute le résultat au prompt
  • lorsqu’aucun nouvel appel d’outil n’est demandé et que le modèle produit un message assistant, un tour se termine
• Chaque tour fait partie d’une conversation ; les messages précédents ainsi que l’historique des appels d’outils sont tous inclus dans le prompt de la requête suivante
• Comme la longueur du prompt est limitée par la fenêtre de contexte (context window) du modèle, Codex doit la gérer activement

Structure de communication entre Responses API et Codex

• Codex CLI envoie des requêtes HTTP à la Responses API pour l’inférence du modèle
  • le point d’accès API varie selon la configuration et peut être utilisé avec OpenAI, ChatGPT, Azure ou des environnements locaux (LM Studio, Ollama, etc.)
• Les requêtes API sont structurées sous forme de charge utile JSON, avec notamment les champs suivants
  • messages system/developer : définissent le contexte de base du modèle
  • instructions : liste des outils que le modèle peut appeler
  • tools : définitions des outils fournis par Codex CLI, la Responses API ou l’utilisateur (serveur MCP, etc.)
  • input : liste de messages incluant l’historique de la conversation et les informations d’environnement
• Codex lit automatiquement la configuration ~/.codex/config.toml ainsi que des fichiers tels que AGENTS.md et skills dans le projet afin d’injecter les consignes utilisateur et les informations d’environnement

Composition des prompts et traitement des événements

• Codex structure chaque message comme un objet JSON (type, role, content) puis l’envoie à la Responses API
• Le serveur génère ensuite le prompt du modèle à partir de ce JSON et renvoie la réponse sous forme de flux SSE (Server-Sent Events)
  • l’événement response.output_text.delta est utilisé pour la sortie en streaming
  • l’événement response.output_item.added est ajouté au champ input de la requête suivante afin de poursuivre la boucle
• Le système est conçu pour que l’ancien prompt soit un préfixe exact du nouveau, ce qui permet d’exploiter le cache de prompts (prompt caching)

Optimisation des performances : cache et architecture sans état

• Codex n’utilise pas previous_response_id, ce qui lui permet de conserver une structure de requêtes entièrement sans état (stateless)
  • cela rend possible la prise en charge des clients Zero Data Retention (ZDR) et une minimisation de la conservation des données
• Le cache de prompts réutilise le même préfixe pour linéariser le coût d’échantillonnage
  • un hit de cache ne se produit qu’en cas de correspondance exacte du préfixe du prompt
  • une modification de la liste d’outils, du modèle, des paramètres de sandbox ou du répertoire de travail provoque un cache miss
• Les changements dynamiques des outils MCP peuvent faire perdre le cache ; Codex reflète donc ces changements en insérant de nouveaux messages

Gestion de la fenêtre de contexte et compaction automatique

• Quand la conversation s’allonge, une compaction de la conversation est effectuée afin d’éviter de dépasser la fenêtre de contexte
  • au départ, un résumé manuel était réalisé via la commande /compact, mais aujourd’hui l’endpoint /responses/compact de la Responses API est utilisé automatiquement
  • cet endpoint renvoie des éléments de type=compaction ainsi qu’un encrypted_content chiffré afin de préserver la compréhension du modèle
• Codex exécute automatiquement la compaction dès que auto_compact_limit est dépassé, afin d’assurer la continuité de la conversation

Conclusion et orientations à venir

• La boucle agent de Codex constitue la structure centrale qui intègre inférence du modèle, appels d’outils, cache et gestion du contexte
• Cette architecture permet une conception d’agents performante, sans état et centrée sur la sécurité
• Les prochains articles aborderont plus en détail la structure interne de Codex, notamment l’architecture CLI, l’implémentation de l’usage des outils et le modèle de sandboxing

[GN⁺]

Réactions sur Hacker News

• Le meilleur point de cet article de blog, c’est qu’il n’a rien de surprenant. Codex CLI est open source, donc on peut examiner son fonctionnement interne sans faire de reverse engineering
  La communication d’Eric Traut, connu pour Pyright, est également excellente. Il participe activement aux issues et aux PR
  Dépôt GitHub

  • J’ai vraiment été surpris quand Codex CLI est passé en open source l’an dernier. Il inclut aussi codex-rs, porté de TypeScript vers Rust, ce qui est très utile pour quiconque veut comprendre comment fonctionne un agent de code
    J’ai moi-même contribué à quelques améliorations du CLI, et je suis régulièrement les releases et les PR pour approfondir mes connaissances
  • Beaucoup de gens semblent ignorer que Claude Code est un logiciel propriétaire
  • Franchement, je pense que si Claude Code n’est pas open source, c’est parce que la qualité du code est tellement mauvaise qu’ils en auraient honte. Je paie un abonnement à 200 dollars par mois, mais le CLI est lent et plante souvent, donc je vais probablement résilier bientôt
  • Je me demande si Codex CLI est simplement un frontend qui appelle une logique distante, ou s’il peut fonctionner entièrement hors ligne. J’aimerais aussi savoir s’ils fournissent les poids sous licence FLOW et s’ils documentent le processus de build

• Ce qui est intéressant, c’est que la compaction est effectuée sous forme de « message chiffré qui préserve la compréhension latente du modèle »
  Codex utilise automatiquement cet endpoint pour réduire efficacement le contexte de conversation dès que auto_compact_limit est dépassé

  • L’endpoint de compaction de Codex est parmi les meilleurs du secteur. Celui de Claude est proche du pire
  • Je me demande s’il est possible d’utiliser l’endpoint compactor de façon indépendante. Nous avons notre propre boucle d’agent spécialisée pour notre domaine, et celui de Codex serait peut-être plus performant que notre système de compression interne
  • J’aimerais savoir si cette fonctionnalité fonctionne aussi avec d’autres modèles que ceux d’OpenAI

• En examinant l’intérieur de Codex, ce qui m’a surpris, c’est que les tokens de reasoning sont conservés dans la boucle d’appels d’outils de l’agent, mais supprimés à chaque changement de tour utilisateur
  On peut donc garder le contexte sur plusieurs tours, mais une partie du contexte peut être perdue entre des requêtes utilisateur liées
  Je fais donc consigner au modèle sa progression, son plan ou ses informations de débogage dans un fichier Markdown, qui sert alors de sorte de snapshot entre plusieurs fenêtres de contexte

  • Cela dépend du chemin API. Avec Chat completions, c’est comme tu le décris, mais avec l’API responses v1, c’est l’inverse : les tokens de reasoning sont conservés lors de l’envoi du message suivant. En revanche, le mode xhigh consomme le contexte beaucoup plus vite
  • Ne pas conserver les tokens de reasoning est peut-être au contraire une bonne décision. Sinon, un contexte invisible pour l’utilisateur risque de s’accumuler, avec un risque de désalignement entre la compréhension du modèle et celle de l’utilisateur
  • J’ai créé une Codex Reflect Skill qui prend en compte les conversations passées et construit le contexte via des sessions parallèles
    Dépôt GitHub
  • Enregistrer ce journal avec le code est pratique, mais cela pose problème en équipe ou quand on travaille sur plusieurs branches en même temps. Pour ma prochaine expérimentation, je compte séparer ces données dans un daemon avec stockage externe, accessible via un client CLI
  • J’utilise souvent agent-shell dans emacs, qui enregistre tout l’historique de conversation. Du coup, je peux facilement dire « réfère-toi à la conversation précédente ». Comme les logs sont gérés par emacs et non par l’agent, il n’y a pas à craindre d’omissions

• Ce que je veux vraiment dans Codex, c’est une fonctionnalité de checkpoints façon Copilot. Il existe quelques issues GitHub à ce sujet (#2788, #3585), mais cela ne semble pas être une priorité pour l’équipe

  • Gemini CLI a déjà cette fonctionnalité
  • L’équipe Codex dit définir ses priorités selon le nombre d’upvotes en emoji sur GitHub. Si une fonctionnalité vous intéresse, il faut vraiment aller l’upvoter

• Je me demande comment ils gèrent le maintien du contexte dans les conversations multi-tours lorsqu’ils agrègent les instructions utilisateur dans la boucle d’agent. J’aimerais aussi savoir s’ils ont testé des techniques d’ajustement dynamique quand les demandes utilisateur évoluent

• J’aime bien Codex, mais je le trouve plus lent que l’interface web de ChatGPT. Pour échanger rapidement des idées, je reste plus productif en faisant du copier-coller dans le web
  Codex se met souvent à modifier le mauvais code, ce qui rend la boucle de feedback lente et frustrante. Cela dit, quand il fonctionne bien, il est excellent. J’espère qu’un jour il sera aussi rapide que le web tout en permettant le travail en local

  • L’interface web de ChatGPT Plus ne propose pas le mode xhigh reasoning effort du modèle 5.2

• Rien de particulièrement nouveau, mais cela restait un article utile. J’aimerais qu’il soit plus facile de réfléchir a posteriori sur les boucles ou l’historique dans les CLI de coding agent. J’ai essayé d’interroger l’historique de chat via MCP, mais c’est peu pratique car il faut le préciser explicitement. L’apprentissage continu pourrait résoudre ce genre de problème

• On peut aussi observer ce comportement via la télémétrie OTEL. J’utilise souvent codex exec en mode headless, mais le support de télémétrie intégré est insuffisant, ce qui complique le débogage
  J’ai donc créé moi-même codex-plus. Il reprend fidèlement l’interface de codex exec, tout en étant implémenté sur le SDK TypeScript, et exporte après exécution les logs de session vers un collecteur OpenTelemetry distant pour analyse avec codex-plus-log-viewer

• La partie qui décrit les skills m’a paru étrange
  Lien vers le code concerné
  Je me demande pourquoi ils n’exposent pas simplement les fichiers directement, au lieu de laisser le modèle les demander comme s’il s’agissait de fichiers ordinaires

  • C’est justement tout l’intérêt des skills. Cela permet de n’ouvrir que les fichiers pertinents, afin de réduire l’usage de la fenêtre de contexte

• Je me demandais si quelqu’un avait vraiment utilisé Codex CLI sérieusement. J’ai testé l’extension Codex pour VSCode, Gemini CLI et Claude Code CLI, et tous avaient des performances catastrophiques.
  En revanche, le nouveau Codex CLI réécrit en Rust est incroyable côté performances. L’UX est excellente, et même les détails comme les raccourcis clavier sont soignés. Theo disait qu’il aurait fallu se concentrer sur l’amélioration du modèle plutôt que sur l’optimisation du CLI, mais après l’avoir essayé, je ne peux pas du tout être d’accord

  • J’ai l’impression que Codex CLI est bien meilleur que Claude Code. Il suit précisément les instructions et n’adopte pas de comportements indésirables. Avec un abonnement mensuel à 20 dollars, on peut utiliser très confortablement le modèle 5.2 codex high. Je travaille sur des modèles SSL de bioacoustique
  • OpenCode est aussi plus rapide et plus stable que les autres CLI. J’utilise davantage Codex ces derniers temps, et je vais probablement résilier Claude Pro. Le fait qu’OpenAI prenne officiellement en charge OpenCode est un point très attractif. C’est bien d’avoir plusieurs options concurrentes aujourd’hui
  • Codex fournit des résultats cohérents à plus de 95 % sur la plupart des tâches de code. En revanche, sur des tâches non structurées comme la conversation ou l’écriture d’histoires, il peut produire des sorties absurdes. Il m’est aussi arrivé de le voir partir en boucle pendant un git rebase. J’ai essayé Aider, mais je l’ai trouvé quasiment inutile
  • L’efficacité mémoire et CPU de Codex CLI est excellente. Et comme c’est open source, on peut vérifier directement comment il fonctionne. Les propos de Theo continuent de me déranger
  • Le problème de Codex, c’est qu’il n’a toujours pas de support des hooks. J’ai créé un outil qui réduit de 30 % la consommation de tokens de l’agent grâce aux hooks. Les hooks permettent de corriger en temps réel les comportements inefficaces de l’agent
    Article lié : Scribe Swebench Benchmark