Metadata-Version: 2.2
Name: cascade-backup-utils
Version: 0.1.0
Summary: A utility to backup and consolidate Cascade AI conversations from the Windsurf IDE. Prevents data loss by safely storing conversations as markdown files and provides tools to manage and consolidate multiple backups efficiently.
Home-page: https://github.com/dipaksaraf/cascade-backup-utils
Author: Dipak Saraf
Author-email: Dipak Saraf <hello@dipaksaraf.com>
License: MIT License
        
        Copyright (c) 2025 Dipak Saraf
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/dipaksaraf/cascade-backup-utils
Project-URL: Repository, https://github.com/dipaksaraf/cascade-backup-utils.git
Keywords: cascade,backup,windsurf,codeium,conversation,markdown,consolidation,archiving
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyautogui
Requires-Dist: pyperclip

# Cascade Conversation Backup Utility

[![Python CI](https://github.com/dipaksaraf/cascade-backup-utils/actions/workflows/python-app.yml/badge.svg)](https://github.com/dipaksaraf/cascade-backup-utils/actions/workflows/python-app.yml)
[![PyPI version](https://badge.fury.io/py/cascade-backup-utils.svg)](https://badge.fury.io/py/cascade-backup-utils)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

This utility helps you back up and consolidate your Cascade conversations from the Windsurf IDE as markdown files. It may also work with other AI coding platforms, though this has not been tested. Backing up conversations from AI coding sessions is crucial, especially as AI models can sometimes produce unexpected results. In particular, when using Windsurf, large conversations can lead to issues such as the IDE failing to start with the message "windsurf failed to start."

## Quick Start

### Installation

You can install the package directly from PyPI:

```bash
pip install cascade-backup-utils
```

Or install from source:

```bash
git clone https://github.com/dipaksaraf/cascade-backup-utils.git
cd cascade-backup-utils
pip install -e .
```

### Basic Usage

After installation, you can use the command-line tools:

```bash
# To backup a conversation:
cascade-backup

# To consolidate all backups:
cascade-consolidate
```

## Why This Utility?

When the Windsurf IDE encounters issues with large conversations, the common solutions are:

1. Continuously press `Ctrl + Shift + P` (Command Palette) and select "Developer: Reload Window."
2. Delete the Cascade cache folder:
   - **Windows**: `C:\Users\<YOUR_USERNAME>\.codeium\windsurf\cascade`
   - **Linux/Mac**: `~/.codeium/windsurf\cascade`

However, deleting the cache folder will remove your conversation history. This utility ensures your valuable conversations are preserved and accessible even if you need to clear the cache.

## Features

### Backup Features
- Manual text selection and copying with retry mechanism
- Automatic timestamp addition
- Clipboard management and content verification
- Clear user instructions and feedback
- Fail-safe mechanism (move mouse to corner to abort)

### Consolidation Features
- Combines multiple backup files into a single conversation
- Removes duplicate content automatically
- Chronological sorting (newest conversations first)
- Cleans up UI messages and system text
- Preserves conversation context and readability

## Development Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/dipaksaraf/cascade-backup-utils.git
   cd cascade-backup-utils
   ```

2. Create a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows use: venv\Scripts\activate
   ```

3. Install development dependencies:
   ```bash
   pip install -r requirements.txt
   pip install -r requirements-dev.txt
   ```

## Usage

### Backing Up Conversations

1. Open your Cascade conversation
2. Run the backup command:
   ```bash
   cascade-backup
   ```
3. Follow the on-screen instructions:
   - Clear any existing text selection
   - Select the conversation text you want to backup
   - Copy using Ctrl+C
   - Press Enter to continue

The script will:
- Clear the clipboard before starting
- Verify the content was copied successfully
- Allow multiple retry attempts if needed
- Save the backup with timestamp

### Consolidating Backups

1. Run the consolidate command:
   ```bash
   cascade-consolidate
   ```

The script will:
- Process all backup files in the `backups` directory
- Remove duplicate content
- Sort conversations chronologically (newest first)
- Clean up UI messages and system text
- Save everything to `consolidated_conversation.md`

## Advanced Usage

### Custom Backup Directory
By default, backups are stored in your home directory under `.cascade_backups`. You can specify a custom directory:

```bash
cascade-backup --dir /path/to/backup/directory
```

### Consolidation Options
The consolidate command supports several options:

```bash
# Consolidate with custom output file
cascade-consolidate --output combined_conversations.md

# Keep original timestamps
cascade-consolidate --preserve-timestamps

# Sort by oldest first
cascade-consolidate --sort ascending
```

## Backup Location

All files are stored in the `backups` directory:
```
backups/
  ├── cascade_backup_20250209_200618.md  # Individual backups
  ├── cascade_backup_20250210_001059.md
  ├── consolidated_conversation.md        # Combined conversations
  └── ...
```

## UI Messages Removed

The consolidation process automatically removes common UI elements and system messages:
- "DoneFeedback has been submitted"
- "Start with History Ctrl + ⏎"
- "Press Enter again to interrupt and send a new message"
- Various UI mode indicators (Image, Write, Chat, etc.)
- System status messages

## Troubleshooting

### Common Issues

1. **Mouse Movement Issues**
   - Ensure no other applications are controlling the mouse
   - Try increasing the delay: `cascade-backup --delay 2`

2. **Clipboard Problems**
   - Clear your clipboard before starting
   - Check if other applications are monitoring the clipboard

3. **File Permission Errors**
   - Ensure you have write permissions in the backup directory
   - Try running with elevated privileges if necessary

### Error Messages

- `Failed to capture clipboard`: Clear your clipboard and try again
- `Timeout waiting for selection`: Increase the timeout with `--timeout 60`
- `Invalid backup file format`: Ensure the backup files haven't been modified manually

## Security Considerations

1. **Clipboard Security**
   - The utility temporarily stores conversation data in your system clipboard
   - Clear sensitive information from your clipboard after use

2. **File Permissions**
   - Backup files are created with user-only read/write permissions
   - Consider encrypting sensitive backups

3. **Data Privacy**
   - Review conversations before backup to exclude sensitive information
   - Be cautious when sharing consolidated backup files

## Best Practices

1. **Regular Backups**
   - Back up important conversations immediately
   - Consider scheduling regular backups

2. **Backup Organization**
   - Use descriptive filenames
   - Maintain separate directories for different projects
   - Document the context of important conversations

3. **Maintenance**
   - Regularly consolidate backups to save space
   - Archive old backups
   - Test backup files periodically

## Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
