atuin-history-cleanup

name	atuin-history-cleanup
description	Use when auditing Atuin shell history for noisy duplicates or high-confidence typo/retry pairs and when preparing safe preview-first cleanup steps without editing the SQLite database directly.

Atuin History Cleanup

Overview

Audit first, delete second. Use the bundled script to summarize duplicate pressure and high-confidence typo-like retries. For typo cleanup, prefer the transactional cleanup-typos command so the flow snapshots history.db, uploads the current host history store, deletes candidates, verifies the result, and rolls back automatically if verification fails.

Read references/atuin-cli.md when you need the exact delete, dedup, or prune behavior.

Use When

• Reviewing a noisy Atuin history.db before removing anything.
• Estimating how much atuin history dedup would remove while still keeping the newest repeated entries.
• Looking for typo-like retries such as gti status followed by git status.
• Running a transactional typo cleanup with backup, verification, and rollback.
• Rechecking an Atuin cleanup plan without mutating the database directly.

Guardrails

• Always run atuin info and the audit script before any destructive step.
• Treat duplicate cleanup as global. atuin history dedup is not a single-command delete tool.
• atuin search --delete is query-wide and follows Atuin's active search semantics. Do not use it manually for typo cleanup.
• cleanup-typos is the only approved automation path for typo deletion. It may use atuin search --delete only after a strict uniqueness gate; any ambiguous match must fall back to the interactive inspector path.
• cleanup-typos must snapshot history.db before deletion and delay the final remote sync until verification passes.
• Rollback is whole-database restore, not selective row restore.
• Re-confirm every destructive command immediately before running it.
• Do not delete rows directly from SQLite.
• Do not edit Atuin config as part of this skill. history_filter and cwd_filter tuning is out of scope for v1.

Workflow

1. Resolve the active database:

atuin info

2. Run the audit:

uv run python skills/atuin-history-cleanup/scripts/atuin_history_cleanup.py audit

Useful flags:

uv run python skills/atuin-history-cleanup/scripts/atuin_history_cleanup.py audit --db-path ~/.local/share/atuin/history.db --dupkeep 3 --before now --typo-window-seconds 300 --max-typos 20

3. Review the duplicates section first. Use the reported atuin history dedup --dry-run ... command. If the dry run matches expectations, rerun the same command without --dry-run.

4. Review the typos section second and choose one path: Preferred transactional path:

uv run python skills/atuin-history-cleanup/scripts/atuin_history_cleanup.py cleanup-typos

Useful flags:

uv run python skills/atuin-history-cleanup/scripts/atuin_history_cleanup.py cleanup-typos --db-path ~/.local/share/atuin/history.db --before now --typo-window-seconds 300 --max-typos 20 --backup-dir ~/.local/share/atuin/cleanup-backups/manual-run

Manual review path: Start with the suggested atuin search -i --search-mode prefix ... preview command. The audit will also add --cwd <cwd> when it knows the original working directory, so review stays narrow even if your default Atuin config uses skim or another fuzzy mode. In the TUI inspector, use Ctrl+O, confirm the exact entry, then Ctrl+D to delete that one row.

5. Stop after the cleanup you actually verified. Do not keep expanding the scope.

What The Audit Does

• Resolves the database path from atuin info unless --db-path is provided.
• Opens the SQLite database in read-only mode and inspects only id, timestamp, exit, command, cwd, session, and hostname.
• Groups duplicates by (command, cwd, hostname) and reports how many rows exceed --dupkeep.
• Emits typo review commands with an explicit --search-mode prefix override and never emits atuin search --delete.
• cleanup-typos first runs the same typo audit, then creates a snapshot, writes pre_audit.json, plan.json, and post_verify.json, and only commits the deletion to remote sync after verification succeeds.
• Detects typo candidates only when all of these are true:
  • same session
  • within the configured window
  • arguments after the first token are identical
  • previous command exited non-zero
  • the first token looks rare
  • the corrected token is much more common
  • the token change is a single-edit or adjacent-transposition typo
• Excludes path- or script-like first tokens from typo suggestions.

Output Expectations

• duplicates gives one global preview/apply pair for history dedup.
• typos gives per-row review data: id, time, cwd, original command, suggested correction, reason, and shell-safe preview commands for inspector review only.
• --format json is preferable when another tool needs to post-process the audit.
• cleanup-typos prints a text summary and leaves its backup and verification artifacts in the chosen backup directory.