Quand on utilise Codex au quotidien, en ligne de commande ou depuis un IDE comme VS Code, un dossier local .codex est créé dans l’environnement utilisateur. Avec le temps, ce dossier peut contenir des historiques de conversations, des sessions archivées, des logs, des fichiers SQLite, du cache, des plugins, des skills, ainsi que des fichiers de configuration.

Ce dossier peut donc grossir rapidement, surtout après plusieurs semaines d’utilisation sur plusieurs projets. Le nettoyer permet de récupérer de l’espace disque, de supprimer les traces locales d’anciennes sessions et de repartir sur une base plus propre, sans forcément désinstaller Codex ni perdre sa configuration.

L’objectif de cette documentation est de comprendre ce que contient le dossier .codex, quoi supprimer sans risque majeur, quoi conserver, et comment effectuer un nettoyage propre sur Windows, Linux, macOS ou WSL2.

1. Où se trouve le dossier .codex ?

L’emplacement exact dépend de l’environnement dans lequel Codex est lancé.

Linux, macOS et WSL2

Sous Linux, macOS ou WSL2, le dossier est généralement situé ici :

~/.codex

Exemple sous Linux ou WSL2 :

/home/<utilisateur>/.codex

Exemple sous macOS :

/Users/<utilisateur>/.codex

Windows

Sous Windows, si Codex est utilisé directement depuis l’environnement Windows, le dossier peut se trouver dans le profil utilisateur :

$env:USERPROFILE\.codex

Ce qui correspond généralement à :

C:\Users\<Utilisateur>\.codex

Cas particulier de WSL2

Si Codex est utilisé dans WSL2, même avec VS Code ouvert depuis Windows, le dossier actif est généralement celui de la distribution Linux :

~/.codex

Par exemple :

/home/<utilisateur>/.codex

Il faut donc bien distinguer :

C:\Users\<Utilisateur>\.codex

et :

/home/<utilisateur>/.codex

Ce sont deux environnements différents.

2. Pourquoi nettoyer le dossier .codex ?

Nettoyer .codex peut être utile pour plusieurs raisons :

  • supprimer l’historique local des anciennes conversations ;
  • éviter de conserver des traces de commandes ou de chemins de projets ;
  • réduire l’espace disque utilisé ;
  • supprimer des logs techniques volumineux ;
  • repartir sur une base plus propre après des tests ;
  • limiter le mélange de traces entre plusieurs projets ;
  • corriger certains comportements étranges liés à un état local trop ancien.

Attention toutefois : il ne faut pas supprimer tout le dossier .codex sans réfléchir. Certains fichiers contiennent l’authentification, la configuration ou des paramètres utiles.

L’idée n’est donc pas de faire :

rm -rf ~/.codex

mais plutôt de nettoyer les bons fichiers.

3. Vérifier la taille du dossier .codex

Avant de supprimer quoi que ce soit, il est utile de mesurer la taille du dossier.

Taille globale

Sous Linux, macOS ou WSL2 :

du -sh ~/.codex

Exemple de sortie :

431M    /home/user/.codex

Sous Windows PowerShell :

Get-ChildItem "$env:USERPROFILE\.codex" -Recurse -Force |
    Measure-Object -Property Length -Sum

Détail par sous-dossier

Sous Linux, macOS ou WSL2 :

du -h ~/.codex/ --max-depth=2

Cette commande permet de voir rapidement quels sous-dossiers occupent le plus d’espace.

Afficher les plus gros fichiers

Pour identifier les fichiers les plus lourds :

du -ah ~/.codex | sort -h | tail -50

Cette commande est souvent la plus utile, car de gros fichiers peuvent se trouver directement à la racine de .codex.

On peut aussi afficher uniquement les fichiers situés à la racine :

find ~/.codex -maxdepth 1 -type f -exec ls -lh {} \;

4. Comprendre les principaux fichiers et dossiers

