| Name | cascade-backup-utils JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | https://github.com/dipaksaraf/cascade-backup-utils |
| 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. |
| upload_time | 2025-02-10 12:04:45 |
| maintainer | None |
| docs_url | None |
| author | Dipak Saraf |
| requires_python | >=3.8 |
| 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.
|
| keywords |
cascade
backup
windsurf
codeium
conversation
markdown
consolidation
archiving
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
pyautogui
pyperclip
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Cascade Conversation Backup Utility
[](https://github.com/dipaksaraf/cascade-backup-utils/actions/workflows/python-app.yml)
[](https://badge.fury.io/py/cascade-backup-utils)
[](https://opensource.org/licenses/MIT)
[](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.
Raw data
{
"_id": null,
"home_page": "https://github.com/dipaksaraf/cascade-backup-utils",
"name": "cascade-backup-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cascade, backup, windsurf, codeium, conversation, markdown, consolidation, archiving",
"author": "Dipak Saraf",
"author_email": "Dipak Saraf <hello@dipaksaraf.com>",
"download_url": "https://files.pythonhosted.org/packages/a4/ee/1b573ddc748cd27d26b988b1a1c9226eeec78f63fd85825f614080f44147/cascade_backup_utils-0.1.0.tar.gz",
"platform": null,
"description": "# Cascade Conversation Backup Utility\r\n\r\n[](https://github.com/dipaksaraf/cascade-backup-utils/actions/workflows/python-app.yml)\r\n[](https://badge.fury.io/py/cascade-backup-utils)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://www.python.org/downloads/)\r\n\r\nThis 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.\"\r\n\r\n## Quick Start\r\n\r\n### Installation\r\n\r\nYou can install the package directly from PyPI:\r\n\r\n```bash\r\npip install cascade-backup-utils\r\n```\r\n\r\nOr install from source:\r\n\r\n```bash\r\ngit clone https://github.com/dipaksaraf/cascade-backup-utils.git\r\ncd cascade-backup-utils\r\npip install -e .\r\n```\r\n\r\n### Basic Usage\r\n\r\nAfter installation, you can use the command-line tools:\r\n\r\n```bash\r\n# To backup a conversation:\r\ncascade-backup\r\n\r\n# To consolidate all backups:\r\ncascade-consolidate\r\n```\r\n\r\n## Why This Utility?\r\n\r\nWhen the Windsurf IDE encounters issues with large conversations, the common solutions are:\r\n\r\n1. Continuously press `Ctrl + Shift + P` (Command Palette) and select \"Developer: Reload Window.\"\r\n2. Delete the Cascade cache folder:\r\n - **Windows**: `C:\\Users\\<YOUR_USERNAME>\\.codeium\\windsurf\\cascade`\r\n - **Linux/Mac**: `~/.codeium/windsurf\\cascade`\r\n\r\nHowever, 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.\r\n\r\n## Features\r\n\r\n### Backup Features\r\n- Manual text selection and copying with retry mechanism\r\n- Automatic timestamp addition\r\n- Clipboard management and content verification\r\n- Clear user instructions and feedback\r\n- Fail-safe mechanism (move mouse to corner to abort)\r\n\r\n### Consolidation Features\r\n- Combines multiple backup files into a single conversation\r\n- Removes duplicate content automatically\r\n- Chronological sorting (newest conversations first)\r\n- Cleans up UI messages and system text\r\n- Preserves conversation context and readability\r\n\r\n## Development Setup\r\n\r\n1. Clone the repository:\r\n ```bash\r\n git clone https://github.com/dipaksaraf/cascade-backup-utils.git\r\n cd cascade-backup-utils\r\n ```\r\n\r\n2. Create a virtual environment:\r\n ```bash\r\n python -m venv venv\r\n source venv/bin/activate # On Windows use: venv\\Scripts\\activate\r\n ```\r\n\r\n3. Install development dependencies:\r\n ```bash\r\n pip install -r requirements.txt\r\n pip install -r requirements-dev.txt\r\n ```\r\n\r\n## Usage\r\n\r\n### Backing Up Conversations\r\n\r\n1. Open your Cascade conversation\r\n2. Run the backup command:\r\n ```bash\r\n cascade-backup\r\n ```\r\n3. Follow the on-screen instructions:\r\n - Clear any existing text selection\r\n - Select the conversation text you want to backup\r\n - Copy using Ctrl+C\r\n - Press Enter to continue\r\n\r\nThe script will:\r\n- Clear the clipboard before starting\r\n- Verify the content was copied successfully\r\n- Allow multiple retry attempts if needed\r\n- Save the backup with timestamp\r\n\r\n### Consolidating Backups\r\n\r\n1. Run the consolidate command:\r\n ```bash\r\n cascade-consolidate\r\n ```\r\n\r\nThe script will:\r\n- Process all backup files in the `backups` directory\r\n- Remove duplicate content\r\n- Sort conversations chronologically (newest first)\r\n- Clean up UI messages and system text\r\n- Save everything to `consolidated_conversation.md`\r\n\r\n## Advanced Usage\r\n\r\n### Custom Backup Directory\r\nBy default, backups are stored in your home directory under `.cascade_backups`. You can specify a custom directory:\r\n\r\n```bash\r\ncascade-backup --dir /path/to/backup/directory\r\n```\r\n\r\n### Consolidation Options\r\nThe consolidate command supports several options:\r\n\r\n```bash\r\n# Consolidate with custom output file\r\ncascade-consolidate --output combined_conversations.md\r\n\r\n# Keep original timestamps\r\ncascade-consolidate --preserve-timestamps\r\n\r\n# Sort by oldest first\r\ncascade-consolidate --sort ascending\r\n```\r\n\r\n## Backup Location\r\n\r\nAll files are stored in the `backups` directory:\r\n```\r\nbackups/\r\n \u251c\u2500\u2500 cascade_backup_20250209_200618.md # Individual backups\r\n \u251c\u2500\u2500 cascade_backup_20250210_001059.md\r\n \u251c\u2500\u2500 consolidated_conversation.md # Combined conversations\r\n \u2514\u2500\u2500 ...\r\n```\r\n\r\n## UI Messages Removed\r\n\r\nThe consolidation process automatically removes common UI elements and system messages:\r\n- \"DoneFeedback has been submitted\"\r\n- \"Start with History Ctrl + \u23ce\"\r\n- \"Press Enter again to interrupt and send a new message\"\r\n- Various UI mode indicators (Image, Write, Chat, etc.)\r\n- System status messages\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **Mouse Movement Issues**\r\n - Ensure no other applications are controlling the mouse\r\n - Try increasing the delay: `cascade-backup --delay 2`\r\n\r\n2. **Clipboard Problems**\r\n - Clear your clipboard before starting\r\n - Check if other applications are monitoring the clipboard\r\n\r\n3. **File Permission Errors**\r\n - Ensure you have write permissions in the backup directory\r\n - Try running with elevated privileges if necessary\r\n\r\n### Error Messages\r\n\r\n- `Failed to capture clipboard`: Clear your clipboard and try again\r\n- `Timeout waiting for selection`: Increase the timeout with `--timeout 60`\r\n- `Invalid backup file format`: Ensure the backup files haven't been modified manually\r\n\r\n## Security Considerations\r\n\r\n1. **Clipboard Security**\r\n - The utility temporarily stores conversation data in your system clipboard\r\n - Clear sensitive information from your clipboard after use\r\n\r\n2. **File Permissions**\r\n - Backup files are created with user-only read/write permissions\r\n - Consider encrypting sensitive backups\r\n\r\n3. **Data Privacy**\r\n - Review conversations before backup to exclude sensitive information\r\n - Be cautious when sharing consolidated backup files\r\n\r\n## Best Practices\r\n\r\n1. **Regular Backups**\r\n - Back up important conversations immediately\r\n - Consider scheduling regular backups\r\n\r\n2. **Backup Organization**\r\n - Use descriptive filenames\r\n - Maintain separate directories for different projects\r\n - Document the context of important conversations\r\n\r\n3. **Maintenance**\r\n - Regularly consolidate backups to save space\r\n - Archive old backups\r\n - Test backup files periodically\r\n\r\n## Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n",
"bugtrack_url": null,
"license": "MIT License\r\n \r\n Copyright (c) 2025 Dipak Saraf\r\n \r\n Permission is hereby granted, free of charge, to any person obtaining a copy\r\n of this software and associated documentation files (the \"Software\"), to deal\r\n in the Software without restriction, including without limitation the rights\r\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n copies of the Software, and to permit persons to whom the Software is\r\n furnished to do so, subject to the following conditions:\r\n \r\n The above copyright notice and this permission notice shall be included in all\r\n copies or substantial portions of the Software.\r\n \r\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n SOFTWARE.\r\n ",
"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.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/dipaksaraf/cascade-backup-utils",
"Repository": "https://github.com/dipaksaraf/cascade-backup-utils.git"
},
"split_keywords": [
"cascade",
" backup",
" windsurf",
" codeium",
" conversation",
" markdown",
" consolidation",
" archiving"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7c3785e47b6ac58d5f36c92e4fbbd59093a5dc21f0589416763039a649df1819",
"md5": "829d18d80dbd7ca12ffc5fed56dd2284",
"sha256": "6903edabe4d87441cbc864d6c390b99448d6b8f0c072ce0389c9d6b06e4e5e43"
},
"downloads": -1,
"filename": "cascade_backup_utils-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "829d18d80dbd7ca12ffc5fed56dd2284",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12373,
"upload_time": "2025-02-10T12:04:43",
"upload_time_iso_8601": "2025-02-10T12:04:43.333677Z",
"url": "https://files.pythonhosted.org/packages/7c/37/85e47b6ac58d5f36c92e4fbbd59093a5dc21f0589416763039a649df1819/cascade_backup_utils-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a4ee1b573ddc748cd27d26b988b1a1c9226eeec78f63fd85825f614080f44147",
"md5": "e21eaf88649c4df37cf963fa2456cd84",
"sha256": "a4c17b2ac4135d0fbaead8763b826eb18ffc71e651445de4e6cda18af7d1c1b5"
},
"downloads": -1,
"filename": "cascade_backup_utils-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e21eaf88649c4df37cf963fa2456cd84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14024,
"upload_time": "2025-02-10T12:04:45",
"upload_time_iso_8601": "2025-02-10T12:04:45.856767Z",
"url": "https://files.pythonhosted.org/packages/a4/ee/1b573ddc748cd27d26b988b1a1c9226eeec78f63fd85825f614080f44147/cascade_backup_utils-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-10 12:04:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dipaksaraf",
"github_project": "cascade-backup-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pyautogui",
"specs": [
[
">=",
"0.9.54"
]
]
},
{
"name": "pyperclip",
"specs": [
[
">=",
"1.8.2"
]
]
}
],
"lcname": "cascade-backup-utils"
}
