Skip to content

README.md

Latest commit

 

History

History
55 lines (37 loc) · 1.86 KB

README.md

File metadata and controls

55 lines (37 loc) · 1.86 KB

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