zsh-scratch-manager

A zsh plugin for creating temporary scratch directories with automatic cleanup.

Add a keybinding:

# .zshrc
bindkey '^[o' scratch-find-or-create-widget   # Alt-o: open existing or create new

$ # press Alt+O
~/scratch/tmp.x2Lm
$ # reopen it later, or choose + new scratch from the picker

Add an alias:

# .zshrc
alias t='scratch'

$ t myproject
~/scratch/myproject.x2Lm

Installation

zinit

zinit light cosgroveb/zsh-scratch-manager

antibody

antibody bundle cosgroveb/zsh-scratch-manager

sheldon

[plugins.scratch-manager]
github = "cosgroveb/zsh-scratch-manager"

oh-my-zsh

git clone https://github.com/cosgroveb/zsh-scratch-manager \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/scratch-manager

Then add scratch-manager to your plugins in .zshrc.

Direct sourcing

source /path/to/zsh-scratch-manager/scratch-manager.plugin.zsh

Usage

scratch [prefix]         # Create ~/scratch/<prefix>.XXXX and cd into it
scratch -t [prefix]      # Create in /tmp (volatile, cleared on reboot)
scratch -l, --list       # List existing scratch directories
scratch -c, --cleanup    # Run cleanup now
scratch --pick           # Pick an existing scratch directory and print its path
sff                      # Convenience wrapper for scratch --pick
sfp                      # Pick an existing scratch directory and pushd into it
scratch-find-or-create   # Optional helper: pick an existing scratch or create a new one, then pushd
scratch --help           # Show help

Configuration

Set these environment variables before loading the plugin:

export SCRATCH_DIR=~/scratch           # Where scratches are created
export SCRATCH_CLEANUP_PERIOD=3600     # Cleanup check interval (seconds)
export SCRATCH_CLEANUP_AGE=3600        # Min age before cleanup (seconds)
export SCRATCH_DEFAULT_PREFIX=tmp      # Default prefix when none given

# Hidden files/dirs ignored during cleanup (default shown)
SCRATCH_IGNORE_HIDDEN=(.local .config .cache .npm .yarn .pnpm .claude)

Aliases and Key Bindings

Add to your .zshrc after loading the plugin:

alias t='scratch'
alias tt='scratch -t'
bindkey '^[o' scratch-find-or-create-widget   # Alt-o: open existing or create new
bindkey '^G' scratch-widget                   # Ctrl+G: always create a fresh scratch

If fzf is installed, scratch --pick uses it for interactive selection. If lsd is installed, the picker preview shows a tree view of the highlighted scratch directory. The picker sorts newest-first and also matches shallow file and path names inside each scratch directory, so you can type Gemfile, notes, or src/app even when every scratch name is tmp.*.

Auto-Cleanup

Abandoned scratch directories are cleaned up automatically in the background.

A directory is removed when ALL of these are true:

1. No visible files (empty or only hidden tool dirs)
2. No .git directory
3. No shell has it as current working directory
4. Older than SCRATCH_CLEANUP_AGE

Features

• Random suffixes to avoid collisions
• Optional /tmp location for volatile scratch dirs
• Auto-cleanup of abandoned directories
• Tab completion
• Works with zinit, antibody, sheldon, oh-my-zsh, or direct sourcing

Inspiration

Inspired by jtm's comment on Lobste.rs.

License

MIT