Do 99% ao 90%: como tirei o SSD do Mac do vermelho com mo clean, um script próprio e launchd

O SSD no vermelho

Numa noite de outubro o Mac começou a engasgar. Nada dramático: o Spotlight demorava, um npm install parou no meio, uma build do Xcode reclamou de espaço. Rodei o comando que todo mundo roda nessa hora:

df -h /System/Volumes/Data

/dev/disk3s5   460Gi   417Gi   5.6Gi    99%

Sobravam 5,6 GB num SSD de 460 GB. Em APFS isso é perigoso por um motivo prático: o sistema precisa de espaço livre para swap, snapshots, atualizações e para os arquivos temporários que qualquer ferramenta de desenvolvimento cria sem pedir licença. Com 1% livre, qualquer coisa pode ser a gota que trava a máquina.

O detalhe constrangedor é que eu já tinha uma rotina de limpeza agendada. Um job rodava mo clean --dry-run a cada hora e me mandava uma notificação dizendo quanto espaço poderia ser liberado. Ele cumpria o papel dele com disciplina. O problema é que um dry-run não apaga nada. A esteira rodava, o aviso chegava, e o resultado prático era zero, porque ninguém tomava a decisão de executar.

Este artigo conta como saí de 5,6 GB para 43 GB livres em uma noite, sem reinstalar o sistema e sem perder trabalho. Conta também o que deu errado no caminho, porque deu. A primeira execução real do script moveu para a Lixeira os node_modules de catorze projetos que eu estava usando. Isso está na seção sobre falhas, com o log.

A tese é simples. Manter o SSD de um laptop de desenvolvimento saudável não exige uma ferramenta mágica nem um produto comercial. Exige três camadas que conversam entre si:

1. Uma camada pronta, que cobre o que todo usuário de Mac acumula (mo clean).
2. Uma camada própria e auditável, que cobre o que só uma máquina de desenvolvimento acumula (mo_clean_full.sh).
3. Uma camada de decisão humana, alimentada por um job em background que avisa quando há algo a fazer (launchd + notificação).

Três nomes aparecem o tempo todo daqui em diante:

• Mole (mo): uma CLI open source de limpeza para macOS. O subcomando mo clean remove caches genéricos de apps e do sistema.
• launchd: o agendador nativo do macOS, que faz o papel do cron e de muito mais.
• LaunchAgent: um arquivo .plist em ~/Library/LaunchAgents que diz ao launchd o que rodar, quando, e dentro da sessão do seu usuário.

Fica de fora deste texto: ferramentas comerciais de limpeza, backup externo e qualquer promessa de portabilidade. O script usa caminhos da minha máquina e serve como referência para adaptar, não para copiar e rodar.

Tudo o que aparece aqui saiu de arquivos reais: o script, a biblioteca compartilhada, o plist do LaunchAgent e os logs de duas execuções com --apply (/tmp/apply.log e /tmp/apply2.log, de 11 de outubro de 2026). Quando um número não vem de log, eu digo de onde veio.

Diagnóstico: para onde foram os gigabytes

Antes de apagar qualquer coisa, fiz uma varredura com du -sh nos suspeitos de sempre. A tabela abaixo é a captura daquele momento:

Três linhas merecem atenção especial, porque são as que crescem sem ninguém perceber.

Worktrees de agentes de IA. Cada vez que um agente como o Codex trabalha numa tarefa isolada, ele pode abrir um git worktree: uma cópia completa do repositório, com .git, artefatos de análise, lockfiles e testes. Isso é ótimo para isolamento. O custo aparece semanas depois, quando ninguém lembra que aquelas pastas existem. Eram 30 diretórios e 13 GB. Vinte deles não eram modificados havia mais de uma semana.

~/.npm. Todo npm install alimenta o cache. Ele acelera reinstalações, só que quase ninguém limpa e ele cresce indefinidamente. Eram 7,5 GB. Esse número escondia uma surpresa que só entendi depois da segunda execução.

Simuladores iOS e Xcode. Somados, CoreSimulator, Xcode e XcodeBuildMCP passavam de 48 GB. Boa parte disso é recriável sob demanda: o Xcode baixa símbolos de novo, recompila DerivedData, recria simuladores.

Repare no padrão. O que pesa numa máquina de desenvolvimento são caches de ferramentas de desenvolvimento e artefatos de automação. Fotos, documentos e vídeos pesam pouco perto disso. Esse ponto decide qual ferramenta resolve qual parte do problema.

A solução em três camadas

Antes do código, a arquitetura:

Camada 1: mo clean

Mole é uma ferramenta de linha de comando open source para limpeza e manutenção de macOS. O subcomando mo clean varre caches de apps, logs, Lixeira, metadados do Finder, caches de navegadores, armazenamento em nuvem e apps de escritório. Uso a versão 1.26.0:

mo --version
# Mole version 1.26.0

