El problema

Claude Code (y cualquier otra CLI de codificación con IA) almacena el historial completo de tus conversaciones como JSONL en texto plano en el disco: en ~/.claude/projects/ para Claude Code, ~/.codex/sessions/ para OpenAI Codex. Cualquier cosa que pegues — una clave de AWS, un archivo .env, una URL de base de datos — queda en texto claro indefinidamente. El historial de un desarrollador típico acumula docenas de secretos a lo largo de los meses, a menudo sin que se dé cuenta.

agentsweep escanea ese historial, te dice qué se ha filtrado y puede redactar los valores secretos en su lugar mientras preserva la estructura JSONL byte a byte. También te indica qué claves rotar, con la URL de revocación correcta para cada proveedor.

Alcance de la protección: agentsweep en sí es totalmente local y sin conexión — solo lee y escribe archivos en tu máquina y no realiza ninguna llamada de red. Elimina un vector de ataque: los secretos que permanecen en archivos de historial local. No afecta a lo que tu proveedor de IA ya ha recibido: cuando pegas una clave en Claude Code, Cursor o cualquier agente respaldado por la nube, esa clave ya pasó por los servidores del proveedor antes de llegar al disco. Si te preocupa, considera un modelo alojado localmente (Ollama, LM Studio, OpenCode) donde nada sale de tu máquina — agentsweep combina especialmente bien con configuraciones de modelos locales.

Por qué esto importa ahora mismo

Los ataques a la cadena de suministro se están acelerando. En 2024–2025, una ola de paquetes maliciosos de npm y PyPI — sha256-universal, shailulid, cientos de typosquats — fue descubierta haciendo una sola cosa: exfiltrar credenciales de desarrolladores desde la máquina que los instaló. Apuntan a variables de entorno, archivos .env, historial de shell, claves SSH y ahora a los archivos de historial de los agentes de IA.

Los asistentes de codificación con IA han creado una nueva categoría de exposición de credenciales que no existía hace dos años:

• Pegas una clave de API de producción en Claude Code para depurar algo → ahora está en ~/.claude/projects/*/conversations/*.jsonl para siempre
• Un paquete npm comprometido ejecuta postinstall → escanea rutas comunes → encuentra tu historial JSONL → exfiltra 50 claves de API en una sola petición
• Rotas la clave que usaste en público pero olvidas las otras docenas que están en tu historial
• Mientras tanto tu historial crece: cada .env con el que pediste ayuda a una IA, cada URL de base de datos que compartiste para depurar, cada token que pegaste para una línea de comando

El historial de los agentes de IA es el nuevo .bash_history — excepto que contiene contexto completo, no solo comandos. Las herramientas de ataque ya lo saben. agentsweep existe para limpiar antes de que sea explotado.

Inicio 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

Eso es todo. Sin virtualenv que activar, sin tocar el PATH — uv tool install le da al comando su propio entorno aislado.

Cómo funciona

agentsweep ejecuta un pipeline fijo de 5 etapas. scan se detiene después de la etapa 3; fix continúa hasta la redacción.

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 escritura está protegida por 8 invariantes de seguridad: reemplazo atómico, copia de seguridad .bak obligatoria, rechazo de enlaces simbólicos, controles de mtime/proceso y validación JSONL posterior a la escritura. agentsweep undo restaura desde las copias de seguridad.

Instalación

Recomendado — aislado, sin conflictos de venv:

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

Prueba sin instalar (siempre ejecuta la última versión):

uvx agentsweep@latest

Pip clásico:

pip install agentsweep
pip install --upgrade agentsweep

¿No tienes uv? pip install uv o consulta astral.sh/uv. Requiere Python 3.11+.

Uso

Modo interactivo

Ejecútalo sin argumentos en una terminal y obtienes la experiencia completa: banner, menú numerado, confirmaciones escritas antes de cualquier acción destructiva y deshacer con una sola tecla (restaura las copias de seguridad .bak). Cualquier escaneo interactivo que encuentre secretos termina con una oferta para redactarlos en el momento (escribe REDACT para confirmar):

agentsweep

La automatización no se ve afectada: cualquier bandera, o un flujo canalizado/redirigido, omite el menú por completo y se comporta exactamente como se documenta a continuación.

Verbos

La forma heredada con bandera agentsweep --fix sigue siendo aceptada y se comporta igual que agentsweep fix.

Selección de fuentes

Elige el historial del agente que quieres analizar con --source. El valor predeterminado es 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/

¿No sabes qué agentes tienes instalados? list-sources imprime cada fuente compatible, su ubicación de historial y si ese historial existe en esta máquina, para que sepas qué valores de --source merece la pena escanear. No lee ni escribe 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)

Escanea todos los agentes registrados de una sola vez (hallazgos agregados; la redacción se mantiene por fuente):

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

Anula el directorio raíz predeterminado para escanear cualquier carpeta arbitraria:

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

Banderas 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

Banderas exclusivas de 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

Banderas de undo

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

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

Garantías contra la corrupción

Un redactor que corrompe tu historial es estrictamente peor que la fuga que está arreglando. agentsweep aplica estos invariantes en cada --fix:

1. La redacción ocurre en JSON analizado, no sobre bytes brutos. Los secretos se reemplazan como valores de cadena dentro de la estructura analizada y luego se re-serializan. El daño estructural es imposible por construcción.
2. Escrituras atómicas. Cada reescritura sigue: archivo temporal → fsync() → os.replace() sobre el original. Un fallo en cualquier instante deja o el archivo antiguo completo o el archivo nuevo completo — nunca una escritura a medias.
3. Validación posterior a la escritura. Antes de confirmar, el nuevo contenido debe pasar una comprobación según el formato: JSONL — cada línea no vacía se analiza como JSON y el número de líneas coincide con el original; JSON de archivo completo — el documento se analiza; markdown/texto plano — el número de líneas coincide con el original; SQLite — la copia reescrita supera PRAGMA integrity_check. Si la comprobación falla, la escritura se aborta y el original no se toca.
4. Copia de seguridad .bak por defecto. Se crea legible solo por el propietario (modo 0600) ya que contiene los secretos previos a la redacción; se niega a ejecutarse si ya existe un .bak (para que las copias anteriores no puedan sobrescribirse).
5. Contención de rutas. Rechaza cualquier destino que no se resuelva dentro de uno de los árboles de historial de la fuente (p. ej. el directorio User de Windsurf y su ~/.codeium/windsurf/memories/).
6. Rechazo de enlaces simbólicos. Rechaza los enlaces simbólicos directamente.
7. Ventana de mtime. Rechaza archivos modificados en los últimos 60 segundos (probablemente una sesión activa). lo anula.

Recuperación

Cada archivo redactado tiene un *.bak hermano con los bytes originales. La forma más fácil de deshacer todas las redacciones de una fuente es:

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

Si necesitas restaurar un solo archivo manualmente (p. ej. eliminaste la fuente del comando undo):

mv session.jsonl.bak session.jsonl

Las copias de seguridad contienen los originales previos a la redacción — secretos en texto plano, por lo que un barrido no está completo hasta que las claves filtradas se rotan y las copias desaparecen. Una vez que las hayas rotado:

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)

Qué se detecta

191 patrones de alta confianza más un detector de frases semilla de criptomonedas validado por checksum — los mnemónicos BIP-39 (12/15/18/21/24 palabras; el formato de cartera detrás de BTC, ETH, SOL, BNB, ADA, DOGE, LTC, DOT, AVAX y prácticamente todas las cadenas principales) y las semillas de Electrum se confirman criptográficamente (checksum BIP-39 / etiqueta de versión de Electrum), por lo que la prosa en inglés que usa palabras de cartera no genera falsos positivos.

Los patrones: claves de acceso de AWS, tokens de GitHub (PAT/OAuth/App/fine-grained), Stripe live/test, OpenAI, Anthropic, Google API, Slack bot/usuario/webhook, Hugging Face, JWT, claves privadas PEM, URLs de bases de datos con contraseñas incrustadas, tokens de npm/PyPI/SendGrid/Twilio — más 167 reglas portadas del paquete gitleaks que cubren 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, credenciales curl en la línea de comandos y muchas más. Los patrones son de alta precisión: los falsos positivos son raros y las reglas con contexto de proveedor están controladas por palabras clave para que los pegados grandes sigan siendo rápidos.

Qué NO se detecta

• Secretos personalizados o propietarios sin un prefijo reconocible.
• Frases semilla de Monero (25 palabras de la lista de palabras propia de Monero — previsto).
• Tokens desconocidos que parecen base64 arbitrario.
• Secretos divididos en varios mensajes.
• Cualquier cosa dentro de un archivo binario o no UTF-8.

Para una detección más profunda, ejecuta gitleaks o trufflehog junto con agentsweep: sus paquetes de reglas son más exhaustivos. El valor de agentsweep es la superficie específica del historial de agentes, no el motor de detección.

Preguntas frecuentes

¿Por qué uvx agentsweep muestra una versión antigua? uvx almacena en caché las herramientas localmente. Usa uvx agentsweep@latest para ejecutar siempre la versión más reciente (recomendado), o fuerza una actualización de caché con uvx --reinstall agentsweep.

¿Dónde está OpenCode en el menú? El soporte para OpenCode se añadió en v0.1.1. Ejecuta pip install --upgrade agentsweep o uvx agentsweep@latest para obtenerlo.

¿Agentsweep envía mis datos a algún sitio? No. Es totalmente sin conexión: cero llamadas de red durante el escaneo o la redacción. La única llamada de red opcional es la comprobación de actualización en segundo plano, que solo obtiene el número de la última versión desde PyPI.

Contribuyentes

Gracias a todos los que han contribuido con código, informes de errores e ideas.

Licencia

MIT. Consulta LICENSE.