dispatch-session-cleaner

dispatch-session-cleaner

A bash CLI tool that cleans up stale Dispatch session directories left behind after Claude Desktop crashes.

Problem: Dispatch sessions fail silently when stale local-agent-mode-sessions directories persist after crashes. There's no error message and no recovery path without manual filesystem cleanup. See claude-code#37473.

Usage

# Show what would be cleaned (safe preview)
./dispatch-session-cleaner.sh --dry-run

# Clean stale sessions
./dispatch-session-cleaner.sh

# Custom age threshold (default: 24 hours)
./dispatch-session-cleaner.sh --max-age 6

# Custom directory
./dispatch-session-cleaner.sh --dir /path/to/sessions

# Verbose output
./dispatch-session-cleaner.sh --verbose

How It Works

The tool scans ~/Library/Application Support/Claude/local-agent-mode-sessions for session subdirectories and marks them as stale if:

1. Dead process: The session has a .pid file and the referenced process is no longer running.
2. Age exceeded: The session directory hasn't been modified within the threshold (default 24h).
3. Broken structure: The session is missing the expected agent/ subdirectory.

Active sessions (with live processes) are never removed.

Options

Flag	Description	Default
-d, --dir DIR	Session directory path	~/Library/Application Support/Claude/local-agent-mode-sessions
-n, --dry-run	Preview without deleting	off
-a, --max-age HRS	Hours before a session is considered stale	24
-v, --verbose	Show kept sessions too	off
-h, --help	Show help	—

Environment Variables

• DISPATCH_SESSIONS_DIR — Override the default session directory path.

Validation

make test    # Syntax check (bash -n)
make lint    # ShellCheck analysis