Le contenu exact peut varier selon les versions, les extensions installées et le mode d’utilisation. Voici les éléments que l’on peut rencontrer fréquemment.

sessions/

Le dossier sessions/ contient les sessions actives ou récentes. Il peut être organisé par année, mois et jour, avec des fichiers .jsonl.

Exemple :

~/.codex/sessions/2026/04/23/rollout-....jsonl

Ces fichiers peuvent contenir des échanges détaillés avec Codex.

Pour supprimer les sessions actives :

rm -rf ~/.codex/sessions/*

archived_sessions/

Le dossier archived_sessions/ peut contenir d’anciennes sessions archivées.

Ces fichiers peuvent conserver :

  • le dossier courant du projet ;
  • le nom de branche Git ;
  • des extraits de conversation ;
  • des appels d’outils ;
  • des sorties de commandes ;
  • des chemins de fichiers ;
  • du contexte technique.

Pour les supprimer :

rm -rf ~/.codex/archived_sessions/*

history.jsonl

Le fichier history.jsonl peut contenir un historique court des anciennes interactions.

Pour le vider sans supprimer le fichier :

: > ~/.codex/history.jsonl

Sous PowerShell :

Clear-Content "$env:USERPROFILE\.codex\history.jsonl"

session_index.jsonl

Le fichier session_index.jsonl peut contenir un index des sessions connues par Codex, parfois avec des titres de conversations.

Pour le vider :

: > ~/.codex/session_index.jsonl

Sous PowerShell :

Clear-Content "$env:USERPROFILE\.codex\session_index.jsonl"

logs_*.sqlite

Certains fichiers SQLite peuvent devenir volumineux, par exemple :

logs_2.sqlite
logs_2.sqlite-wal
logs_2.sqlite-shm

Ces fichiers correspondent à une base SQLite de logs internes.

Le fichier principal est :

logs_2.sqlite

Les fichiers associés sont :

logs_2.sqlite-wal
logs_2.sqlite-shm

Le suffixe -wal correspond au journal d’écriture SQLite en mode Write-Ahead Logging. Le suffixe -shm correspond au fichier de mémoire partagée utilisé par SQLite pour coordonner les accès.

Ces fichiers peuvent contenir des traces techniques :

  • événements internes ;
  • erreurs ;
  • appels d’outils ;
  • chemins de projets ;
  • commandes exécutées ;
  • sorties terminal ;
  • contexte d’exécution.

Ils ne sont pas nécessairement l’historique conversationnel principal, mais ils peuvent contenir des informations issues des sessions passées.

Il est recommandé de fermer VS Code, l’extension Codex, Continue ou toute session Codex avant de les supprimer.

Commande de suppression :

rm -f ~/.codex/logs_*.sqlite ~/.codex/logs_*.sqlite-wal ~/.codex/logs_*.sqlite-shm

Sous PowerShell :

Remove-Item "$env:USERPROFILE\.codex\logs_*.sqlite*" -Force

Codex devrait recréer ces fichiers si nécessaire.

cache/

Le dossier cache/ contient du cache technique.

Exemples possibles :

~/.codex/cache/
~/.codex/cache/codex_app_directory
~/.codex/cache/codex_apps_tools

Ce dossier n’est généralement pas le premier à supprimer. Il peut être conservé.

Pour un nettoyage plus agressif, il peut être vidé :

rm -rf ~/.codex/cache/*

Mais il sera probablement reconstruit ensuite.

plugins/

Le dossier plugins/ peut contenir des plugins installés ou mis en cache.

Exemple :

~/.codex/plugins/

En général, il vaut mieux le conserver, sauf si l’on cherche à réinitialiser complètement les plugins.

skills/

Le dossier skills/ peut contenir des compétences ou instructions installées.

Exemple :

~/.codex/skills/

Il est préférable de le conserver, sauf nettoyage complet volontaire.

memories/ et memories_*.sqlite

Selon la configuration et les fonctionnalités utilisées, Codex peut stocker des éléments de mémoire locale.

On peut rencontrer :

~/.codex/memories/
~/.codex/memories_1.sqlite
~/.codex/memories_1.sqlite-wal
~/.codex/memories_1.sqlite-shm

Il faut vérifier leur contenu ou leur taille avant suppression.

Pour afficher la taille :

du -sh ~/.codex/memories 2>/dev/null
ls -lh ~/.codex/memories_*.sqlite* 2>/dev/null

Si ces fichiers sont très petits, ils ne contiennent probablement pas grand-chose. Si l’objectif est un nettoyage strict des traces locales, ils peuvent être sauvegardés puis supprimés, mais ce n’est pas forcément nécessaire dans un nettoyage standard.

config.toml

Le fichier config.toml contient la configuration de Codex.

Exemple :

~/.codex/config.toml

Il peut contenir :

  • des paramètres globaux ;
  • des paramètres par projet ;
  • des règles d’approbation ;
  • des paramètres de sandbox ;
  • des options liées au modèle ;
  • des chemins de projets.

Il ne s’agit pas d’un historique de conversation. Il est donc généralement recommandé de le conserver.

Pour le consulter :

sed -n '1,160p' ~/.codex/config.toml

auth.json

Le fichier auth.json contient des informations liées à l’authentification.

Exemple :

~/.codex/auth.json

Il ne faut pas le supprimer si l’on veut rester connecté.

À conserver :

auth.json

installation_id et version.json

Ces fichiers servent à identifier l’installation ou la version locale.

Exemples :

installation_id
version.json

Ils sont petits et peuvent être conservés.

5. Rechercher les traces d’un projet dans .codex

Avant et après nettoyage, il peut être utile de rechercher des traces liées à un projet.

Exemple :

grep -RniE "nom-du-projet|wordpress|docker|laravel|mariadb|php" ~/.codex 2>/dev/null | head -100

Il faut toutefois interpréter les résultats avec prudence.

Certains mots comme docker, laravel, wordpress ou php peuvent apparaître dans des plugins, skills ou fichiers techniques sans aucun rapport avec vos propres projets.

Les fichiers réellement intéressants à surveiller sont surtout :

sessions/
archived_sessions/
history.jsonl
session_index.jsonl
logs_*.sqlite

Si les résultats ne proviennent plus que de config.toml, cache/, plugins/ ou skills/, il ne s’agit pas forcément d’un historique de conversation.

6. Sauvegarder avant nettoyage

Avant de supprimer des fichiers, il est préférable de faire une sauvegarde.

Sous Linux, macOS ou WSL2 :

mkdir -p ~/backup_codex

tar -czf ~/backup_codex/codex-cleanup-$(date +%Y-%m-%d_%H-%M).tar.gz \
  -C ~/.codex \
  sessions archived_sessions history.jsonl session_index.jsonl \
  logs_2.sqlite logs_2.sqlite-wal logs_2.sqlite-shm 2>/dev/null

Cette sauvegarde peut être supprimée plus tard si tout fonctionne correctement.

7. Nettoyage prudent de l’historique Codex

Cette étape supprime l’historique actif, les sessions archivées et les index de sessions.

Sous Linux, macOS ou WSL2 :

# Sessions actives
rm -rf ~/.codex/sessions/*

# Sessions archivées
rm -rf ~/.codex/archived_sessions/*

# Historique court
: > ~/.codex/history.jsonl

# Index des sessions
: > ~/.codex/session_index.jsonl

Pourquoi vider history.jsonl et session_index.jsonl plutôt que les supprimer ?

Parce que si Codex s’attend à retrouver ces fichiers, il est parfois plus propre de les laisser présents mais vides.

8. Nettoyage des logs SQLite volumineux

Avant cette étape, il est conseillé de fermer :

  • VS Code ;
  • l’extension Codex ;
  • Continue ;
  • les terminaux Codex en cours ;
  • tout processus susceptible d’utiliser .codex.

Sous Linux, macOS ou WSL2 :

rm -f ~/.codex/logs_*.sqlite ~/.codex/logs_*.sqlite-wal ~/.codex/logs_*.sqlite-shm

Sous Windows PowerShell :

Remove-Item "$env:USERPROFILE\.codex\logs_*.sqlite*" -Force

Ces fichiers peuvent être recréés automatiquement par Codex.

9. Nettoyage des fichiers temporaires

Les dossiers temporaires peuvent également être vidés :

rm -rf ~/.codex/tmp/*
rm -rf ~/.codex/.tmp/*
rm -rf ~/.codex/log/*

Ces dossiers sont généralement reconstruits si nécessaire.

10. Ce qu’il vaut mieux conserver

Dans un nettoyage standard, il est préférable de conserver :

auth.json
config.toml
installation_id
version.json
skills/
plugins/
cache/
state_*.sqlite
goals_*.sqlite
memories_*.sqlite

À conserver absolument

auth.json
config.toml

Supprimer auth.json peut obliger à se reconnecter.
Supprimer config.toml peut faire perdre la configuration personnalisée.

À vérifier avant suppression

memories/
memories_*.sqlite
state_*.sqlite
goals_*.sqlite

Ces fichiers sont généralement petits. Il vaut mieux ne pas les supprimer sans raison précise.

Supprimables en priorité

sessions/
archived_sessions/
history.jsonl
session_index.jsonl
logs_*.sqlite
tmp/
.tmp/
log/

11. Vérifier le résultat après nettoyage

Après nettoyage, vérifier la taille du dossier :

du -sh ~/.codex
du -h ~/.codex/ --max-depth=2

Vérifier que les historiques sont vides :

find ~/.codex/sessions ~/.codex/archived_sessions -type f 2>/dev/null | head
wc -l ~/.codex/history.jsonl ~/.codex/session_index.jsonl 2>/dev/null

Exemple de résultat attendu :

0 /home/user/.codex/history.jsonl
0 /home/user/.codex/session_index.jsonl

Rechercher encore d’éventuelles traces de projets :

grep -RniE "nom-du-projet|wordpress|docker|laravel|mariadb|php" ~/.codex 2>/dev/null | head -50

Si les résultats restants viennent seulement de config.toml, cache/, plugins/ ou skills/, il ne s’agit généralement plus d’un historique conversationnel.

12. Exemple de nettoyage complet sous Linux, macOS ou WSL2

Voici une commande complète de nettoyage prudent.

Elle sauvegarde d’abord les éléments importants, puis nettoie les historiques, archives, index, logs et fichiers temporaires.

# Fermer VS Code / Codex avant de lancer ce nettoyage si possible.

# 1. Sauvegarde
mkdir -p ~/backup_codex

tar -czf ~/backup_codex/codex-cleanup-$(date +%Y-%m-%d_%H-%M).tar.gz \
  -C ~/.codex \
  sessions archived_sessions history.jsonl session_index.jsonl \
  logs_2.sqlite logs_2.sqlite-wal logs_2.sqlite-shm 2>/dev/null

# 2. Nettoyage de l'historique
rm -rf ~/.codex/sessions/*
rm -rf ~/.codex/archived_sessions/*
: > ~/.codex/history.jsonl
: > ~/.codex/session_index.jsonl

# 3. Nettoyage des logs SQLite
rm -f ~/.codex/logs_*.sqlite ~/.codex/logs_*.sqlite-wal ~/.codex/logs_*.sqlite-shm

# 4. Nettoyage temporaire
rm -rf ~/.codex/tmp/*
rm -rf ~/.codex/.tmp/*
rm -rf ~/.codex/log/*

# 5. Vérification
du -sh ~/.codex
find ~/.codex/sessions ~/.codex/archived_sessions -type f 2>/dev/null | head
wc -l ~/.codex/history.jsonl ~/.codex/session_index.jsonl 2>/dev/null

13. Exemple de nettoyage sous Windows PowerShell

Si Codex est utilisé directement sous Windows :

# Fermer VS Code / Codex avant de lancer ce nettoyage si possible.

$CodexPath = "$env:USERPROFILE\.codex"
$BackupPath = "$env:USERPROFILE\backup_codex"

New-Item -ItemType Directory -Force -Path $BackupPath | Out-Null

# Sauvegarde simple du dossier .codex
$Date = Get-Date -Format "yyyy-MM-dd_HH-mm"
Compress-Archive -Path `
    "$CodexPath\sessions", `
    "$CodexPath\archived_sessions", `
    "$CodexPath\history.jsonl", `
    "$CodexPath\session_index.jsonl" `
    -DestinationPath "$BackupPath\codex-cleanup-$Date.zip" `
    -Force `
    -ErrorAction SilentlyContinue

# Nettoyage historique
Remove-Item "$CodexPath\sessions\*" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$CodexPath\archived_sessions\*" -Recurse -Force -ErrorAction SilentlyContinue

# Vider les fichiers d'index
if (Test-Path "$CodexPath\history.jsonl") {
    Clear-Content "$CodexPath\history.jsonl"
}

if (Test-Path "$CodexPath\session_index.jsonl") {
    Clear-Content "$CodexPath\session_index.jsonl"
}

# Nettoyage logs SQLite
Remove-Item "$CodexPath\logs_*.sqlite*" -Force -ErrorAction SilentlyContinue

# Nettoyage temporaire
Remove-Item "$CodexPath\tmp\*" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$CodexPath\.tmp\*" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$CodexPath\log\*" -Recurse -Force -ErrorAction SilentlyContinue

14. Après nettoyage : relancer proprement l’environnement

Après le nettoyage, il est conseillé de relancer l’environnement de développement.

Dans VS Code :

Ctrl + Shift + P
Developer: Reload Window

Ou bien fermer puis rouvrir complètement VS Code.

Si Codex recrée certains fichiers SQLite ou certains dossiers, c’est normal. L’objectif n’est pas d’empêcher Codex de fonctionner, mais de supprimer les anciens historiques et les logs accumulés.

15. Faut-il supprimer tout .codex ?

Dans la plupart des cas, non.

Supprimer tout le dossier :

rm -rf ~/.codex

peut entraîner :

  • la perte de la connexion ;
  • la perte de la configuration ;
  • la perte des paramètres projet ;
  • la suppression des plugins ou skills ;
  • une réinitialisation plus brutale que nécessaire.

Il vaut mieux commencer par nettoyer :

sessions/
archived_sessions/
history.jsonl
session_index.jsonl
logs_*.sqlite
tmp/
.tmp/
log/

Puis vérifier le résultat.

Conclusion

Le dossier .codex ne contient pas uniquement des conversations. Il peut aussi stocker des logs, des bases SQLite, du cache, des plugins, des skills, des fichiers temporaires et de la configuration.

Pour un nettoyage propre, il faut distinguer :

Historique conversationnel :
- sessions/
- archived_sessions/
- history.jsonl
- session_index.jsonl

Logs et traces techniques :
- logs_*.sqlite
- logs_*.sqlite-wal
- logs_*.sqlite-shm
- log/
- tmp/
- .tmp/

Configuration et authentification :
- config.toml
- auth.json
- installation_id
- version.json

Éléments techniques à conserver en général :
- cache/
- plugins/
- skills/
- state_*.sqlite
- goals_*.sqlite
- memories_*.sqlite

Le bon compromis consiste à supprimer les historiques, archives, index, logs volumineux et fichiers temporaires, tout en conservant la configuration et l’authentification.

Ce nettoyage permet de récupérer de l’espace disque, de supprimer les traces locales d’anciennes sessions et de repartir sur une base plus propre, sans réinstaller Codex.