organvm-iv-taxis shell-history-hygiene — Shell-History Audit + Targeted Cleanup
When to invoke
- User explicitly asks to audit / clean / dedup / prune their shell history (atuin or otherwise)
- User pasted an ad-hoc
atuin stats / prune / dedupone-liner and asked for review or improvement - Before any history-store migration (atuin → atuin v2, zsh-only → atuin, etc.) where you want a clean baseline
- During machine-setup audits where the history corpus is being inspected for size or quality
Backends
- atuin (current):
atuin stats today,atuin history prune,atuin history dedup - zsh native (future):
.zsh_historyline dedup, size limits - bash native (future):
.bash_historyline dedup - mcfly (future): mcfly's own pruning
This skill currently ships the atuin backend at scripts/atuin-audit.sh. Add sibling scripts under scripts/ as backends are added.
How it works (preview-then-apply)
The audit is dry-run only. It produces three things:
- A headline summary on the terminal —
atuin stats today+ counts. - Two dated preview artifacts on disk — one per operation (prune, dedup) — for human inspection.
- Echoed apply commands at the end — copy/paste shapes that the human runs manually.
The skill never runs the apply commands itself. Separation of audit from apply is deliberate — it's the kill-switch against accidental history destruction.
Running the audit
${CLAUDE_SKILL_ROOT}/scripts/atuin-audit.sh # dedup --before defaults to today
${CLAUDE_SKILL_ROOT}/scripts/atuin-audit.sh 2026-05-01 # dedup --before <date>
If ${CLAUDE_SKILL_ROOT} isn't resolved by the harness, use the absolute path:
/Users/4jp/Code/organvm/a-i--skills/skills/tools/shell-history-hygiene/scripts/atuin-audit.sh
Preview artifacts land alongside the script:
atuin-prune-preview-YYYY-MM-DD.txtatuin-dedup-preview-YYYY-MM-DD.txt
Dated filenames preserve a trail — re-runs don't clobber prior previews.
Interpreting output
| Headline | Meaning |
|---|---|
prune entries: N |
atuin's own "Found N entries to prune" — structural no-ops (empty commands, repeated clear, paste-glitch duplicates). Almost always safe to prune. |
dedup duplicates: M |
atuin's own "Found M duplicates to delete" — exact-string repeats older than --before. Inspect a sample before applying; large M (10K+) is normal across months of history. |
(N lines in preview, multi-line commands expand) |
The preview file may have more lines than the entity count because multi-line commands (HEREDOCs, for loops) take multiple lines each. Trust the headline number, use the line count for file-size context. |
Applying the cleanup
After the human eyeballs the preview and approves:
atuin history prune # apply prune
atuin history dedup --before "$BEFORE_DATE" --dupkeep 1 # apply dedup (keep 1 copy per duplicate string)
Run in that order. Prune first removes the structural no-ops; dedup then collapses the remaining exact-string repeats. Reverse order works but does redundant scanning.
--dupkeep 0 is destructive (removes ALL copies). Never recommend it — --dupkeep 1 is the right default.
Safety / failure modes
- Script preserves dry-run guarantee —
set -euo pipefail, never invokes apply commands. atuinnot on PATH — script exits 1 with clear error. No partial action.- Multi-line commands in atuin — the script's headline parses atuin's own "Found N" lines (not
wc -l) so the count is accurate even when multi-line commands inflate the line total. --beforedate in the future — atuin accepts it; dedup just considers all history. Inspect preview before applying.
Heritage / why this skill exists
Triggered by a 2026-05-21 review of an ad-hoc one-liner that had a tee cmd > file.txt bug — wrote two files, swallowed dedup output. The fix evolved into a dated-preview script, then into this skill so the workflow lives somewhere discoverable rather than as scratch material under ~/_dot-config/scratch/. Per Rule #34 ("merge into ideal form") the function clarified beyond scratch/'s purpose, so it migrated here.
Original artifact birthplace: ~/_dot-config/scratch/atuin-audit.sh (worktree commit 6d6ef39 on _dot-config main). This skill's scripts/atuin-audit.sh is the canonical-from-here copy.