Passer de Claude Code à Codex sans perdre le contexte

Trois raisons opérationnelles motivent la bascule : la limite de contexte atteinte sur Claude Code (200 000 tokens Sonnet, saturés en 3-4 heures de refactor), le coût des tokens de sortie sur les longues sessions, et la spécialisation de Codex CLI sur l'exécution de tâches shell chaînées via son mode --full-auto. Beaucoup d'équipes utilisent Claude Code pour l'exploration architecturale, puis Codex pour l'implémentation mécanique et les tests.

La bascule échoue quand le nouvel agent recommence l'analyse. Codex ignore par défaut les fichiers CLAUDE.md, MEMORY.md et les JSONL de session stockés dans ~/.claude/projects/. Sans pont explicite, l'utilisateur recolle manuellement 40 minutes de contexte, se trompe sur trois décisions et casse le worktree partagé. Le handoff structuré résout ce problème en 2 minutes plutôt qu'en 40.

Le format cible tient en cinq blocs : objectif courant, dépôt et branche, décisions verrouillées, tests actuels, prochaines actions. Cinq blocs, moins de 2 000 tokens, aucune ambiguïté sur qui reprend quoi.

Étape 1 — Geler l'état Git. Dans le terminal Claude Code, exécuter git status puis git stash push -u -m "handoff-$(date +%s)" si des fichiers sont modifiés. Cette commande sauvegarde même les fichiers non trackés (-u) et empêche Codex d'écraser du travail en cours. Noter le hash retourné.

Étape 2 — Synchroniser la session dans Tramya. Lancer tramya sync --project $(basename $PWD). Le compagnon lit le JSONL Claude Code, extrait objectif, décisions et état de branche via l'API get_project_context. La date de dernière lecture s'affiche pour confirmer que rien n'a été oublié.

Étape 3 — Générer le handoff. Appeler tramya handoff --to codex --format markdown > HANDOFF.md. Le fichier produit fait typiquement 1 200 tokens : objectif, branche, worktree, 3 à 8 décisions récentes, résultat de pytest ou npm test, et les 3 prochaines actions ordonnées.

Étape 4 — Lancer Codex dans le même worktree. Exécuter codex --model gpt-5-codex --config-file HANDOFF.md. Codex charge le brief avant le premier tour et enchaîne sur les actions listées, avec accès aux mêmes fichiers que Claude Code.

La règle est simple : un worktree Git par agent actif. Deux CLIs qui écrivent dans le même dossier corrompent les caches (.claude/, .codex/) et provoquent des merge conflicts sur des fichiers générés. La commande git worktree add ../projet-codex feature/refactor-auth crée un dossier frère qui partage l'historique Git mais isole les fichiers de travail.

Concrètement, Claude Code reste dans ~/projects/tramya sur la branche main. Codex reprend dans ~/projects/tramya-codex sur feature/refactor-auth. Les deux voient l'intégralité des commits, mais leurs modifications non commitées n'interfèrent pas. Le handoff Tramya inclut automatiquement le chemin absolu du worktree cible, donc Codex ne se trompe pas de dossier au lancement.

À la fin de la session Codex, exécuter git worktree remove ../projet-codex une fois la branche mergée. Ne jamais supprimer le dossier à la main avec rm -rf : le fichier .git/worktrees/ conserverait une référence morte qui bloquerait le prochain worktree add sur le même nom.

1. « Codex ne voit pas mon AGENTS.md ». Codex CLI cherche le fichier à la racine du dépôt Git, pas dans le sous-dossier courant. Exécuter cd $(git rev-parse --show-toplevel) avant codex, ou créer un lien symbolique ln -s CLAUDE.md AGENTS.md pour réutiliser les instructions déjà écrites pour Claude.

2. « fatal: not a git repository ». Le worktree cible n'a pas de dossier .git lisible. Vérifier avec git worktree list. Si le worktree apparaît « prunable », le régénérer via git worktree repair.

3. « Codex répète l'analyse déjà faite ». Le handoff n'a pas été chargé. Vérifier que HANDOFF.md apparaît dans le premier prompt système : codex --show-context | head -50. Si absent, relancer avec --config-file en chemin absolu, pas relatif.

4. « MCP tool not found: get_project_context ». Le serveur MCP Tramya n'est pas déclaré dans ~/.codex/config.toml. Ajouter la section [mcp_servers.tramya] avec la commande de lancement, puis relancer Codex.

5. « Merge conflict dans .claude/settings.local.json ». Ce fichier n'a rien à faire dans Git. L'ajouter à .gitignore, exécuter git rm --cached .claude/settings.local.json, puis committer.