zsh-clean-history

November 7, 2025 ยท View on GitHub

Smart zsh history cleanup plugin that automatically removes typos and failed commands based on similarity analysis.

Features

  • Smart cleanup: Removes failed commands similar to successful ones
  • Typo detection: Finds rare commands similar to common variants
  • Exit code tracking: Automatically captures command success/failure
  • Configurable: Adjust similarity thresholds and behavior
  • Safe: Creates backups before cleaning

Installation

Using zplug

# Add to ~/.zshrc
zplug "automaat/zsh-clean-history", from:github, at:main

Using zinit

# Add to ~/.zshrc
zinit light automaat/zsh-clean-history

Using oh-my-zsh

# Clone to custom plugins
git clone https://github.com/automaat/zsh-clean-history \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-clean-history

# Add to plugins in ~/.zshrc
plugins=(... zsh-clean-history)

Manual

# Clone
git clone https://github.com/automaat/zsh-clean-history ~/.zsh-clean-history

# Add to ~/.zshrc
source ~/.zsh-clean-history/zsh-clean-history.plugin.zsh

Usage

Commands

  • clean-history - Run cleanup now
  • clean-history-stats - Show stats without cleaning (dry run)
  • clean-history-info - Show plugin configuration and commands

Configuration

Add before loading plugin in ~/.zshrc:

# Auto-clean on shell exit (default: false)
ZSH_CLEAN_HISTORY_AUTO_CLEAN=true

# Similarity threshold 0-1 (default: 0.8)
ZSH_CLEAN_HISTORY_SIMILARITY=0.85

# Max occurrences to consider "rare" (default: 3)
ZSH_CLEAN_HISTORY_RARE_THRESHOLD=2

# Load plugin
zplug "automaat/zsh-clean-history", from:github

Examples

# Run cleanup manually
clean-history

# Preview what would be removed
clean-history-stats

# See current configuration
clean-history-info

# Run with custom settings
clean-history --similarity 0.9 --rare-threshold 5

# Silent cleanup
clean-history --quiet

How it works

  1. Exit code tracking: Plugin captures exit codes for all commands
  2. Analysis: Python script analyzes history to find:
    • Failed commands similar to successful ones (likely typos)
    • Rare commands similar to common ones (likely misspellings)
  3. Smart removal: Removes problematic entries while preserving history

Configuration options

Environment variables

VariableDefaultDescription
ZSH_CLEAN_HISTORY_AUTO_CLEANfalseAuto-clean on shell exit
ZSH_CLEAN_HISTORY_SIMILARITY0.8Similarity threshold (0-1)
ZSH_CLEAN_HISTORY_RARE_THRESHOLD3Max count for "rare" commands

Command-line flags

  • --similarity FLOAT - Override similarity threshold
  • --rare-threshold INT - Override rare threshold
  • --dry-run - Show what would be removed without changing history
  • --quiet / -q - Minimal output

Requirements

  • zsh
  • Python 3.6+

License

MIT