O problema

O Claude Code (e qualquer outro CLI de codificação de IA) armazena todo o seu histórico de conversas como JSONL em texto simples no disco — em ~/.claude/projects/ para Claude Code, ~/.codex/sessions/ para OpenAI Codex. Qualquer coisa que você cole — uma chave da AWS, um arquivo .env, uma URL de banco de dados — fica em texto claro indefinidamente. O histórico de um desenvolvedor típico acumula dezenas de segredos ao longo de meses, muitas vezes sem que ele perceba.

O agentsweep examina esse histórico, informa o que vazou e pode mascarar os valores dos segredos no local, preservando a estrutura JSONL byte por byte. Ele também informa quais chaves você deve rotacionar, com a URL de revogação correta para cada provedor.

Escopo da proteção: o agentsweep em si é totalmente local e offline — ele lê e grava apenas arquivos na sua máquina e não faz nenhuma chamada de rede. Ele remove um vetor de ataque: segredos em arquivos locais de histórico. Ele não afeta o que seu provedor de IA já recebeu: quando você cola uma chave no Claude Code, Cursor ou qualquer agente baseado em nuvem, essa chave já passou pelos servidores do provedor antes de chegar ao disco. Se isso preocupa você, considere um modelo hospedado localmente (Ollama, LM Studio, OpenCode), em que nada sai da sua máquina — o agentsweep combina especialmente bem com configurações de modelos locais.

Por que isso importa agora

Os ataques à cadeia de suprimentos estão se acelerando. Em 2024–2025, uma onda de pacotes maliciosos npm e PyPI — sha256-universal, shailulid, centenas de typosquats — foi flagrada fazendo uma coisa: exfiltrando credenciais de desenvolvedores da máquina em que foram instalados. Eles miram variáveis de ambiente, arquivos .env, histórico do shell, chaves SSH e agora os arquivos de histórico de agentes de IA.

Os assistentes de codificação de IA criaram uma nova categoria de exposição de credenciais que não existia há dois anos:

• Você cola uma chave de API de produção no Claude Code para depurar algo → ela agora está em ~/.claude/projects/*/conversations/*.jsonl para sempre
• Um pacote npm comprometido executa postinstall → verifica caminhos comuns → encontra seu histórico JSONL → exfiltra 50 chaves de API em uma única requisição
• Você rotaciona a chave que usou em público, mas esquece as outras dezenas no seu histórico
• Enquanto isso, seu histórico cresce: cada .env para o qual você pediu ajuda a uma IA, cada URL de banco de dados compartilhada para depuração, cada token colado para um one-liner

O histórico de agentes de IA é o novo .bash_history — exceto que contém contexto completo, não apenas comandos. As ferramentas de ataque já sabem disso. O agentsweep existe para limpar antes que isso seja explorado.

Início rápido

pip install uv                  # get uv (skip if you already have it)
uv tool install agentsweep      # install — adds `agentsweep` and `asweep` to PATH
asweep                          # run — interactive menu guides you through everything

Só isso. Nenhum virtualenv para ativar, nenhuma configuração de PATH — o uv tool install dá ao comando seu próprio ambiente isolado.

Como funciona

O agentsweep executa um pipeline fixo de 5 estágios. O scan para após o estágio 3; o fix continua até o mascaramento.

flowchart LR
    A("🔍 DISCOVER\nwalk history dirs\nstream file list") --> B("⚡ SCAN\nAho-Corasick pre-filter\n191 regex rules + BIP-39")
    B --> C{"secrets\nfound?"}
    C -- "none" --> D("✅ CLEAN\nexit 0")
    C -- "found" --> E("📋 FINDINGS\nshow report\nexit 1")
    E -. "scan only" .-> F("⚠️ ROTATE\nkeys still live")
    E -- "type REDACT" --> G("✏️ REDACT\natomic write · .bak backup\npost-write JSON validation")
    G --> H("🔑 ROTATE\nper-provider\nrevocation links")

    style A fill:#1e3a5f,color:#fff,stroke:#2d5986
    style B fill:#1e3a5f,color:#fff,stroke:#2d5986
    style C fill:#4a3728,color:#fff,stroke:#7a5c3f
    style D fill:#1a4731,color:#fff,stroke:#2d7a52
    style E fill:#4a3a1e,color:#fff,stroke:#7a6030
    style F fill:#4a2020,color:#fff,stroke:#8b3a3a
    style G fill:#1e3a5f,color:#fff,stroke:#2d5986
    style H fill:#2d1e4a,color:#fff,stroke:#5a3a8b

Cada gravação é protegida por 8 invariantes de segurança — substituição atômica, backup .bak obrigatório, rejeição de symlinks, bloqueios de mtime/processo e validação JSONL pós-gravação. O agentsweep undo restaura a partir dos backups.

Instalação

Recomendado — isolado, sem conflitos de venv:

uv tool install agentsweep      # one-time install
uv tool upgrade agentsweep      # update to latest

Experimente sem instalar (sempre executa a versão mais recente):

uvx agentsweep@latest

pip clássico:

pip install agentsweep
pip install --upgrade agentsweep

Não tem uv? pip install uv ou veja astral.sh/uv. Requer Python 3.11+.

Uso

Modo interativo

Execute sem argumentos em um terminal e você terá a experiência completa — banner, menu numerado, confirmações digitadas antes de qualquer ação destrutiva e desfazer com uma tecla (restaura os backups .bak). Qualquer verificação interativa que encontrar segredos termina com uma oferta para mascarar na hora (digite REDACT para confirmar):

agentsweep

A criação de scripts não é afetada: qualquer flag, ou um fluxo canalizado/redirecionado, pula o menu inteiramente e se comporta exatamente como documentado abaixo.

Verbos

A forma legada com flag agentsweep --fix ainda é aceita e se comporta de forma idêntica ao agentsweep fix.

Seleção de fonte

Escolha o histórico de qual agente será alvo com --source. O padrão é claude-code.

agentsweep scan --source claude-code          # ~/.claude/projects/ (default)
agentsweep scan --source codex                # ~/.codex/sessions/
agentsweep scan --source opencode             # OpenCode SQLite store
agentsweep scan --source cursor               # Cursor history
agentsweep scan --source windsurf             # Windsurf history
agentsweep scan --source aider                # ~/.aider/
agentsweep scan --source cline                # Cline history
agentsweep scan --source gemini-cli           # Gemini CLI history
agentsweep scan --source continue-vscode      # Continue (VS Code) history
agentsweep scan --source github-copilot-chat  # GitHub Copilot Chat history
agentsweep scan --source openclaw             # OpenClaw ~/.openclaw/
agentsweep scan --source hermes               # Hermes Agent ~/.hermes/state.db
agentsweep scan --source goose                # Goose ~/.local/share/goose/

Não sabe quais agentes você tem instalados? O list-sources imprime cada fonte suportada, sua localização de histórico e se esse histórico existe nesta máquina — para você saber quais valores de --source valem a pena verificar. Ele não lê nada e não escreve nada.

agentsweep list-sources             # all 29 sources + which are on disk
agentsweep list-sources --detected  # only the ones found on this machine
agentsweep list-sources --json      # machine-readable (for scripts/CI)

Verifique todos os agentes registrados em uma única passada (achados agregados; o mascaramento permanece por fonte):

agentsweep scan --all                 # all registered sources
agentsweep scan --all --detected      # only sources with a history root on disk
agentsweep scan --all --json          # aggregated JSON (each finding has "source")
agentsweep scan --all --json -o out.json

Substitua o diretório raiz padrão para verificar qualquer pasta arbitrária:

agentsweep scan --root ~/backups/claude-history
agentsweep fix  --root /tmp/history-copy --allow-production

Flags de scan / fix

# Machine-readable JSON to stdout (exit 0 = clean, 1 = findings found, 2 = error)
agentsweep scan --json

# Write findings JSON to a file instead of stdout
agentsweep scan --json -o findings.json
agentsweep scan --json --output /tmp/report.json

# Skip .agentsweepignore files
agentsweep scan --no-ignore

Flags exclusivas do fix

# Redact Claude Code history in place (--allow-production required for default roots during alpha)
agentsweep fix --allow-production

# Skip creating .bak backups (not recommended)
agentsweep fix --allow-production --no-backup

# Bypass soft safety checks: mtime gate (files modified <60 s ago) and running-process gate
agentsweep fix --allow-production --force

# Combine: non-interactive JSON-mode redaction against a custom root
agentsweep fix --root ~/history-copy --json

Flags do undo

# Undo redactions for a specific source
agentsweep undo --source codex

# Undo against a custom root
agentsweep undo --root ~/history-copy

Garantias de prevenção contra corrupção

Uma ferramenta de mascaramento que corrompe seu histórico é estritamente pior do que o vazamento que ela está corrigindo. O agentsweep aplica estes invariantes em todo --fix:

1. O mascaramento acontece no JSON analisado, não nos bytes brutos. Os segredos são substituídos como valores de string dentro da estrutura analisada e depois re-serializados. Danos estruturais são impossíveis por construção.
2. Gravações atômicas. Cada reescrita segue: arquivo temporário → fsync() → os.replace() sobre o original. Uma falha em qualquer instante deixa ou o arquivo antigo completo ou o novo arquivo completo — nunca uma gravação interrompida.
3. Validação pós-gravação. Antes de confirmar, o novo conteúdo deve passar por uma verificação ciente do formato: JSONL — cada linha não vazia é analisada como JSON e a contagem de linhas corresponde ao original; JSON de arquivo inteiro — o documento é analisado; markdown/texto simples — a contagem de linhas corresponde ao original; SQLite — a cópia reescrita passa em PRAGMA integrity_check. Se a verificação falhar, a gravação é abortada e o original fica intocado.
4. Backup .bak por padrão. Criado somente com leitura para o dono (modo 0600), pois contém os segredos pré-mascaramento; recusa-se a executar se um .bak já existir (para que backups anteriores não sejam sobrescritos).
5. Contenção de caminho. Recusa qualquer alvo que não resolva dentro de uma das árvores de histórico da fonte (por exemplo, o diretório User do Windsurf e seu ~/.codeium/windsurf/memories/).
6. Rejeição de symlinks. Recusa symlinks de imediato.
7. Janela de mtime. Recusa arquivos modificados nos últimos 60 segundos (provavelmente uma sessão ativa). O sobrescreve.

Recuperação

Todo arquivo mascarado tem um *.bak irmão com os bytes originais. A maneira mais fácil de desfazer todos os mascaramentos de uma fonte é:

agentsweep undo                        # undo Claude Code (default)
agentsweep undo --source codex         # undo a specific source
agentsweep undo --root ~/history-copy  # undo against a custom root

Se você precisar restaurar um único arquivo manualmente (por exemplo, se você excluiu a fonte do comando undo):

mv session.jsonl.bak session.jsonl

Os backups contêm os originais pré-mascaramento — segredos em texto simples, então uma varredura não termina até que as chaves vazadas sejam rotacionadas e os backups sejam removidos. Depois de rotacionar:

agentsweep purge                       # delete Claude Code backups (asks first)
agentsweep purge --source windsurf     # delete a specific source's backups
agentsweep purge --yes                 # non-interactive (scripts / CI)

O que é detectado

191 padrões de alta confiança mais um detector de frases-semente cripto validado por checksum — mnemônicos BIP-39 (12/15/18/21/24 palavras; o formato de carteira por trás de BTC, ETH, SOL, BNB, ADA, DOGE, LTC, DOT, AVAX e praticamente todas as principais blockchains) e sementes Electrum são confirmados criptograficamente (checksum BIP-39 / tag de versão Electrum), então textos em inglês que por acaso usam palavras de carteira nunca geram falsos positivos.

Os padrões: chaves de acesso da AWS, tokens do GitHub (PAT/OAuth/App/fine-grained), Stripe live/test, OpenAI, Anthropic, Google API, Slack bot/user/webhook, Hugging Face, JWT, chaves privadas PEM, URLs de banco de dados com senhas embutidas, tokens npm/PyPI/SendGrid/Twilio — além de 167 regras portadas do pacote gitleaks que cobrem GitLab, Grafana, HashiCorp Vault/Terraform, DigitalOcean, Shopify, PlanetScale, Databricks, Atlassian, Azure AD, 1Password, Sentry, New Relic, Mailgun, Datadog, Twilio, Twitter/X, Twitch, Yandex, JFrog, Snyk, Mailchimp, credenciais curl na linha de comando e muitos outros. Os padrões são de alta precisão — falsos positivos são raros, e as regras de contexto do provedor são limitadas por palavras-chave para que colagens grandes continuem rápidas.

O que NÃO é detectado

• Segredos personalizados/proprietários sem um prefixo reconhecível.
• Frases-semente Monero (25 palavras da própria wordlist do Monero — planejado).
• Tokens desconhecidos que parecem base64 arbitrário.
• Segredos divididos entre várias mensagens.
• Qualquer coisa dentro de um arquivo binário/não UTF-8.

Para uma detecção mais profunda, execute gitleaks ou trufflehog junto com o agentsweep — os pacotes de regras deles são mais exaustivos. O valor do agentsweep é a superfície específica do histórico do agente, não o mecanismo de detecção.

Perguntas frequentes

Por que o uvx agentsweep mostra uma versão antiga? O uvx armazena ferramentas em cache localmente. Use uvx agentsweep@latest para sempre executar a versão mais recente (recomendado) ou force a atualização do cache com uvx --reinstall agentsweep.

Onde está o OpenCode no menu? O suporte ao OpenCode foi adicionado na v0.1.1. Execute pip install --upgrade agentsweep ou uvx agentsweep@latest para obtê-lo.

O agentsweep envia meus dados para algum lugar? Não. Ele é totalmente offline — zero chamadas de rede durante a verificação ou o mascaramento. A única chamada de rede opcional é a verificação de atualização em segundo plano, que apenas busca o número da versão mais recente no PyPI.

Contribuidores

Obrigado a todos que contribuíram com código, relatórios de bugs e ideias.

Licença

MIT. Veja LICENSE.