shell-history-hygiene
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).
Best use case
shell-history-hygiene is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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).
Teams using shell-history-hygiene should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/shell-history-hygiene/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How shell-history-hygiene Compares
| Feature / Agent | shell-history-hygiene | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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).
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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 / 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:
1. A headline summary on the terminal — `atuin stats today` + counts.
2. Two dated preview artifacts on disk — one per operation (prune, dedup) — for human inspection.
3. 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
```bash
${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:
```bash
/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:
```bash
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.Related Skills
taxonomy-modeling-design
Phase 2 of the pentaphase structural-overhaul protocol. Classifies entities, standardizes attributes, establishes relationships, and designs the access framework. Use when the user invokes phase 2 of an overhaul, asks to "design the taxonomy" or "model the structure", or has completed a landscape audit and is ready to redesign. Consumes phase-1-landscape-report.md; produces phase-2-taxonomy-model.md.
systemic-ingestion-normalization
Phase 4 of the pentaphase structural-overhaul protocol. Purges redundancies, enriches and aligns legacy entities to the new schema, executes phased ingestion into the new environment, and audits integrity. Use when the user invokes phase 4 of an overhaul, asks to "migrate the data" or "ingest into the new system", or has a configured environment ready to accept legacy entities. Consumes phase-3-environment-spec.md; produces phase-4-ingestion-report.md.
system-environment-configuration
Phase 3 of the pentaphase structural-overhaul protocol. Translates the taxonomy model into objective technical criteria, evaluates candidate mechanisms or frameworks, instantiates the chosen architecture, and programs validation rules. Use when the user invokes phase 3 of an overhaul, asks to "select a system" or "configure the environment", or has a taxonomy model and is ready to choose technology. Consumes phase-2-taxonomy-model.md; produces phase-3-environment-spec.md.
pentaphase-orchestrator
Threads the full five-phase structural-overhaul protocol — landscape discovery, taxonomy design, environment configuration, systemic ingestion, governance evolution — for any substrate the user names. Use when the user requests a structural overhaul, system redesign, or end-to-end restructuring of a documentation system, asset registry, code monorepo, knowledge base, or operational workflow; or when they explicitly invoke the pentaphase methodology. Coordinates handoffs between phase-skills and seats validation gates between phases.
landscape-discovery-audit
Phase 1 of the pentaphase structural-overhaul protocol. Inventories assets, maps current flow, identifies friction, and defines value metrics for any substrate. Use when the user invokes phase 1 of an overhaul, requests a baseline audit, asks to "discover the landscape" of a system, or wants to understand current state before redesigning. Produces phase-1-landscape-report.md.
governance-evolution-protocol
Phase 5 of the pentaphase structural-overhaul protocol. Codifies operational protocols, onboards the ecosystem of participants, programs behavior monitoring, and establishes an iteration cadence so the substrate evolves rather than calcifies. Use when the user invokes phase 5 of an overhaul, asks to "establish governance" or "lock in the protocols", or has completed ingestion and is ready to declare the substrate operational. Consumes phase-4-ingestion-report.md; produces phase-5-governance-charter.md, which closes the protocol.
dimension-surfacing
Surfaces the parallel domain dimensions implicit in a dense or minimal prompt. Use when a user prompt is small on the surface but plainly implies multiple independent domains needing different expertise; when explicitly invoked by the coliseum-orchestrator skill as Phase 1; or when the user asks "what dimensions does this prompt encode" or "what axes does this break into." Produces a named dimension set where each dimension is independently executable and not a paraphrase of another.
coliseum-dispatch
Dispatches a composed set of assignment envelopes to domain-expert subagents in parallel, in a single message with multiple Agent tool calls. Enforces the no-pingpong gate via the pingpong-detector agent before any dispatch fires. Use when invoked by the coliseum-orchestrator as Phase 3; when envelopes are already composed and the next step is parallel execution; or when the user asks to "fan out" or "dispatch in parallel." Produces a dispatch log capturing what was sent, when, and where returns land.
assignment-composition
Wraps each surfaced dimension as a self-contained 9-section autonomous-work-assignment envelope — scope, context, success criteria, allowed tools, return format, handoff — all the recipient subagent needs to execute without coming back. Use when invoked by coliseum-orchestrator as Phase 2; when dimensions are named and the next step is to make each independently dispatchable; or when the user asks "compose this as an assignment." The no-pingpong gate validates each envelope before dispatch.
workspace-autopsy-governance
Conducts a full automated autopsy of the current workspace directory to map files, identifies structural issues, proposes a restructuring plan (the signal), and establishes unified governance using templates. Use this skill when a user asks to map, restructure, reorganize, or apply new governance to an existing messy repository.
workshop-presentation-design
Design engaging workshops, conference talks, and educational presentations. Covers learning objectives, activity design, slide craft, and facilitation techniques. Triggers on workshop design, presentation prep, talk structure, or training session requests.
webhook-integration-patterns
Designs reliable webhook systems with proper delivery guarantees, retry logic, signature verification, and idempotent processing for event-driven integrations.