Nas execuções registradas nos meus logs, mo clean --dry-run estimou entre 3,47 GB e 9,65 GB de espaço potencial, dependendo do dia. É um bom primeiro andar. Cobre o que eu esqueceria e faz isso com cuidado, inclusive com uma whitelist explícita. A saída mais recente mostra parte dela:

✓ Whitelist: 20 core patterns active
  → /Users/andersonlimadev/Library/Caches/ms-playwright*
  → /Users/andersonlimadev/.cache/huggingface*
  → /Users/andersonlimadev/.gradle/caches/*
  → /Users/andersonlimadev/.ollama/models/*
  → /Users/andersonlimadev/Library/Caches/pypoetry/virtualenvs*
  → /Users/andersonlimadev/Library/Caches/JetBrains*
  ...

Essa whitelist é a razão de existir da Camada 2. O Mole protege de propósito caches de ferramentas de desenvolvimento, modelos locais e ambientes virtuais, porque um produto genérico não sabe se você vai precisar deles amanhã. Ele também não conhece worktrees de agentes, não mexe em simuladores e não faz npm cache clean. Cada uma dessas escolhas é razoável para quem distribui uma ferramenta para milhares de pessoas. Na minha máquina, são justamente os maiores alvos.

Um detalhe que influenciou o desenho: mo clean tem --dry-run, mas a execução real é interativa. Não existe --apply. Por isso o meu script sempre chama o Mole em dry-run e deixa a execução real para eu rodar manualmente, olhando o que ele propõe.

Camada 2: mo_clean_full.sh

É um script bash de cerca de 920 linhas que cobre o que a Camada 1 não cobre e mantém o mesmo espírito: nada é apagado sem --apply. Ele chama o Mole como primeira categoria e segue com as outras dezoito. Esta é a numeração real do código hoje:

Os limites de idade são variáveis de ambiente (WORKTREE_STALE_DAYS, DERIVED_STALE_DAYS, DEVSUPPORT_STALE_DAYS, DIAG_STALE_DAYS, TMP_STALE_HOURS, SSD_STALE_DAYS), então dá para apertar ou afrouxar sem editar o arquivo.

A tabela tem uma história escondida. A primeira execução com --apply terminou na categoria 13: as categorias 14 a 18 ainda não existiam. Elas aparecem pela primeira vez no log da segunda execução, três horas depois. A categoria 19, do volume externo, veio depois disso. O script cresceu conforme o diagnóstico mostrava onde o espaço estava.

Camada 3: decisão humana por notificação

Um LaunchAgent roda o script a cada hora, sempre em dry-run. Ao final, o script dispara uma notificação nativa com um de três textos:

🟢 Lemon · SSD limpo     Nenhum alvo encontrado — sistema já enxuto
🟡 Lemon · SSD (DRY)     ~N alvos detectados. Rode com --apply para limpar.
🟢 Lemon · SSD limpo     ~N alvos removidos · ~X MB liberados

O terceiro texto só aparece quando eu rodo --apply. Essa é a parte que considero mais importante do desenho: a máquina detecta e avisa, e quem decide apagar sou eu. O job nunca roda --apply sozinho.

Vale também dizer o que não é automático. Desinstalar apps, mexer em ~/Movies e decidir se um worktree antigo ainda tem valor continuam sendo decisões humanas. O script lista e mede. Não decide.

O script, peça por peça

O objetivo aqui não é mostrar as 920 linhas. É mostrar as decisões que tornam o script seguro de rodar numa máquina com trabalho de verdade dentro.

Os trechos são excertos e não rodam soltos. Funções como log, ok, warn, skip, header e have são helpers de log e de verificação de comando definidos em lib/_common.sh. As dependências externas se instalam pelo Homebrew: brew install terminal-notifier e, para o Mole, o comando indicado no README do projeto.

Cabeçalho: o que o script não usa, e por quê

Quase todo guia de bash recomenda começar com set -euo pipefail. Este script começa assim:

#!/usr/bin/env bash
# mo_clean_full.sh — Limpeza profunda do SSD para o projeto lemon-scripts.

set -o pipefail
# (desabilitamos -u e -e propositalmente:
#  • bash 3.2 (default do macOS) falha em expansão de array vazio "${ARR[@]}"
#    sob set -u — inicializamos arrays no topo e usamos guards.
#  • -e abortaria a limpeza inteira caso UMA categoria falhasse (ex.: lixeira
#    não existente). Cada categoria tem `|| true` e reporta erro isoladamente.)

Os dois flags removidos têm cicatriz associada. Explico cada uma na seção de falhas. Por ora, guarde a ideia: num script de manutenção com dezenove etapas independentes, uma etapa que falha não deve derrubar as outras dezoito.

A biblioteca compartilhada

O script carrega lib/_common.sh antes de qualquer coisa. Se a lib não existir, ele para com código 127 em vez de seguir sem as proteções:

THIS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
LIB="$THIS_DIR/lib/_common.sh"

if [[ -r "$LIB" ]]; then
  source "$LIB"
else
  echo "[FATAL] lib/_common.sh não encontrada em $LIB" >&2
  exit 127
fi

A lib define o modo de execução. Dry-run é o padrão, e só --apply muda isso:

DRY_RUN=true
FORCE=false
for arg in "$@"; do
  case "$arg" in
    --apply)   DRY_RUN=false ;;
    --force)   FORCE=true ;;
    --dry-run) DRY_RUN=true ;;
  esac
done

A peça central é safe_rm. Toda remoção do script passa por ela (o script a chama de guard_path, um apelido mais legível):

safe_rm() {
  local target="$1"
  # Recusa paths perigosos (vazio, raiz, home puro, dirs de sistema)
  case "$target" in
    ""|"/"|"$HOME"|"$HOME/"|"/Users"|"/Users/"|"/System"|"/System/"*|"/Library"|"/bin"|"/usr"|"/etc"|"/var"|".."|"."|"~"|"~/")
      err "Recusando apagar path perigoso: '$target'"; return 1 ;;
  esac
  # Existe? (suporta glob)
  if [[ ! -e "$target" ]] && ! compgen -G "$target" >/dev/null 2>&1; then
    return 0
  fi
  local sz; sz=$(sizeof "$target")
  if $DRY_RUN; then
    echo -e "${YELLOW}  [DRY]${NC} apagaria: $target  ${BOLD}(${sz})${NC}"
  else
    _account "$target"
    rm -rf "$target" 2>/dev/null && echo -e "${GREEN}  [DEL]${NC} $target  ${BOLD}(${sz})${NC}" \
      || warn "não consegui apagar: $target"
  fi
}

Três propriedades importam aqui:

• Lista de recusa. Uma variável vazia ou mal expandida nunca vira rm -rf / ou rm -rf $HOME. É o clássico bug de script de limpeza, e a lista existe para ele.
• Dry-run e execução no mesmo caminho. A mesma função imprime [DRY] apagaria: ou apaga de fato. Não há dois códigos que podem divergir.
• Contabilidade. Antes de apagar, _account soma o tamanho em LEMON_FREED_KB. No final, freed_report imprime o total.

A contabilidade tem um limite que preciso registrar com honestidade: ela só mede o que passa por safe_rm. Quando o script delega para outro programa (npm cache clean, brew cleanup, xcrun simctl delete ou os scripts legados), esse espaço não entra na conta. Por isso o número do script e o número do df nunca batem.

A outra função da lib é confirm, e ela tem uma sutileza:

confirm() {
  $FORCE && return 0
  $DRY_RUN && return 1   # em dry-run nunca confirma ação real
  read -rp "$(echo -e "${YELLOW}$1${NC} [s/N] ")" _ans
  [[ "$_ans" =~ ^[sSyY]$ ]]
}

O nome engana: --force não significa "apagar de verdade". Significa "não perguntar". Quem decide se algo é apagado é --apply. As quatro combinações ficam assim:

Em dry-run sem --force, a maioria das categorias nem chega a listar o que apagaria. Com --force, a categoria entra no bloco de remoção e safe_rm imprime [DRY] apagaria:, porque DRY_RUN continua verdadeiro. Por isso o LaunchAgent roda com --dry-run --force. Parece contraditório, mas é a única combinação que produz um relatório completo sem apagar nada. A célula de baixo à direita é a perigosa, e vai aparecer de novo na seção de falhas.

Seletores: --skip e --only

Rodar dezenove categorias para testar uma só seria lento e arriscado. O script aceita dois seletores, repetíveis, nas formas --skip npm e --skip=npm:

SKIP=()
ONLY=()
i=1
while (( i <= $# )); do
  arg="${!i}"
  case "$arg" in
    --apply|--force|--dry-run) ;;              # já tratado pela lib
    --skip=*) SKIP+=("${arg#*=}") ;;
    --only=*) ONLY+=("${arg#*=}") ;;
    --skip)   (( i++ )); SKIP+=("${!i:-}") ;;
    --only)   (( i++ )); ONLY+=("${!i:-}") ;;
    *) : ;;                                    # ignora silencioso
  esac
  (( i++ ))
done

is_skipped() {
  local cat="$1"
  for s in "${SKIP[@]}"; do [[ "$s" == "$cat" ]] && return 0; done
  if (( ${#ONLY[@]} > 0 )); then
    local found=0
    for o in "${ONLY[@]}"; do [[ "$o" == "$cat" ]] && found=1; done
    (( found == 0 )) && return 0   # ONLY setado e cat não está → pula
  fi
  return 1
}

A semântica tem duas regras. SKIP é exclusão absoluta: o que está nele nunca roda. ONLY é uma lista de permissão: quando existe, tudo o que não está nela é pulado. Se uma categoria aparece nas duas, SKIP vence, porque é verificado primeiro.

Na prática, os comandos que mais uso são estes:

bash mo_clean_full.sh --force                  # relatório completo (dry-run)
bash mo_clean_full.sh --only npm --apply       # limpa só o cache do npm
bash mo_clean_full.sh --apply --force --skip playwright

O terceiro é exatamente o comando das duas execuções reais. Pulei o Playwright porque havia testes rodando naquela noite.

Worktrees órfãos: o caso que mais rendeu

if ! is_skipped worktrees; then
  header "2) Worktrees Codex órfãos (>${WORKTREE_STALE_DAYS:-7}d sem alteração)"
  WT_ROOT="$HOME/.codex/worktrees"
  if [[ ! -d "$WT_ROOT" ]]; then
    skip "diretório $WT_ROOT não existe"
  else
    WT_STALE_DAYS="${WORKTREE_STALE_DAYS:-7}"
    WT_ORPHANS=()
    while IFS= read -r d; do WT_ORPHANS+=("$d"); done < <(find "$WT_ROOT" -maxdepth 1 -mindepth 1 -type d -mtime "+$WT_STALE_DAYS" 2>/dev/null | sort)
    if (( ${#WT_ORPHANS[@]} == 0 )); then
      ok "nenhum worktree órfão encontrado"
    else
      log "Encontrados ${#WT_ORPHANS[@]} worktrees sem modificação há >${WT_STALE_DAYS}d"
      total_sz=0
      for wt in "${WT_ORPHANS[@]}"; do
        sz=$(du -sk "$wt" 2>/dev/null | awk '{print $1+0}')
        total_sz=$(( total_sz + sz ))
        log "  - $(basename "$wt")  ($(du -sh "$wt" 2>/dev/null | awk '{print $1}'))"
      done
      log "Total estimado: ~$(( total_sz / 1024 )) MB"
      if confirm "Remover ${#WT_ORPHANS[@]} worktrees orfãos?"; then
        for wt in "${WT_ORPHANS[@]}"; do guard_path "$wt"; done
        ok "Worktrees órfãos processados"
      fi
    fi
  fi
fi

A heurística é deliberadamente burra: find -mtime +7 no primeiro nível de ~/.codex/worktrees. Ela não pergunta ao git se o worktree tem commits não enviados. Aceito esse risco porque, no meu fluxo, worktree de agente é descartável por definição: o que importa vira branch e PR. Se no seu fluxo não é assim, esse é o lugar para acrescentar um git -C "$wt" status --porcelain antes de apagar.

Na primeira execução, a categoria encontrou 20 worktrees e estimou cerca de 7.102 MB. Os maiores:

[  ..  ]   - 8bf6  (1.3G)
[  ..  ]   - e69e  (1.3G)
[  ..  ]   - eea3  (1.3G)
[  ..  ]   - 5c57  (1.1G)
[  ..  ]   - 7aa0  (855M)
[  ..  ]   - adb7  (841M)
[  ..  ]   - 5150  (157M)

Sete dos vinte tinham 0 B. Eram cascas vazias de execuções que nunca chegaram a fazer checkout. Três horas depois, a segunda execução não encontrou nenhum órfão. Hoje há 9 worktrees no diretório, todos recentes.

O laço while IFS= read -r no lugar de mapfile não é estilo. É o primeiro bug da lista de falhas.

Simuladores: só os desligados

SHUTDOWN_DEVS=()
while IFS= read -r u; do
  [ -z "$u" ] && continue
  SHUTDOWN_DEVS+=("$u")
done < <(xcrun simctl list devices 2>/dev/null \
         | awk '/Shutdown/ {
             s=$0
             gsub(/[()]/," ",s)
             n=split(s, f, " ")
             for (i=1;i<n;i++) if (f[i] != "" && f[i+1]=="Shutdown") { print f[i]; break }
           }' \
         | sort -u)

xcrun simctl list devices imprime linhas como iPhone 15 Pro (UDID) (Shutdown). O awk troca parênteses por espaços, quebra a linha em campos e pega o campo imediatamente anterior a Shutdown, que é o UDID. Simuladores Booted nunca entram na lista. Na primeira execução foram 10 UDIDs removidos com xcrun simctl delete; o Xcode recria simuladores quando você pede um.

Lixeira: esvaziar o conteúdo, não a pasta

# Importante: NÃO chamamos safe_rm em ~/.Trash em si — o diretório ~/.Trash é
# "system-protected" (Finder/mavis-trash recusam removê-lo). Esvaziamos o CONTEÚDO.
if ! is_skipped trash; then
  header "11) Lixeira (~/.Trash/* + /Volumes/*/.Trashes/*)"
  TRASH_SZ=$(sizeof_safe "$HOME/.Trash")
  log "Tamanho ~/.Trash: $TRASH_SZ"
  if $DRY_RUN; then
    log "[DRY] esvaziaria conteúdo de ~/.Trash + /Volumes/*/.Trashes"
  else
    shopt -s nullglob dotglob 2>/dev/null || true
    count=0
    for item in "$HOME/.Trash"/*; do
      [ -e "$item" ] || continue
      rm -rf "$item" 2>/dev/null && count=$((count + 1))
    done
    if have sudo; then
      for vol_trash in /Volumes/*/.Trashes; do
        [ -d "$vol_trash" ] || continue
        sudo rm -rf "$vol_trash"/* 2>/dev/null || true
      done
    fi
    ok "Lixeira esvaziada ($TRASH_SZ liberados, $count itens)"
  fi
fi

Essa versão é a terceira. A primeira pedia confirmação interativa. A segunda passava o próprio ~/.Trash para safe_rm, que falhou nas duas execuções reais com a mesma mensagem:

[ WARN ] não consegui apagar: /Users/andersonlimadev/.Trash
[  OK  ] Lixeira esvaziada

Repare na segunda linha: o script reportou sucesso logo depois de falhar. Era um ok incondicional. A versão atual itera o conteúdo com nullglob e dotglob (para pegar arquivos ocultos e não quebrar com Lixeira vazia) e conta os itens de verdade. Essa falha tem um papel importante na falha 5, mais adiante.

O comentário do código cita o mavis-trash: um shim que, no ambiente de um agente de IA que eu uso, substitui rm por "mover para a Lixeira via Finder". Ele também vai importar na falha 5.

Notificação com dois caminhos

_send_notification() {
  local title="$1" body="$2" kind="${3:-ok}"
  local sender="com.lemon.scripts.mo-clean-full"
  local icon="$ICON_1X"
  [[ -r "$ICON_2X" ]] && icon="$ICON_2X"

  if command -v terminal-notifier >/dev/null 2>&1 && [[ -r "$icon" ]]; then
    if terminal-notifier \
        -title "$title" -message "$body" -sender "$sender" \
        -appIcon "$icon" -group "lemon-mo-clean-full" \
        -activate "com.apple.Terminal" >/dev/null 2>&1; then
      log "Notificação via terminal-notifier ($kind)"
      return 0
    fi
  fi
  if command -v osascript >/dev/null 2>&1; then
    local t="${title//\"/\\\"}" b="${body//\"/\\\"}"
    if osascript -e "display notification \"$b\" with title \"$t\" subtitle \"Lemon mo clean full\"" >/dev/null 2>&1; then
      log "Notificação via osascript ($kind)"
      return 0
    fi
  fi
  warn "Nenhum notificador disponível"
  return 1
}

terminal-notifier permite ícone próprio, identidade de remetente e agrupamento (-group), então uma notificação nova substitui a anterior em vez de empilhar 24 avisos por dia. Se ele não estiver instalado, osascript entrega uma notificação simples. Se nenhum funcionar, o script registra no log e segue. O log atual tem 12 notificações entregues via terminal-notifier.

Um detalhe do fallback: osascript recebe o texto dentro de uma string AppleScript. As substituições ${title//\"/\\\"} escapam aspas para que um título com " não quebre o comando.

Agendamento com launchd

No macOS, o jeito nativo de agendar trabalho de usuário é o launchd, não o cron. O job vive em ~/Library/LaunchAgents/com.lemon.scripts.mo-clean-hourly.plist. Mostro a parte que importa (o arquivo real tem comentários e um bloco de variáveis de ambiente):

<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.lemon.scripts.mo-clean-hourly</string>

    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/andersonlimadev/Projects/lemon_scripts/macos/mo_clean_full.sh</string>
        <string>--dry-run</string>
        <string>--force</string>
    </array>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/sbin:/usr/sbin:/opt/homebrew/sbin</string>
        <key>LANG</key>
        <string>en_US.UTF-8</string>
    </dict>

    <key>WorkingDirectory</key>
    <string>/Users/andersonlimadev/Projects/lemon_scripts/macos</string>

    <key>StartInterval</key>
    <integer>3600</integer>
    <key>RunAtLoad</key>
    <false/>
    <key>KeepAlive</key>
    <false/>
    <key>Nice</key>
    <integer>5</integer>
    <key>ProcessType</key>
    <string>Background</string>
    <key>LimitLoadToSessionType</key>
    <string>Aqua</string>

    <key>StandardOutPath</key>
    <string>/Users/andersonlimadev/Projects/lemon_scripts/logs/mo_clean_hourly.launchd.out</string>
    <key>StandardErrorPath</key>
    <string>/Users/andersonlimadev/Projects/lemon_scripts/logs/mo_clean_hourly.launchd.err</string>
</dict>
</plist>

Cada chave tem um motivo:

O PATH explícito merece ênfase. É o erro mais comum de quem migra um script do terminal para o launchd: no terminal tudo funciona porque o shell interativo carregou o Homebrew; no launchd o ambiente é mínimo. A documentação da Apple sobre agentes e daemons do launchd descreve essas chaves, e man launchd.plist tem a referência completa.

O ciclo completo de uma execução fica assim:

Para instalar, carregar e conferir:

cp com.lemon.scripts.mo-clean-hourly.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.lemon.scripts.mo-clean-hourly.plist
launchctl list | grep com.lemon.scripts

25258	0	com.lemon.scripts.mo-clean-hourly

A segunda coluna é o código de saída da última execução. Zero significa que a última rodada terminou bem. Em versões recentes do macOS, launchctl load e unload são considerados legados e a Apple recomenda launchctl bootstrap gui/$(id -u) <plist> e bootout. Os dois funcionam; uso load por hábito.

Por que não cron

O cron funciona no macOS, mas não sabe nada sobre sessões. Um job de cron roda fora da sessão gráfica, então a notificação, que é o ponto da Camada 3, depende de truques. O launchd resolve isso com uma chave (LimitLoadToSessionType) e ainda aplica prioridade de processo e classe de background, que o cron não conhece. Num laptop que alterna entre bateria, sono e trabalho pesado, isso faz diferença.

O que deu errado

Esta é a seção que justifica o artigo. Nenhum dos problemas abaixo foi hipotético.

1. mapfile não existe no bash do macOS

O macOS ainda vem com bash 3.2.57 em /bin/bash, por questão de licença (as versões 4 e 5 são GPLv3). Conferi na máquina:

/bin/bash --version | head -1
# GNU bash, version 3.2.57(1)-release (arm64-apple-darwin25)

mapfile (ou readarray) só existe a partir do bash 4. A primeira versão do script usava mapfile -t x < <(find ...) e quebrou com:

mo_clean_full.sh: line 169: mapfile: command not found

A correção é o laço clássico, compatível com qualquer bash:

x=()
while IFS= read -r d; do x+=("$d"); done < <(find ... | sort)

Apliquei em todos os pontos que listam diretórios: worktrees, DerivedData, DeviceSupport, simuladores, e depois nas categorias novas. Dava para instalar bash 5 pelo Homebrew e mudar o shebang. Não fiz isso porque o LaunchAgent chama /bin/bash explicitamente, e um script de manutenção não deve depender de uma ferramenta que ele mesmo pode precisar limpar.

2. set -u e o array vazio

Com set -u, o bash 3.2 trata "${ARR[@]}" de um array vazio como variável não definida, mesmo que você tenha declarado ARR=(). O erro aparece assim:

x[@]: unbound variable

Esse comportamento mudou no bash 4.4. Em 3.2, as saídas são proteger cada expansão com ${ARR[@]:-} (que injeta uma string vazia e exige cuidado nos laços) ou abrir mão do -u. Escolhi abrir mão e declarar todos os arrays globais no topo:

WT_ORPHANS=()
hits=()
OLD_DD=()
OLD_DS=()
SHUTDOWN_DEVS=()

O script ainda usa ${hits_builds[@]:-} num ponto da categoria 19, junto com um filtro que descarta a entrada vazia. É o tipo de inconsistência que aparece quando um arquivo cresce em várias sessões.

3. set -e derrubava a esteira inteira

Com set -e, qualquer comando que retorna diferente de zero encerra o script. Na primeira versão, a categoria 11 (Lixeira) passava ~/.Trash para safe_rm, a remoção falhava e o script morria ali, com exit=1, sem chegar ao resumo nem à notificação. Uma Lixeira teimosa impedia a limpeza de pip, Homebrew e Quick Look.

A correção foi remover o -e e tratar cada categoria como uma unidade isolada: cada comando externo leva || true ou um && ok || warn, e cada categoria reporta o próprio resultado. Num script de manutenção, a granularidade da falha precisa ser a categoria, não o arquivo.

4. O parser que apagaria um simulador chamado "Shutdown"

A primeira versão do parser de simuladores fazia gsub(/[()]/,"") e imprimia $NF, o último campo da linha. Só que o último campo de iPhone 15 Pro (UDID) (Shutdown) é o estado. O dry-run denunciou:

[DRY] apagaria: Shutdown

Ainda bem que era dry-run. A correção, mostrada antes, percorre os campos e pega o que vem imediatamente antes de Shutdown. É o argumento mais concreto que conheço a favor de dry-run como padrão: o bug apareceu num relatório, não num rm.

5. A delegação que moveu catorze node_modules para a Lixeira

Esse é o erro que mais me ensinou.

As categorias 12 e 13 delegam para dois scripts antigos que eu mantinha havia anos, de antes de existir a lib. Eis o clean_node_modules.sh inteiro, sem os comentários:

BASE_DIR="${1:-$HOME/Projects}"
echo "🔍 Buscando pastas node_modules em $BASE_DIR ..."
echo
find "$BASE_DIR" -type d -name "node_modules" -prune -exec rm -rf '{}' +
echo
echo "✅ Limpeza finalizada com sucesso."

Não há dry-run, idade mínima, lista de exclusão ou safe_rm. O script novo protegia a chamada com confirm e com $DRY_RUN. Só que eu rodei com --apply --force, a célula perigosa da tabela, então confirm devolveu "sim" sem perguntar, e o script legado fez exatamente o que sabia fazer. O log da primeira execução:

║ 12) node_modules (delega para clean_node_modules.sh) ║
>> MODO --apply ATIVO (alterações REAIS serão feitas).
🔍 Buscando pastas node_modules em /Users/andersonlimadev/Projects ...
mavis-trash: moved to trash: '.../lemon-code-project/lemon-code/node_modules'
mavis-trash: moved to trash: '.../lemon-code-app/omni-gateway/node_modules'
mavis-trash: moved to trash: '.../vaiterfut-app/vaidefut-web/node_modules'
mavis-trash: moved to trash: '.../vaiterfut-app/vaiterfut-mobile-app/node_modules'
mavis-trash: moved to trash: '.../vaiterfut-mobile-app/functions/node_modules'
...
✅ Limpeza finalizada com sucesso.

Foram catorze diretórios node_modules, incluindo projetos em que eu estava trabalhando naquela semana. Nenhum deles entrou na contagem de espaço liberado, porque o script legado não passa por safe_rm.

Duas coincidências evitaram o estrago. A primeira: eu estava rodando o script de dentro de uma sessão de agente cujo PATH incluía o mavis-trash, um shim que intercepta rm e move os arquivos para a Lixeira via Finder em vez de apagar. Por isso o log diz "moved to trash". A segunda: a etapa da Lixeira falhou, como vimos, então nada foi esvaziado naquela rodada. Os node_modules continuavam recuperáveis. De qualquer forma, node_modules se recria com npm install, e o prejuízo real teria sido tempo.

A categoria 13 também falhou, de outro jeito, com uma mensagem que não esclarece nada:

║ 13) Build artifacts .next/.expo/dist (delega para clean_builds.sh) ║
(eval):1: == not found

O que mudou depois disso:

• A categoria 19, escrita depois, abre com a regra em maiúsculas: JAMAIS apagar node_modules (projetos em desenvolvimento ativo). Ela usa find ... -prune em node_modules, .venv e venv, e ainda filtra o resultado uma segunda vez por padrão de path.
• Passei a rodar com --skip node_modules --skip build_artifacts até reescrever as duas categorias com idade mínima e safe_rm.

A lição vale para qualquer script que delega: as garantias do chamador não se transferem para o chamado. Um confirm na porta não protege o que acontece dentro de um programa que não conhece dry-run.

Uma observação sobre o shim, já que ele ajudou: o PATH do LaunchAgent não inclui o diretório do mavis-trash. Quando o launchd roda o script, rm é o /bin/rm de verdade. A rede de segurança que me salvou não existe no job agendado, o que reforça a decisão de o job nunca usar --apply.

6. O cache do npm que não era do npm

Na primeira execução, a categoria 4 rodou npm cache clean --force, apagou _logs (3,2 MB) e reportou "Cache do npm limpo". Três horas depois, a segunda execução encontrou ~/.npm com 7,7 GB. A conta não fechava, então medi as subpastas:

du -sh ~/.npm/* | sort -h | tail -4

 11M	/Users/andersonlimadev/.npm/_prebuilds
197M	/Users/andersonlimadev/.npm/_cacache
7.4G	/Users/andersonlimadev/.npm/_npx

Quase tudo estava em ~/.npm/_npx, o diretório onde o npx guarda os pacotes que executa. npm cache clean --force limpa _cacache, não _npx. Numa máquina onde agentes e servidores MCP rodam npx -y alguma-coisa o dia inteiro, _npx vira o maior cache do npm, e o comando oficial de limpeza não toca nele.

O script ainda não trata isso, e está na lista de próximos passos. Por enquanto, a remoção manual de ~/.npm/_npx é segura no sentido de que o npx baixa de novo o que precisar, ao custo da primeira execução seguinte ser mais lenta.

7. Mensagens que mentem um pouco

Dois problemas menores que encontrei relendo o código para este artigo, sem consequência destrutiva:

• Algumas categorias imprimem ok "... removidos" depois do laço de guard_path, mesmo em dry-run. O log de dry-run de hoje contém a linha [OK] Build artifacts de projects-ssd removidos (node_modules preservados), e nada foi removido.
• A notificação conta alvos somando só cinco arrays: worktrees, /tmp, DerivedData, DeviceSupport e simuladores. npm, Poetry, pip, Homebrew e o volume externo não entram. A mensagem "Nenhum alvo encontrado" pode aparecer com gigabytes de cache para limpar.

Nenhum dos dois apaga nada. Os dois corroem a confiança no sinal, e a Camada 3 inteira depende dessa confiança. Estão na lista.

A decisão sobre os apps

Limpar caches resolve a maior parte, mas apps instalados também ocupam espaço. Para decidir quais remover, usei o índice do Spotlight, que registra a data do último uso de cada app:

mdfind 'kMDItemLastUsedDate > $time.today(-30)'

O comando devolve os itens usados nos últimos 30 dias. Os apps fora dessa lista viram candidatos. A tabela gerada naquela noite:

A lista sugeria quase 16 GB. Removi três apps: GitHub Desktop, MongoDB Compass e iMovie. Os outros ficaram, porque "não usei em 30 dias" não significa "não vou precisar". Xcode sem registro de uso é o melhor exemplo do limite da heurística: xcodebuild e xcrun simctl usam as ferramentas do Xcode sem abrir o app, e o simulador e o DerivedData que apareceram no diagnóstico mostram que ele estava em uso.

A remoção foi feita movendo os apps para a Lixeira, o que mantém a reversão a um arraste de distância:

mavis-trash -- \
  "/Applications/GitHub Desktop.app" \
  "/Applications/MongoDB Compass.app" \
  "/Applications/iMovie.app"

Essa parte nunca vai para o script. Um job que desinstala apps sozinho com base em data de último uso é o tipo de automação que funciona até o dia em que você precisa abrir o Keynote dez minutos antes de uma apresentação.

Resultados

O que cada execução mediu por conta própria:

Os 8.830 MB da primeira execução batem com a soma dos itens que passaram por safe_rm: worktrees, /tmp, Poetry e pnpm. Simuladores, node_modules e o que o npm cache clean removeu ficam fora da conta, pelo motivo explicado na seção da biblioteca.

O df é a medida que importa, mas também não é uma soma simples. Em APFS, o espaço livre é do container compartilhado entre volumes, e "usado" mais "livre" raramente fecha com o total do disco. Itens movidos para a Lixeira continuam ocupando espaço até ela ser esvaziada. Não consigo atribuir cada gigabyte a uma categoria com precisão, e prefiro dizer isso a inventar uma decomposição.

O que dá para afirmar: saí de 5,6 GB para 43 GB livres em uma noite, sem reinstalar nada e sem perder código, e o job continua rodando de hora em hora.

O que o caso ensina

Ferramenta pronta e ferramenta própria trabalham em série. O Mole é excelente no que se propõe, e a whitelist dele é uma decisão consciente. Uma ferramenta feita para milhares de usuários precisa ser conservadora justamente com os caches de desenvolvimento, que em máquinas como a minha são a maior parte do problema. A camada própria não substitui o Mole. Ela começa onde ele decide parar.

Dry-run por padrão encontra bugs antes que eles apaguem coisas. O parser de simuladores teria tentado apagar algo chamado "Shutdown". O dry-run mostrou isso num relatório. Toda remoção passar por uma função que sabe imprimir em vez de apagar é o que permite rodar o script toda hora sem medo.

Garantias não atravessam fronteiras de processo. O episódio dos node_modules mostrou isso de forma cara. confirm e DRY_RUN protegem o código que os consulta. Um script legado chamado de dentro não herda nada disso. Se você delega, delega também a responsabilidade de verificar o que o outro lado faz.

Escreva para o bash que a máquina tem. No macOS, isso significa bash 3.2: sem mapfile, com cuidado em set -u e arrays vazios. Pedir ao usuário que instale bash 5 resolve o seu problema e cria outro para ele.

launchd entende laptops. Sessão gráfica, prioridade baixa, classe de background, PATH explícito. O cron não foi pensado para uma máquina que fecha a tampa.

A notificação é um contrato, e contratos precisam ser verdadeiros. Ícone próprio, remetente identificável, número concreto. Se o sinal disser "nenhum alvo" quando há 7 GB de _npx esperando, eu aprendo a ignorar a notificação, e a Camada 3 deixa de existir na prática.

Próximos passos

• Tratar ~/.npm/_npx como categoria própria, com idade mínima.
• Fazer a notificação contar todas as categorias, não só cinco arrays.
• Trocar os ok "... removidos" incondicionais por mensagens que dependem de DRY_RUN.
• Reescrever as categorias 12 e 13 com safe_rm e idade mínima, ou removê-las.
• Avaliar se os 54 GB de colima-home/_lima no volume externo ainda servem para alguma coisa.
• Mover ~/Movies (8,5 GB) para o volume externo.
• Trocar launchctl load por launchctl bootstrap na documentação do plist.

Arquivos de referência

Os arquivos que sustentam este artigo, para quem quiser reproduzir:

• macos/mo_clean_full.sh: o script completo (19 categorias).
• macos/lib/_common.sh: safe_rm, confirm, freed_report e o modo dry-run.
• macos/launchd/com.lemon.scripts.mo-clean-hourly.plist: o LaunchAgent.
• logs/mo_clean_full.log e logs/mo_clean_full.mole.out: a execução horária mais recente.
• /tmp/apply.log e /tmp/apply2.log: as duas execuções reais com --apply, de 11 de outubro de 2026.

Fontes externas:

• Mole (tw93/mole), a ferramenta por trás de mo clean.
• Creating Launch Daemons and Agents, documentação da Apple sobre launchd.
• terminal-notifier, notificações nativas pela linha de comando.
• man launchd.plist, man tmutil, man qlmanage e xcrun simctl help para os detalhes de cada ferramenta.