Fabián Delgado

1 de junio de 2026 · 7 min de lectura

Cómo aporté a Mole la limpieza de los worktrees que dejan los agentes de IA

Hace unas semanas mi Mac empezó a quedarse sin espacio sin razón aparente. No eran fotos, ni Docker, ni descargas. Cuando fui a buscar de dónde salían los gigabytes, el culpable era algo que yo mismo había puesto a trabajar todos los días: los agentes de IA. Cada vez que dejaba a Claude Code corriendo una tarea en paralelo, creaba una copia completa del proyecto en una carpeta escondida — y nunca la borraba. Terminé escribiendo el código que faltaba para limpiarlas y mandándolo como contribución a una herramienta open source. Esto es lo que aprendí.

La herramienta se llama Mole (el comando es mo): un limpiador de disco para macOS, open source, que libera espacio borrando cachés, logs y artefactos que se regeneran solos. La uso desde hace un tiempo. El problema es que Mole no sabía nada de un tipo de basura nuevo que recién empezó a aparecer en 2025: los git worktrees que dejan los agentes de IA.

El problema: cada tarea en paralelo es una copia entera del proyecto

Cuando un agente de IA como Claude Code corre una tarea en background o varias en paralelo, no trabaja sobre tu carpeta directamente — eso pisaría tu trabajo. En vez de eso usa una función de git llamada worktree: crea un checkout aislado del repositorio en otra carpeta, normalmente bajo <proyecto>/.claude/worktrees/. Ahí el agente puede tocar archivos, instalar dependencias y compilar sin interferir con lo que vos estás haciendo. Uso Claude Code todos los días — incluso conté cómo armé mi asistente personal con él en WhatsApp.

El detalle es que cada uno de esos worktrees es un checkout completo del proyecto: incluye node_modules, salida de build, artefactos, todo. Y cuando la tarea termina, nadie los borra. Se van acumulando, repo por repo, ejecución por ejecución. En mi caso eran varios GB repartidos en una decena de carpetas que ni sabía que existían. 

~/Code/proyecto-a/.claude/worktrees/task-3f2a/   # checkout completo + node_modules
~/Code/proyecto-a/.claude/worktrees/task-91be/   # otro más
~/Code/proyecto-b/.claude/worktrees/task-0c7d/   # y otro
...

Lo busqué en Mole y la limpieza existente solo se ocupaba de las versiones de binarios de los agentes y del estado global en ~/.claude. Los worktrees por proyecto quedaban completamente afuera. Era un punto ciego — y uno que va a crecer a medida que más gente use agentes que trabajan en paralelo.

Por qué no alcanza con un rm -rf

La tentación es obvia: rm -rf .claude/worktrees/ y listo. No lo hagas. Hay dos razones por las que esto es peligroso, y las dos guiaron el diseño de mi contribución.

Razón uno: podés borrar trabajo sin guardar. Un worktree de un agente puede tener cambios sin commitear, archivos sin trackear, o commits que todavía no están en ningún remoto. Borrarlo a ciegas es perder ese trabajo para siempre. Cualquier limpieza automática tiene que distinguir un worktree limpio (seguro de borrar) de uno que podría tener algo adentro.

Razón dos: git no te deja limpiar prolijo. Los agentes bloquean sus worktrees (los marcan como locked) para que git no los toque mientras corren. Si borrás la carpeta a mano, el registro de worktrees del repo padre queda con una entrada fantasma, y un git worktree prune normal la saltea justamente porque está bloqueada. Te queda el repo sucio.

Qué hace mi contribución (PR #985)

Agregué una función nueva, clean_dev_agent_worktrees, al flujo de herramientas de desarrollo de Mole. El diseño está pensado para que sea imposible perder trabajo sin querer:

  • No corre por defecto. En una limpieza normal solo reporta cuánto espacio podrías recuperar y te da la pista para activarlo. No borra nada hasta que vos lo pidas explícitamente.
  • Opt-in con una variable. Con MOLE_AGENT_WORKTREES=1 activado, borra solo los worktrees que están completamente limpios: sin cambios sin commitear, sin archivos sin trackear y sin commits que falten en un remoto. Cualquier cosa que pueda contener trabajo sin guardar se conserva y se lista para que la revises a mano.
  • Borrado seguro, nunca rm crudo. Elimina a través de la función safe_clean de Mole: ruteo a la Papelera, log de operaciones y soporte de --dry-run. Y respeta should_protect_path, la lista de rutas protegidas.
  • Limpia el registro de git, no solo la carpeta. Hace unlock de los worktrees bloqueados y después prune --expire=now sobre el repo padre, para que no queden entradas fantasma — el problema que mencioné arriba.
  • Configurable. Las rutas donde busca se pueden sobreescribir con MOLE_AGENT_WORKTREE_PATHS, por si tus agentes dejan los worktrees en otro lado.

Además sumé dos tests automatizados (con bats): uno que verifica que por defecto solo reporta sin borrar, y otro que confirma que con el flag activado borra un worktree limpio aunque esté bloqueado, pero conserva uno que tiene cambios. Son 174 líneas, cero borradas — una función nueva que no toca el comportamiento existente.

Cómo usarlo vos

El cambio se mergeó el 26 de mayo y salió en la versión 1.40.0 de Mole, publicada el 30 de mayo de 2026. Si ya tenés Mole, actualizá con mo update. Si no, está en su repositorio. Después, tres pasos:

1. Ver cuánto espacio hay para recuperar — sin borrar nada: 

mo clean --dry-run

En la sección de herramientas de desarrollo vas a ver los worktrees de agentes detectados y el tamaño recuperable, con la pista para activarlos.

Salida de mo clean en la terminal: archivos grandes, datos de OrbStack, artefactos de proyecto con carpetas venv y 628,7 MB liberados al terminar
Una corrida real de mo clean en mi Mac: detecta artefactos de proyecto (acá, carpetas venv) y libera espacio sin tocar tu trabajo. La limpieza de worktrees de agentes corre en este mismo flujo, opt-in.

2. Previsualizar la limpieza real — con el flag activado, todavía sin borrar: 

MOLE_AGENT_WORKTREES=1 mo clean --dry-run

Acá Mole te muestra exactamente qué worktrees borraría (los limpios) y cuáles conserva (los que tienen trabajo sin guardar). Leé esa lista antes de seguir.

3. Ejecutar: 

MOLE_AGENT_WORKTREES=1 mo clean

Se borran solo los limpios, van a la Papelera (no se evaporan), y el registro de git queda prolijo. Tu trabajo sin commitear sigue intacto.

Lo que me llevo de esto

Los agentes de IA generan basura nueva que las herramientas de hoy todavía no conocen. Worktrees, checkouts paralelos, estado por proyecto: son patrones que hace dos años no existían. La higiene de disco para una máquina de desarrollo que corre agentes es un problema distinto al de una máquina común, y las herramientas recién están alcanzando esa realidad.

El diseño seguro es casi todo el trabajo. Borrar archivos es una línea. Borrar solo los que se pueden borrar sin perder nada — distinguir limpio de sucio, respetar bloqueos, rutear a la Papelera, dejar el registro consistente — es donde está el 90% del código y de la responsabilidad. En cualquier flujo destructivo, lo que no borrás importa más que lo que borrás.

Contribuir a open source sigue siendo la mejor forma de devolver. Usaba Mole gratis todos los días; tenía un punto ciego que a mí me molestaba; lo arreglé para todos los que la usan. Ese ciclo — encontrar fricción real en una herramienta que usás, resolverla bien y mandarla de vuelta — es de las cosas más sanas que tiene este oficio.

Última actualización: