disky · research note
cli · for · agents rust duckdb mcp

ten ways to
sharpen disky
for agents.

Research note cruzando dust, gdu, ncdu, diskonaut, erdtree, duf e qdirstat — com viés agent-first: outputs determinísticos, progressive disclosure, rails contra ações destrutivas e composabilidade.

Matriz · esforço × ROI agente

quadrant chart 
quadrantChart
  title 10 ideas · agent-ROI vs effort
  x-axis "Low effort" --> "High effort"
  y-axis "Low agent ROI" --> "High agent ROI"
  quadrant-1 "Ship now"
  quadrant-2 "Plan"
  quadrant-3 "Skip"
  quadrant-4 "Quick wins"
  "1 hardlink-aware": [0.55, 0.62]
  "2 mtime filters": [0.22, 0.85]
  "3 ignore profiles": [0.50, 0.70]
  "4 --summarize scalar": [0.12, 0.78]
  "5 streaming cursor": [0.58, 0.88]
  "6 saved views": [0.28, 0.74]
  "7 plan-token apply": [0.55, 0.92]
  "8 per-volume": [0.55, 0.55]
  "9 file kind tags": [0.60, 0.72]
  "10 incremental scan": [0.85, 0.80]

Top 10 idéias

S · small M · medium L · large
01
M

Hardlink/clone-aware accounting

peer · gdu hardlink dedup · erdtree physical vs logical

O quê: tracking de inode (e APFS clones) durante scan; logical + physical bytes por arquivo, inodes compartilhados contam uma vez no snapshot.

Por que agente: ações em top/dirs hoje contam dobrado em Time Machine local snapshots, APFS clones, pnpm hardlinks. Numero ruim = decisão ruim.

Como: colunas inode, nlink, physical_size. statx/fstatat p/ st_blocks + detecção de clones. Flags --apparent vs --physical + dedup: true em stats.

02
S

Filtros de idade · --older-than

peer · gdu --since/--until · gdu --min-age/--max-age

O quê: filtros de mtime/atime em todo subcomando: --older-than 90d, --newer-than 2025-01-01, --accessed-before.

Por que agente: "acha 50 GB que ninguém tocou em 1 ano" é prompt frequente e hoje vira SQL bruto. Flag nativa aparece em disky schema e MCP — agente descobre sem precisar adivinhar.

Como: parser de duração (7d, 2h30m, 1y) + RFC3339. Predicado mtime <= ? no DuckDB. Args age_older_than/age_newer_than em MCP tools.

03
M

Ignore profiles + .gitignore/.diskyignore

peer · erdtree gitignore aware · gdu --ignore-from

O quê: honra .gitignore/.diskyignore no scan; config ~/.config/disky/config.toml com profiles nomeados (work, personal).

Por que agente: agente não threa lista de ignores em cada chamada. Profiles são reproduzíveis — agente pede --profile work.

Como: crate ignore (mesma do ripgrep/fd) dentro do jwalk callback. scan_meta guarda o set resolvido. disky config show em JSON.

04
S

--summarize · escalar puro

peer · gdu -s · dust --skip-total

O quê: disky stats --summarize imprime só {"bytes": N, "files": M} (ou inteiro cru com --raw).

Por que agente: quando agente só quer o número pra alimentar próximo passo, o envelope inteiro é overhead. Resposta escalar corta tokens e parsing.

Como: variante kind: "scalar" no envelope JSON, ou flag --raw imprimindo inteiro nu. Trivial sobre o schema atual.

05
M

Streaming NDJSON com cursor

peer · gdu --output-file JSON

O quê: disky query --stream e disky top --stream emitem NDJSON linha-a-linha conforme DuckDB rende. --cursor <id> em vez de --limit hard.

Por que agente: find de 100k linhas explode o contexto. NDJSON com cursor = progressive disclosure no protocolo. Agente puxa N, decide, pede mais.

Como: stream das rows direto via serde_json pra stdout. Sentinela final {"cursor":"<row_id>", "done":false}. MCP espelha com arg cursor e response next_cursor.

06
S

Saved views · query nomeada

peer · gdu --write-config · duf --output presets

O quê: disky view save my-cleanup "<sql>", disky view run my-cleanup --snapshot @latest, em TOML.

Por que agente: agentes convergem nas mesmas queries. Dar nome transforma SQL frágil em API estável — disky schema enumera, outros agentes descobrem.

Como: views em ~/.config/disky/views.toml com nome, sql template, params. schema inclui array views. MCP expõe disky_view_run(name, args).

07
M

Plan-token apply · commit transactional

peer · gdu --no-delete · ncdu confirm-on-delete

O quê: disky cleanup --plan imprime plano JSON com plan_id (hash de paths+sizes+mtimes). --apply --plan-id <id> é o único caminho pra deletar. Hash mismatch = recusa.

Por que agente: entre LLM ver dry-run e aprovar --apply, FS pode ter mudado. Plan token converte "show then do" em 2-step transacional, difícil de usar errado.

Como: hash de (path,size,mtime,inode) em digest estável. Persiste em ~/Library/.../disky/plans/<id>.json com TTL. Recusa --apply se qualquer stat diverge.

08
M

Per-volume · envelope tipo df

