O que esta ferramenta faz

claude-file-recovery é uma ferramenta de linha de comando em Python com uma interface TUI interativa que extrai arquivos do histórico de sessões do Claude Code. Foi criada após o autor excluir acidentalmente arquivos através de um link simbólico que o Claude Code não reconheceu, e seu backup não havia sido executado por um mês. A ferramenta reconstrói arquivos analisando transcrições de sessão JSONL armazenadas em ~/.claude/projects/.

Principais recursos e funcionalidades

A ferramenta pode recuperar qualquer arquivo que o Claude Code já leu, editou ou escreveu, incluindo versões anteriores de arquivos em pontos específicos no tempo. Ela oferece:

• TUI interativa com busca fuzzy e atalhos de teclado do vim (j/k/g/G, / para buscar)
• Recuperação pontual — reconstrua arquivos em qualquer snapshot histórico, não apenas o mais recente
• Visualização de diff colorida mostrando como os arquivos mudaram ao longo do tempo (modos unificado, de contexto completo e bruto)
• Extração em lote — selecione vários arquivos e extraia todos de uma vez
• Varredura rápida — análise paralela de sessões com orjson e verificações de rejeição rápida de bytes que pulam ~77% das linhas antes da análise
• Deduplicação de links simbólicos — detecta caminhos com alias e os mescla em entradas canônicas
• Busca inteligente de maiúsculas/minúsculas — sensível a maiúsculas apenas quando sua consulta contém letras maiúsculas (como ripgrep)

Instalação e uso

Requer Python 3.10+. Opções de instalação:

# Recomendado
uv tool install claude-file-recovery

Ou com pipx
pipx install claude-file-recovery
Ou com pip
pip install claude-file-recovery

Comandos básicos:

# Inicia a TUI interativa (comando padrão)
claude-file-recovery

Lista todos os arquivos recuperáveis
claude-file-recovery list-files
Filtra por padrão
claude-file-recovery list-files --filter '*.py'
Exporta como CSV
claude-file-recovery list-files --filter '*.ts' --csv
Extrai arquivos para o disco
claude-file-recovery extract-files --output ./recovered --filter '*.py'
Recupera arquivos como estavam antes de um determinado horário
claude-file-recovery list-files --before '2025-02-20 14:00'
Aponta para um diretório de dados do Claude diferente
claude-file-recovery --claude-dir /path/to/claude-backup

Como funciona

A ferramenta varre todos os arquivos de sessão JSONL em ~/.claude/projects/ e os analisa em paralelo usando um pool de threads. Ela correlaciona solicitações de uso de ferramentas em mensagens do assistente com seus resultados em mensagens do usuário via tool_use_id, então reconstrói arquivos reproduzindo operações em ordem cronológica por caminho de arquivo: operações de escrita definem conteúdo, operações de edição aplicam substituições de string e operações de leitura capturam snapshots. A flag --before usa busca binária para cortar em qualquer ponto no tempo.

Atalhos de teclado da TUI

• j/k: Mover para cima/baixo
• g/G: Ir para o topo/fundo
• /: Buscar
• Ctrl+R: Alternar modo de busca (fuzzy / glob / regex)
• x ou Espaço: Alternar seleção de arquivo
• Enter: Ver detalhes do arquivo + diffs
• d: Alternar modo de diff (unificado / contexto completo / bruto)
• Ctrl+E: Extrair arquivos selecionados
• q: Voltar / sair

Este tipo de ferramenta de recuperação é útil para desenvolvedores que usam o Claude Code extensivamente e desejam proteção contra exclusão ou corrupção acidental de arquivos. O projeto licenciado pelo MIT tem 26 estrelas e 1 fork no GitHub no momento desta escrita.