About

Imported from organvm-iv-taxis/a-i--skills (skills/tools/shell-history-hygiene/SKILL.md). Install upstream with npx skills add organvm-iv-taxis/a-i--skills --skill shell-history-hygiene. Copyright stays with the author (MIT).

shell-history-hygiene — Shell-History Audit + Targeted Cleanup

Name: shell-history-hygiene
Author: organvm-iv-taxis

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 / dedup one-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_history line dedup, size limits
bash native (future): .bash_history line 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.txt
atuin-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.
atuin not 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.
--before date 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.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/organvm-iv-taxis-a-i-skills-shell-history-hygiene/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

organvm-iv-taxis-a-i-skills-shell-history-hygiene.ocm.jsonjson

{
  "ocm": "1",
  "id": "organvm-iv-taxis-a-i-skills-shell-history-hygiene",
  "kind": "skill",
  "name": "shell-history-hygiene",
  "description": "Dry-run audit + targeted cleanup for shell command history. Currently wraps atuin (stats today, prune, dedup with dated preview artifacts); extensible to zsh/bash/mcfly backends. Always previews before applying — apply commands are echoed for the human to run, never auto-executed. Triggers on \"/shell-history-hygiene\", \"audit atuin\", \"audit shell history\", \"clean shell history\", \"atuin prune\", \"atuin dedup\", \"shell history hygiene\", \"history cleanup\". Replaces ad-hoc one-liners (e.g. `... | tee cmd > file.txt` which wrote two files, swallowed dedup output, and left a junk `cmd` file).",
  "publisher": "organvm-iv-taxis",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "shell",
      "history",
      "atuin",
      "hygiene",
      "audit",
      "dry-run",
      "preview-then-apply",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Dry-run audit + targeted cleanup for shell command history. Currently wraps atuin (stats today, prune, dedup with dated preview artifacts); extensible to zsh/bash/mcfly backends. Always previews before applying — apply commands are echoed for the human to run, never auto-executed. Triggers on \"/shell-history-hygiene\", \"audit atuin\", \"audit shell history\", \"clean shell history\", \"atuin prune\", \"atuin dedup\", \"shell history hygiene\", \"history cleanup\". Replaces ad-hoc one-liners (e.g. `... | tee cmd > file.txt` which wrote two files, swallowed dedup output, and left a junk `cmd` file)."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/organvm-iv-taxis/a-i--skills",
      "path": "skills/tools/shell-history-hygiene/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/organvm-iv-taxis/a-i--skills/blob/HEAD/skills/tools/shell-history-hygiene/SKILL.md",
      "key": "organvm-iv-taxis/a-i--skills/skills/tools/shell-history-hygiene/SKILL.md"
    },
    "license": "MIT"
  },
  "instructions": "# shell-history-hygiene — Shell-History Audit + Targeted Cleanup\n\n## When to invoke\n\n- User explicitly asks to audit / clean / dedup / prune their shell history (atuin or otherwise)\n- User pasted an ad-hoc `atuin stats / prune / dedup` one-liner and asked for review or improvement\n- Before any history-store migration (atuin → atuin v2, zsh-only → atuin, etc.) where you want a clean baseline\n- During machine-setup audits where the history corpus is being inspected for size or quality\n\n## Backends\n\n- **atuin** (current): `atuin stats today`, `atuin history prune`, `atuin history dedup`\n- **zsh n",
  "cost": {
    "context_tokens": 1099
  }
}

Fetch it by URL: GET /api/v1/registry/organvm-iv-taxis-a-i-skills-shell-history-hygiene/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.