peer · duf filesystem table · gdu -d --no-cross

O quê: disky volumes (ou --per-volume em stats) listando cada mount {mountpoint, fstype, total, used, avail, scanned_bytes}. --one-filesystem em scan.

Por que agente: "por que disco cheio?" pede contexto de df junto. Sem isso agente shella e merga na mão. --one-filesystem evita agente acidentalmente crawlear /Volumes/TimeMachine.

Como: statfs/getmntinfo no macOS. Cross-ref de path roots c/ mount points; cada row de files ganha volume_id. Flag --one-filesystem tipo erdtree -x.

09
M

Classificação semântica · kind além da extensão

peer · qdirstat MIME-category tree

O quê: tag por categoria no scan (code, media, archive, build-artifact, cache, vcs, container-image, model-weights).

Por que agente: extensão sozinha é fraca (sem ext, ou .bin). Categorias deixam agente perguntar "biggest non-essential" ou "purge caches" com precisão semântica. cleanup propõe por categoria, não só dir-name hardcoded.

Como: ruleset TOML (globs + ext + magic-bytes pros top 50). Coluna category. --category model-weights em qualquer lugar. cleanup --target caches agrega .cache, .npm, .yarn/cache, HuggingFace, pip cache.

10
L

Scan incremental · delta por mtime

peer · gdu -r read-from-storage · gdu --db

O quê: disky scan --incremental --base @latest <path> re-walka mas pula subtrees cujo dir mtime ≤ mtime registrado no snapshot. Merge dos deltas vira snapshot novo.

Por que agente: rescaneando / semanal pra loop de monitor é desperdício. Incremental + bundled --emit-top = agente roda check semanal sub-segundo. disky diff vira quase-realtime.

Como: persistir dir mtimes junto das rows (parcialmente presente). Walker checa parent mtime antes de descer; subtrees inalterados copiam rows via INSERT … SELECT. Grava incremental_base em scan_meta p/ provenance no diff.

Fluxo agente · idéias combinadas

Como 2 + 5 + 7 + 10 viram um loop de cleanup seguro e incremental.

flowchart LR
  S["scan --incremental
--base @latest
idea 10"] --> D["disky diff
old → new"]
  D --> Q["top --older-than 180d
--category cache
idea 2 + 9"]
  Q --> P["cleanup --plan
→ plan_id sha256
idea 7"]
  P --> R{"agent reviews
plan JSON"}
  R -->|approve| A["cleanup --apply
--plan-id sha256
--reversible"]
  R -->|reject| X["discard"]
  A --> M["stats --summarize
idea 4"]
  M --> S

Peer scan notes

7 repos · features destacadas
bootandy/dust · Rust ▸
  • Tree com bars de %
  • --collapse nomeados (folda node_modules)
  • -j JSON output
  • Regex include/exclude (-e/-v)
  • -z min-size filter
  • Screen-reader mode
  • Hardlink awareness
  • --files-from/--files0-from pra paths piped
dundee/gdu · Go ▸
  • --db SQLite/Badger + -r reuse
  • --max-age/--min-age/--since/--until
  • -i/-I/-X ignore lists
  • -o JSON export + -f re-import
  • --no-cross, --no-delete safety toggles
  • YAML config + --write-config
  • Hardlink dedup, archive browsing
rofl0r/ncdu · C ▸
  • Classic curses TUI
  • JSON export/import canonical — outras ferramentas consomem dumps ncdu
  • Confirm-on-delete
imsnif/diskonaut · Rust ▸
  • Treemap visualization
  • Scan-while-browse (incremental UI)
  • Session freed-bytes tracker
solidiquis/erdtree · Rust ▸
  • Physical vs logical vs blocks vs word/line metrics
  • .gitignore aware default
  • Layouts: regular/inverted/flat
  • Glob+regex c/ file-type restriction
  • Long view com perms/owner/inode/nlink
  • Sort por ctime/atime/mtime
  • -x one-filesystem
muesli/duf · Go ▸
  • FS/mount table com usage/inodes
  • --only/--hide group filters
  • --output column selection
  • Thresholds configuráveis pra cor
  • --json da tabela inteira
shundhammer/qdirstat · C++/Qt ▸
  • MIME-category tree ("Pictures", "Videos", "Archives") — base da idéia 9
  • Cleanup actions configuráveis
  • File-age histogram
  • Treemap

Eixos de viés agent-first

determinismo

Plan-token (7) + incremental base (10) garantem que dois agentes vendo o mesmo snapshot tomam a mesma decisão.

progressive disclosure

Cursor streaming (5) + scalar summarize (4) deixam agente puxar só o que precisa, sem queimar contexto.

descoberta via schema

Saved views (6) + ignore profiles (3) + filtros nativos (2,9) aparecem em disky schema, eliminando prompt-engineering.

safety rails

Plan-token (7) + reversible trash (já existe) + one-filesystem (8) tornam ação destrutiva difícil de errar.

precisão

Hardlink/clone-aware (1) + per-volume (8) corrigem contagem dobrada — números bons = decisões boas.

composabilidade

NDJSON streaming (5) + scalar (4) + saved views (6) compõem em pipes Unix — agente encadeia sem glue code.