Qué hace esta herramienta

claude-file-recovery es una herramienta de línea de comandos de Python con una TUI interactiva que extrae archivos del historial de sesiones de Claude Code. Fue creada después de que el autor eliminara accidentalmente archivos a través de un enlace simbólico que Claude Code no reconoció, y su copia de seguridad no se había ejecutado durante un mes. La herramienta reconstruye archivos analizando transcripciones de sesiones JSONL almacenadas en ~/.claude/projects/.

Características y funcionalidades clave

La herramienta puede recuperar cualquier archivo que Claude Code haya leído, editado o escrito, incluyendo versiones anteriores de archivos en puntos específicos en el tiempo. Ofrece:

• TUI interactiva con búsqueda difusa y atajos de teclado estilo vim (j/k/g/G, / para buscar)
• Recuperación puntual — reconstruye archivos en cualquier instantánea histórica, no solo la más reciente
• Vista de diferencias coloreada que muestra cómo cambiaron los archivos con el tiempo (modos unificado, de contexto completo y crudo)
• Extracción por lotes — selecciona múltiples archivos y extráelos todos a la vez
• Escaneo rápido — análisis paralelo de sesiones con orjson y verificaciones de bytes de rechazo rápido que omiten ~77% de líneas antes del análisis
• Deduplicación de enlaces simbólicos — detecta rutas con alias y las fusiona en entradas canónicas
• Búsqueda inteligente de mayúsculas/minúsculas — sensible a mayúsculas solo cuando tu consulta contiene letras mayúsculas (como ripgrep)

Instalación y uso

Requiere Python 3.10+. Opciones de instalación:

# Recomendado
uv tool install claude-file-recovery

O con pipx
pipx install claude-file-recovery
O con pip
pip install claude-file-recovery

Comandos básicos:

# Inicia la TUI interactiva (comando por defecto)
claude-file-recovery

Lista todos los archivos recuperables
claude-file-recovery list-files
Filtra por patrón
claude-file-recovery list-files --filter '*.py'
Exporta como CSV
claude-file-recovery list-files --filter '*.ts' --csv
Extrae archivos al disco
claude-file-recovery extract-files --output ./recovered --filter '*.py'
Recupera archivos como estaban antes de cierto momento
claude-file-recovery list-files --before '2025-02-20 14:00'
Apunta a un directorio de datos de Claude diferente
claude-file-recovery --claude-dir /path/to/claude-backup

Cómo funciona

La herramienta escanea todos los archivos de sesión JSONL en ~/.claude/projects/ y los analiza en paralelo usando un grupo de hilos. Correlaciona solicitudes de uso de herramientas en mensajes del asistente con sus resultados en mensajes del usuario a través de tool_use_id, luego reconstruye archivos reproduciendo operaciones en orden cronológico por ruta de archivo: las operaciones de escritura establecen contenido, las operaciones de edición aplican reemplazos de cadenas, y las operaciones de lectura capturan instantáneas. La bandera --before usa búsqueda binaria para cortar en cualquier punto en el tiempo.

Atajos de teclado de la TUI

• j/k: Mover arriba/abajo
• g/G: Saltar al inicio/final
• /: Buscar
• Ctrl+R: Cambiar modo de búsqueda (difusa / glob / regex)
• x o Espacio: Alternar selección de archivo
• Enter: Ver detalles del archivo + diferencias
• d: Cambiar modo de diferencias (unificado / contexto completo / crudo)
• Ctrl+E: Extraer archivos seleccionados
• q: Atrás / salir

Este tipo de herramienta de recuperación es útil para desarrolladores que usan Claude Code extensivamente y quieren protección contra eliminación o corrupción accidental de archivos. El proyecto con licencia MIT tiene 26 estrellas y 1 bifurcación en GitHub al momento de escribir esto.